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"

Python

import requests

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

print(response.json())

Ruby

require 'net/http'
require 'json'

uri = URI("https://api.postproxy.dev/api/profile_groups")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts JSON.parse(response.body)

JS

const response = await fetch("https://api.postproxy.dev/api/profile_groups", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY"
  }
});

const data = await response.json();
console.log(data);

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"

Python

import requests

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

print(response.json())

Ruby

require 'net/http'
require 'json'

uri = URI("https://api.postproxy.dev/api/profile_groups/grp123abc")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts JSON.parse(response.body)

JS

const response = await fetch(
  "https://api.postproxy.dev/api/profile_groups/grp123abc",
  {
    headers: {
      "Authorization": "Bearer YOUR_API_KEY"
    }
  }
);

const data = await response.json();
console.log(data);

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"
       }
     }'

Python

import requests

response = requests.post(
    "https://api.postproxy.dev/api/profile_groups",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "profile_group": {
            "name": "New Client Project"
        }
    }
)

print(response.json())

Ruby

require 'net/http'
require 'json'

uri = URI("https://api.postproxy.dev/api/profile_groups")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"
request["Content-Type"] = "application/json"
request.body = {
  profile_group: {
    name: "New Client Project"
  }
}.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts JSON.parse(response.body)

JS

const response = await fetch("https://api.postproxy.dev/api/profile_groups", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    profile_group: {
      name: "New Client Project"
    }
  })
});

const data = await response.json();
console.log(data);

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"

Python

import requests

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

print(response.json())

Ruby

require 'net/http'
require 'json'

uri = URI("https://api.postproxy.dev/api/profile_groups/grp123abc")
request = Net::HTTP::Delete.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts JSON.parse(response.body)

JS

const response = await fetch(
  "https://api.postproxy.dev/api/profile_groups/grp123abc",
  {
    method: "DELETE",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY"
    }
  }
);

const data = await response.json();
console.log(data);

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

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"
     }'

Python

import requests

response = requests.post(
    "https://api.postproxy.dev/api/profile_groups/grp123abc/initialize_connection",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "platform": "instagram",
        "redirect_url": "https://myapp.com/oauth/callback"
    }
)

print(response.json())

Ruby

require 'net/http'
require 'json'

uri = URI("https://api.postproxy.dev/api/profile_groups/grp123abc/initialize_connection")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"
request["Content-Type"] = "application/json"
request.body = {
  platform: "instagram",
  redirect_url: "https://myapp.com/oauth/callback"
}.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts JSON.parse(response.body)

JS

const response = await fetch(
  "https://api.postproxy.dev/api/profile_groups/grp123abc/initialize_connection",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      platform: "instagram",
      redirect_url: "https://myapp.com/oauth/callback"
    })
  }
);

const data = await response.json();
console.log(data);

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"
}