Placements API Reference

The Placements API is the account-wide view of every placement your profiles can post to or message from — Facebook Pages, LinkedIn organizations, Pinterest boards, Telegram channels, Google Business locations, WhatsApp phone numbers. One placement record exists per account, platform, and platform ID, even when several connected profiles can see it; exactly one of those profiles is the active profile that posting and webhooks route through.

For the per-profile placement list (used to pick a page_id when posting), see List placements.

A Google Business placement’s external_id is the location_id every Business Profile management endpoint takes.

A Facebook placement’s external_id is the page_id every Page profile management endpoint takes.

A WhatsApp placement’s external_id is the phone_number_id every WhatsApp number-level endpoint takes, and the placement_id you pass when creating a chat.

Endpoints

Method	Endpoint	Description
`GET`	`/api/placements`	List all placements across the account
`PATCH`	`/api/placements/:id/set_active_profile`	Switch which connected profile serves a placement

Placement object

Field	Type	Description
`id`	string	Placement ID. Note: this is Postproxy’s own ID, used in the URLs below — not the platform ID
`platform`	string	Platform the placement belongs to (`facebook`, `linkedin`, `pinterest`, `telegram`, `google_business`, `whatsapp`)
`external_id`	string	Platform-specific ID — the value used as `page_id` / `chat_id` when creating posts, as `phone_number_id` on WhatsApp, and returned as `id` by List placements
`name`	string	Placement name
`avatar_url`	string\|null	Stable Postproxy storage URL of the placement’s picture, resized to 256×256 (Facebook Pages). `null` until it has been mirrored and for networks without one
`status`	string	`active` (the active profile is connected), `orphaned` (the active profile is disconnected — posting is paused until you switch to a connected profile), or `removed` (access was revoked on the platform)
`active_profile`	object	The profile posting routes through: `id`, `name`, `connected`
`linked_profiles`	array	Every profile that can see this placement (`id`, `name`, `connected`) — the candidates for Set active profile

The active profile never changes automatically while it can still serve the placement. If it disconnects, the placement may be handed to another linked, connected profile; otherwise it stays orphaned until you switch it here or in the web app.

List placements (account-wide)

GET /api/placements

Retrieves every placement on the account, across all platforms and profile groups.

Sandbox API keys list sandbox placements; live keys list live placements.

Query parameters

Parameter	Type	Required	Default	Description
`page`	integer	No	`1`	Page number (1-based)
`per_page`	integer	No	`25`	Results per page (maximum `100`)

Example

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

Response:

{
  "total": 2,
  "page": 1,
  "per_page": 25,
  "data": [
    {
      "id": "plc123abc",
      "platform": "facebook",
      "external_id": "967627696429808",
      "name": "Acme Store",
      "avatar_url": "https://cdn.postproxy.dev/uploads/profile_placement_avatar_967627696429808.jpg",
      "status": "active",
      "active_profile": {
        "id": "prof123abc",
        "name": "Acme Facebook",
        "connected": true
      },
      "linked_profiles": [
        { "id": "prof123abc", "name": "Acme Facebook", "connected": true },
        { "id": "prof456def", "name": "Acme Backup", "connected": true }
      ]
    }
  ]
}

Set active profile

PATCH /api/placements/:id/set_active_profile

Switches which connected profile serves the placement — posting and webhook traffic route through it from then on.

Path parameters

Parameter	Type	Required	Description
`id`	string	Yes	Placement ID (the `id` from List placements, not the platform ID)

Body parameters

Parameter	Type	Required	Description
`profile_id`	string	Yes	Profile to make active. Must be listed in the placement’s `linked_profiles` and be connected

Example

curl -X PATCH "https://api.postproxy.dev/api/placements/plc123abc/set_active_profile" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "profile_id": "prof456def"
     }'

Response — the updated Placement object. Switching an orphaned placement to a connected profile also fires the placement.restored webhook.

Error responses

Placement or profile not found (404):

{
  "error": "Not found"
}

Profile cannot serve the placement (422):

{
  "error": "Profile is not linked to this placement"
}

Also returned as "Profile is not connected" when the target profile is disconnected, and "Profile is in a different environment" when it lives in the other live/sandbox environment.

Missing profile_id (400):

{
  "status": 400,
  "error": "Bad Request",
  "message": "param is missing or the value is empty or invalid: profile_id"
}