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 (hashid)
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 hashid

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

from postproxy import PostProxy

client = PostProxy("YOUR_API_KEY")
group = await client.profile_groups.get("grp123abc")
print(group)

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 hashid

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.

Path parameters

Name	Type	Required	Description
id	string	Yes	Profile group hashid

Request body

Name	Type	Required	Description
platform	string	Yes	Platform to connect
redirect_url	string	Yes	URL to redirect to after OAuth completes

Supported platforms

Platform	Account type
facebook	Facebook Page
instagram	Instagram Business/Creator Account
tiktok	TikTok Account
linkedin	LinkedIn Profile
youtube	YouTube Channel
twitter	X (Twitter) Account
threads	Threads Account
pinterest	Pinterest Account

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://postproxy.com/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

Error responses

Missing redirect_url (422):

{
  "error": "Missing redirect_url"
}

Missing platform (422):

{
  "error": "Missing platform"
}

Platform already connected (422):

{
  "error": "Platform already connected"
}