Profiles API Reference

The Profiles API allows you to retrieve and manage connected social media profiles. Profiles represent authenticated connections to social media platforms.

Note

All calls require authentication.

Endpoints

Method	Endpoint	Description
GET	/api/profiles	List all profiles
GET	/api/profiles/:id	Get a single profile
DELETE	/api/profiles/:id	Delete/disconnect a profile

---

Profile object

A profile represents a connected social media account.

Field	Type	Description
id	string	Unique profile identifier (hashid)
name	string	Display name of the connected account
status	string	Platform connection status: active, expired, inactive (might be disconnected or suspended on a platform)
platform	string	Platform identifier
profile_group_id	string	ID of the profile group this belongs to
expires_at	string|null	ISO 8601 timestamp when the connection expires (if applicable)
post_count	integer	Number of posts made through this profile

Platform values

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

---

List profiles

GET /api/profiles

Retrieves all profiles in the current profile group.

Query parameters

Name	Type	Required	Default	Description
profile_group_id	string	No	-	Filter by profile group (hashid)

Example

cURL

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

Python

import requests

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

print(response.json())

Ruby

require 'net/http'
require 'json'

uri = URI("https://api.postproxy.dev/api/profiles")
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/profiles", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY"
  }
});

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

Response:

{
  "data": [
    {
      "id": "prof123abc",
      "name": "My Company Page",
      "platform": "facebook",
      "status": "active",
      "profile_group_id": "grp456xyz",
      "expires_at": null,
      "post_count": 42
    },
    {
      "id": "prof789def",
      "name": "@mycompany",
      "platform": "instagram",
      "status": "expired",
      "profile_group_id": "grp456xyz",
      "expires_at": "2024-03-15T00:00:00.000Z",
      "post_count": 38
    },
    {
      "id": "prof321ghi",
      "name": "John Doe",
      "platform": "linkedin",
      "status": "inactive",
      "profile_group_id": "grp456xyz",
      "expires_at": null,
      "post_count": 15
    },
    {
      "id": "prof654jkl",
      "name": "@mycompany",
      "platform": "twitter",
      "status": "active",
      "profile_group_id": "grp456xyz",
      "expires_at": null,
      "post_count": 127
    }
  ]
}

---

Get profile

GET /api/profiles/:id

Retrieves a single profile by its ID.

Path parameters

Name	Type	Required	Description
id	string	Yes	Profile hashid

Example

cURL

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

Python

import requests

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

print(response.json())

Ruby

require 'net/http'
require 'json'

uri = URI("https://api.postproxy.dev/api/profiles/prof123abc")
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/profiles/prof123abc",
  {
    headers: {
      "Authorization": "Bearer YOUR_API_KEY"
    }
  }
);

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

Response:

{
  "id": "prof123abc",
  "name": "My Company Page",
  "platform": "facebook",
  "status": "active",
  "profile_group_id": "grp456xyz",
  "expires_at": null,
  "post_count": 42
}

---

Delete profile

DELETE /api/profiles/:id

Disconnects and removes a profile from the account. This does not affect posts already published through this profile.

Path parameters

Name	Type	Required	Description
id	string	Yes	Profile hashid

Example

cURL

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

Python

import requests

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

print(response.json())

Ruby

require 'net/http'
require 'json'

uri = URI("https://api.postproxy.dev/api/profiles/prof123abc")
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/profiles/prof123abc",
  {
    method: "DELETE",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY"
    }
  }
);

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

Response:

{
  "success": true
}

---

Token expiration

Some platforms issue access tokens that expire. The expires_at field indicates when the connection will expire and require re-authentication.

Behavior	Description
expires_at: null	Token does not expire or has a refresh token
expires_at: "2024-..."	Token expires at the specified time

When a token expires:

• Posts to that profile will fail
• The user needs to reconnect the profile through the web dashboard
• Use the Initialize Connection endpoint to generate a new connection URL

---

Connecting new profiles

Profiles cannot be created directly via the API. To connect a new social media account:

1. Use the Initialize Connection endpoint to get an OAuth URL
2. Redirect the user to that URL to authenticate
3. User is redirected back to your redirect_url after authentication
4. The profile is automatically created and associated with the profile group

---

Using profiles in posts

When creating posts, reference profiles by:

1. Profile ID: Use the id hashid directly
2. Platform name: Use the platform string (e.g., "twitter") to automatically select the profile for that platform

{
  "profiles": ["prof123abc", "twitter", "linkedin"]
}

If multiple profiles exist for the same platform in a profile group, using the platform name selects the first one. Use the profile ID for explicit selection.