Profiles API Reference

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

Endpoints

Method Endpoint Description
GET /api/profiles List all profiles
GET /api/profiles/:id Get a single profile
GET /api/profiles/:id/placements List placements for a 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 (id)
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
avatar_url string|null URL to the profile’s avatar image (resized, hosted by Postproxy). null if not yet downloaded

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
pinterest Pinterest 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 (id)

Example

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

Response:

{
  "data": [
    {
      "id": "prof123abc",
      "name": "My Company Page",
      "platform": "facebook",
      "status": "active",
      "profile_group_id": "grp456xyz",
      "expires_at": null,
      "post_count": 42,
      "avatar_url": "https://cdn.postproxy.dev/uploads/avatar_prof123abc.jpg"
    },
    {
      "id": "prof789def",
      "name": "@mycompany",
      "platform": "instagram",
      "status": "expired",
      "profile_group_id": "grp456xyz",
      "expires_at": "2024-03-15T00:00:00.000Z",
      "post_count": 38,
      "avatar_url": "https://cdn.postproxy.dev/uploads/avatar_prof789def.jpg"
    },
    {
      "id": "prof321ghi",
      "name": "John Doe",
      "platform": "linkedin",
      "status": "inactive",
      "profile_group_id": "grp456xyz",
      "expires_at": null,
      "post_count": 15,
      "avatar_url": null
    },
    {
      "id": "prof654jkl",
      "name": "@mycompany",
      "platform": "twitter",
      "status": "active",
      "profile_group_id": "grp456xyz",
      "expires_at": null,
      "post_count": 127,
      "avatar_url": "https://cdn.postproxy.dev/uploads/avatar_prof654jkl.jpg"
    }
  ]
}

Get profile

GET/api/profiles/:id

Retrieves a single profile by its ID.

Path parameters

Name Type Required Description
id string Yes Profile id

Response:

{
  "id": "prof123abc",
  "name": "My Company Page",
  "platform": "facebook",
  "status": "active",
  "profile_group_id": "grp456xyz",
  "expires_at": null,
  "post_count": 42,
  "avatar_url": "https://cdn.postproxy.dev/uploads/avatar_prof123abc.jpg"
}

List placements

GET/api/profiles/:id/placements

Retrieves the available placements for a profile. For Facebook profiles, placements are business pages. For LinkedIn profiles, placements include the personal profile and organizations. For Pinterest profiles, placements are boards.

Path parameters

Name Type Required Description
id string Yes Profile id

Placement object

Field Type Description
id string|null Platform-specific placement ID. null for personal profile (LinkedIn)
name string Display name of the placement

Example

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

Response:

{
  "data": [
    {
      "id": null,
      "name": "Personal Profile"
    },
    {
      "id": "108520199",
      "name": "Acme Marketing"
    },
    {
      "id": "110131347",
      "name": "Acme Labs"
    }
  ]
}

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 id

Example

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

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

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 id 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.