Profile Groups API Reference

Profile Groups are organizational containers that group related social media profiles together. For example, you might have separate profile groups for different brands, clients, or projects.

Note

All calls require authentication.

Endpoints

Method	Endpoint	Description
GET	/api/profile_groups	List all profile groups
GET	/api/profile_groups/:id	Get a single profile group
POST	/api/profile_groups	Create a new profile group
DELETE	/api/profile_groups/:id	Delete a profile group
POST	/api/profile_groups/:id/initialize_connection	Get OAuth URL to connect a profile

---

Profile group object

Field	Type	Description
id	string	Unique profile group identifier (id)
name	string	Display name of the profile group
profiles_count	integer	Number of connected profiles in this group

---

List profile groups

GET /api/profile_groups

Retrieves all profile groups accessible with your API key.

API key behavior

API Key Type	Returns
Full account access	All profile groups in the account
Profile group scoped	Only the scoped profile group

Example

cURL

curl -X GET "https://api.postproxy.dev/api/profile_groups" \
     -H "Authorization: Bearer YOUR_API_KEY"

Node

import PostProxy from "postproxy-sdk";

const client = new PostProxy("YOUR_API_KEY");
const groups = await client.profileGroups.list();
console.log(groups);

Python

from postproxy import PostProxy

client = PostProxy("YOUR_API_KEY")
groups = await client.profile_groups.list()
print(groups)

Go

package main

import (
  "fmt"
  postproxy "github.com/postproxy/postproxy-go"
)

func main() {
  client := postproxy.New("YOUR_API_KEY")
  groups, _ := client.ProfileGroups.List()
  fmt.Println(groups)
}

Ruby

require "postproxy"

client = PostProxy::Client.new("YOUR_API_KEY")
groups = client.profile_groups.list
puts groups

PHP

use PostProxy\PostProxy;

$client = new PostProxy("YOUR_API_KEY");
$groups = $client->profileGroups->list();
print_r($groups);

Java

import dev.postproxy.PostProxy;

PostProxy client = new PostProxy("YOUR_API_KEY");
var groups = client.profileGroups().list();
System.out.println(groups);

.NET

using PostProxy;

var client = new PostProxyClient("YOUR_API_KEY");
var groups = await client.ProfileGroups.ListAsync();
Console.WriteLine(groups);

Response:

{
  "data": [
    {
      "id": "grp123abc",
      "name": "Main Brand",
      "profiles_count": 5
    },
    {
      "id": "grp456def",
      "name": "Client Project",
      "profiles_count": 3
    },
    {
      "id": "grp789ghi",
      "name": "Personal",
      "profiles_count": 2
    }
  ]
}

---

Get profile group

GET /api/profile_groups/:id

Retrieves a single profile group by its ID.

Path parameters

Name	Type	Required	Description
id	string	Yes	Profile group id

Example

cURL

curl -X GET "https://api.postproxy.dev/api/profile_groups/grp123abc" \
     -H "Authorization: Bearer YOUR_API_KEY"

Node

import PostProxy from "postproxy-sdk";

const client = new PostProxy("YOUR_API_KEY");
const group = await client.profileGroups.get("grp123abc");
console.log(group);

Python

import requests

response = requests.get(
    "https://api.postproxy.dev/api/profile_groups/grp123abc",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

print(response.json())

Go

package main

import (
  "fmt"
  postproxy "github.com/postproxy/postproxy-go"
)

func main() {
  client := postproxy.New("YOUR_API_KEY")
  group, _ := client.ProfileGroups.Get("grp123abc")
  fmt.Println(group)
}

Ruby

require "postproxy"

client = PostProxy::Client.new("YOUR_API_KEY")
group = client.profile_groups.get("grp123abc")
puts group

PHP

use PostProxy\PostProxy;

$client = new PostProxy("YOUR_API_KEY");
$group = $client->profileGroups->get("grp123abc");
print_r($group);

Java

import dev.postproxy.PostProxy;

PostProxy client = new PostProxy("YOUR_API_KEY");
var group = client.profileGroups().get("grp123abc");
System.out.println(group);

.NET

using PostProxy;

var client = new PostProxyClient("YOUR_API_KEY");
var group = await client.ProfileGroups.GetAsync("grp123abc");
Console.WriteLine(group);

Response:

{
  "id": "grp123abc",
  "name": "Main Brand",
  "profiles_count": 5
}

---

Create profile group

POST /api/profile_groups

Creates a new profile group.

Caution

This endpoint requires a full account access API key. Profile group scoped API keys cannot create new profile groups.

Request body

Name	Type	Required	Description
profile_group[name]	string	Yes	Name for the new profile group

Example

cURL

curl -X POST "https://api.postproxy.dev/api/profile_groups" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "profile_group": {
         "name": "New Client Project"
       }
     }'

Node

import PostProxy from "postproxy-sdk";

const client = new PostProxy("YOUR_API_KEY");
const group = await client.profileGroups.create("New Client Project");
console.log(group);

Python

from postproxy import PostProxy

client = PostProxy("YOUR_API_KEY")
group = await client.profile_groups.create("New Client Project")
print(group)

Go

package main

import (
  "fmt"
  postproxy "github.com/postproxy/postproxy-go"
)

func main() {
  client := postproxy.New("YOUR_API_KEY")
  group, _ := client.ProfileGroups.Create("New Client Project")
  fmt.Println(group)
}

Ruby

require "postproxy"

client = PostProxy::Client.new("YOUR_API_KEY")
group = client.profile_groups.create("New Client Project")
puts group

PHP

use PostProxy\PostProxy;

$client = new PostProxy("YOUR_API_KEY");
$group = $client->profileGroups->create("New Client Project");
print_r($group);

Java

import dev.postproxy.PostProxy;

PostProxy client = new PostProxy("YOUR_API_KEY");
var group = client.profileGroups().create("New Client Project");
System.out.println(group);

.NET

using PostProxy;

var client = new PostProxyClient("YOUR_API_KEY");
var group = await client.ProfileGroups.CreateAsync("New Client Project");
Console.WriteLine(group);

Response (201 Created):

{
  "id": "grp999xyz",
  "name": "New Client Project",
  "profiles_count": 0
}

Error responses

Permission denied (scoped API key) (422):

{
  "error": "Your API key has no such permission"
}

---

Delete profile group

DELETE /api/profile_groups/:id

Deletes a profile group and all its associated profiles.

Caution

This endpoint requires a full account access API key. Profile group scoped API keys cannot delete profile groups.

Path parameters

Name	Type	Required	Description
id	string	Yes	Profile group id

Example

cURL

curl -X DELETE "https://api.postproxy.dev/api/profile_groups/grp123abc" \
     -H "Authorization: Bearer YOUR_API_KEY"

Node

import PostProxy from "postproxy-sdk";

const client = new PostProxy("YOUR_API_KEY");
const result = await client.profileGroups.delete("grp123abc");
console.log(result);

Python

from postproxy import PostProxy

client = PostProxy("YOUR_API_KEY")
result = await client.profile_groups.delete("grp123abc")
print(result)

Go

package main

import (
  "fmt"
  postproxy "github.com/postproxy/postproxy-go"
)

func main() {
  client := postproxy.New("YOUR_API_KEY")
  result, _ := client.ProfileGroups.Delete("grp123abc")
  fmt.Println(result)
}

Ruby

require "postproxy"

client = PostProxy::Client.new("YOUR_API_KEY")
result = client.profile_groups.delete("grp123abc")
puts result

PHP

use PostProxy\PostProxy;

$client = new PostProxy("YOUR_API_KEY");
$result = $client->profileGroups->delete("grp123abc");
print_r($result);

Java

import dev.postproxy.PostProxy;

PostProxy client = new PostProxy("YOUR_API_KEY");
var result = client.profileGroups().delete("grp123abc");
System.out.println(result);

.NET

using PostProxy;

var client = new PostProxyClient("YOUR_API_KEY");
var result = await client.ProfileGroups.DeleteAsync("grp123abc");
Console.WriteLine(result);

Response:

{
  "deleted": true
}

---

Initialize connection

POST /api/profile_groups/:id/initialize_connection

Generates a URL to connect a new social media profile to a profile group. This is used to initiate the OAuth flow for connecting social accounts as if it was inside your service.

Note

Bluesky uses an app-password flow instead of OAuth. The payload is different — see Connect Bluesky (App Password) below.

Telegram uses a bring-your-own-bot flow. The payload is different and channel discovery is asynchronous — see Connect Telegram (Bring Your Own Bot) below.

Path parameters

Name	Type	Required	Description
id	string	Yes	Profile group id

Request body

Name	Type	Required	Description
platform	string	Yes	Platform to connect
redirect_url	string	Yes (except bluesky, telegram)	URL to redirect to after OAuth completes
identifier	string	Yes for bluesky	Bluesky handle (e.g. yourname.bsky.social)
app_password	string	Yes for bluesky	Bluesky app password (generate at bsky.app/settings/app-passwords)
bot_token	string	Yes for telegram	Telegram bot token from @BotFather

Supported platforms

Platform	Account type	Auth type
facebook	Facebook Page	OAuth
instagram	Instagram Business/Creator Account	OAuth
tiktok	TikTok Account	OAuth
linkedin	LinkedIn Profile	OAuth
youtube	YouTube Channel	OAuth
twitter	X (Twitter) Account	OAuth
threads	Threads Account	OAuth
pinterest	Pinterest Account	OAuth
bluesky	Bluesky Account	App password (no OAuth)
telegram	Telegram Channels (via bot)	Bring-your-own-bot (no OAuth)

Example

cURL

curl -X POST "https://api.postproxy.dev/api/profile_groups/grp123abc/initialize_connection" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "platform": "instagram",
       "redirect_url": "https://myapp.com/oauth/callback"
     }'

Node

import PostProxy from "postproxy-sdk";

const client = new PostProxy("YOUR_API_KEY");
const connection = await client.profileGroups.initializeConnection("grp123abc", "instagram", "https://myapp.com/oauth/callback");
console.log(connection);

Python

from postproxy import PostProxy

client = PostProxy("YOUR_API_KEY")
connection = await client.profile_groups.initialize_connection(
    "grp123abc", "instagram", "https://myapp.com/oauth/callback"
)
print(connection)

Go

package main

import (
  "fmt"
  postproxy "github.com/postproxy/postproxy-go"
)

func main() {
  client := postproxy.New("YOUR_API_KEY")
  connection, _ := client.ProfileGroups.InitializeConnection("grp123abc", "instagram", "https://myapp.com/oauth/callback")
  fmt.Println(connection)
}

Ruby

require "postproxy"

client = PostProxy::Client.new("YOUR_API_KEY")
connection = client.profile_groups.initialize_connection(
  "grp123abc",
  platform: "instagram",
  redirect_url: "https://myapp.com/oauth/callback"
)
puts connection

PHP

use PostProxy\PostProxy;

$client = new PostProxy("YOUR_API_KEY");
$connection = $client->profileGroups->initializeConnection("grp123abc", "instagram", "https://myapp.com/oauth/callback");
print_r($connection);

Java

import dev.postproxy.PostProxy;

PostProxy client = new PostProxy("YOUR_API_KEY");
var connection = client.profileGroups().initializeConnection("grp123abc", "instagram", "https://myapp.com/oauth/callback");
System.out.println(connection);

.NET

using PostProxy;

var client = new PostProxyClient("YOUR_API_KEY");
var connection = await client.ProfileGroups.InitializeConnectionAsync("grp123abc", "instagram", "https://myapp.com/oauth/callback");
Console.WriteLine(connection);

Response:

{
  "url": "https://app.postproxy.dev/partner_connect/inv789xyz",
  "success": true
}

Response fields

Field	Type	Description
url	string	URL to redirect the user to for OAuth authentication
success	boolean	Whether the invitation was created successfully

OAuth flow

1. Call this endpoint to get the connection URL
2. Redirect the user to the returned url
3. User authenticates with the social platform
4. User is redirected to your redirect_url after completion
5. A new profile is created in the specified profile group

If the user cancels or the OAuth flow fails, the user is redirected to your redirect_url with ?failure=true and an error_code appended as query parameters. Any existing query parameters on your redirect_url are preserved.

Error Code	Description
user_abandoned	The user cancelled or dismissed the OAuth flow
account_is_already_connected	The social account is already connected to another profile
update_failed	Failed to update a previously disconnected profile during reconnection

Example: If your redirect_url is https://myapp.com/callback?org=123, a cancelled connection redirects to https://myapp.com/callback?org=123&failure=true&error_code=user_abandoned.

Error responses

Missing redirect_url (422):

{
  "error": "Missing redirect_url"
}

Missing platform (422):

{
  "error": "Missing platform"
}

Platform already connected (422):

{
  "error": "Platform already connected"
}

---

Connect Bluesky (App Password)

Bluesky does not support OAuth in the same way other platforms do. Instead of returning a redirect URL, the API authenticates synchronously with the user’s Bluesky handle and an app password, then creates the profile in one call.

POST /api/profile_groups/:id/initialize_connection

Request body

Name	Type	Required	Description
platform	string	Yes	Must be "bluesky"
identifier	string	Yes	Bluesky handle. The .bsky.social suffix is added automatically if missing. Custom domains (e.g. you.example.com) are accepted as-is.
app_password	string	Yes	Bluesky app password, not the account password. Users generate one at https://bsky.app/settings/app-passwords

Caution

Always use an app password, never the user’s main login password. Accounts protected by 2FA will reject the main password and return an error explaining that an app password is required.

Example

curl -X POST "https://api.postproxy.dev/api/profile_groups/grp123abc/initialize_connection" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "bluesky",
    "identifier": "yourname.bsky.social",
    "app_password": "xxxx-xxxx-xxxx-xxxx"
  }'

Response:

{
  "success": true,
  "profile": {
    "id": "prof321zyx",
    "network": "bluesky",
    "name": "Your Display Name",
    "external_username": "yourname.bsky.social"
  }
}

Error responses

Missing credentials (422):

{
  "error": "Bluesky requires `identifier` (handle) and `app_password` in the payload. Generate an app password at https://bsky.app/settings/app-passwords",
  "error_code": "missing_credentials"
}

Invalid credentials / 2FA required (401):

{
  "error": "This account requires 2FA. Generate an app password at bsky.app/settings/app-passwords and use that instead of your main password.",
  "error_code": "bluesky_login_failed"
}

Account already connected to another profile group (422):

{
  "error": "This Bluesky profile is already connected to Postproxy.",
  "error_code": "account_is_already_connected"
}

---

Connect Telegram (Bring Your Own Bot)

Telegram does not expose consumer OAuth for posting. Instead, the user creates their own bot via @BotFather and adds it as administrator to the channel(s) they want to publish to. Postproxy uses that bot’s token to publish.

A single Telegram Profile represents one bot. The channels it can publish to are exposed via the placements endpoint, and the destination channel for each post is selected per-post via the chat_id parameter — see platform parameters.

For a step-by-step walkthrough (creating the bot, adding it to channels, publishing the first post), see the Connect Telegram with your own bot guide.

Three-step flow

1. Submit the bot token with this endpoint to create a Profile. Postproxy validates the token and registers a webhook with Telegram.
2. User adds the bot as administrator to each Telegram channel they want to publish to. As Telegram notifies us via the webhook, channels appear in the Profile’s placements.
3. Poll GET /api/profiles/:id/placements to list discovered channels. Use chat_id (the placement’s id) when creating posts.

POST /api/profile_groups/:id/initialize_connection

Request body

Name	Type	Required	Description
platform	string	Yes	Must be "telegram"
bot_token	string	Yes	Token issued by @BotFather. Get one with /newbot, then choose a name and username and copy the token.

Example

curl -X POST "https://api.postproxy.dev/api/profile_groups/grp123abc/initialize_connection" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "telegram",
    "bot_token": "123456789:ABCdef-GhIJklMnOpQrStUvWxYz"
  }'

Response:

{
  "success": true,
  "profile": {
    "id": "prof321zyx",
    "network": "telegram",
    "name": "My Bot",
    "external_username": "my_bot"
  },
  "next_step": "Add @my_bot as administrator to the Telegram channel(s) you want to publish to. Channels will appear in GET /api/profiles/prof321zyx/placements once Telegram notifies us."
}

Listing channels

After the bot has been added as administrator to one or more channels, list them via:

curl "https://api.postproxy.dev/api/profiles/prof321zyx/placements" \
  -H "Authorization: Bearer your_api_key"

{
  "data": [
    { "id": "-1001234567890", "name": "My Channel (@mychannel)" },
    { "id": "-1009876543210", "name": "Private Channel" }
  ]
}

The list is empty until the user adds the bot to a channel. We recommend polling every few seconds while the user completes that step. If a channel never appears, ask the user to remove and re-add the bot — that re-fires the discovery event.

Error responses

Missing bot token (422):

{
  "error": "Telegram requires `bot_token` in the payload. Create a bot via @BotFather (https://t.me/BotFather) and pass the token."
}

Invalid bot token (401):

{
  "error": "Telegram bot token is invalid or revoked — please reconnect the profile.",
  "error_code": "telegram_connect_failed"
}

Bot already connected to another profile group (422):

{
  "error": "This Telegram bot is already connected to Postproxy.",
  "error_code": "account_is_already_connected"
}

---

Use cases

Multi-brand management

Create separate profile groups for different brands:

# Create brand profile groups
curl -X POST "https://api.postproxy.dev/api/profile_groups" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"profile_group": {"name": "Brand A"}}'

curl -X POST "https://api.postproxy.dev/api/profile_groups" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"profile_group": {"name": "Brand B"}}'

Client onboarding

Generate connection URLs for clients to connect their accounts:

# Get OAuth URL for client to connect Instagram
curl -X POST "https://api.postproxy.dev/api/profile_groups/grp_client123/initialize_connection" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "instagram",
    "redirect_url": "https://yourplatform.com/client/connected"
  }'

Scoped API keys for partners

Issue profile-group-scoped API keys to partners, allowing them access only to their designated profile group while protecting other data.