IDs

Every object SocialAPI returns has an id string. Treat every ID as an opaque string: store it as text, send it back unchanged, and never parse it or depend on its length, characters, or format. The formats below tell you how to recognize an ID, not how to read one.

ID formats

Object	ID format	Example
Connected account	`acc_` prefix	`acc_01HZ9X3Q4R5M6N7P8V2K0W1J`
Facebook Page or other page-level destination of an account	`sapi_page_` prefix	`sapi_page_01HZ9X3Q4R5M6N7P8V2K0W1J`
Pinterest board	`sapi_board_` prefix	`sapi_board_01HZ9X3Q4R5M6N7P8V2K0W1J`
Login (the `login_id` of a Facebook or Google connection)	`cred_` prefix	`cred_01HZ9X3Q4R5M6N7P8V2K0W1J`
Automation	`aut_` prefix	`aut_01HZ9X3Q4R5M6N7P8V2K0W1J`
Automation Firing	`afr_` prefix	`afr_01HZ9X3Q4R5M6N7P8V2K0W1J`
Comment	`sapi_cmt_` prefix	`sapi_cmt_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U1I`
Review	`sapi_rev_` prefix	`sapi_rev_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U1I`
Direct message, as the `id` of a `dm.*` webhook event and in `message_id` and `message_ids` of a send response	`sapi_dm_` prefix	`sapi_dm_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U1I`
Mention	`sapi_mnt_` prefix	`sapi_mnt_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U1I`
Message, as the `id` of an item in `GET /v1/inbox/conversations/{id}/messages`	UUID, no prefix	`7c9e6679-7425-40de-944b-e07fc1f90ae7`
Post, brand, invite, API key, webhook endpoint, webhook delivery, media file, conversation, event, export, announcement	UUID, no prefix	`7c9e6679-7425-40de-944b-e07fc1f90ae7`

The sapi_cmt_, sapi_rev_, sapi_dm_, and sapi_mnt_ IDs are interaction IDs: the id of each item returned by the comment, review, and mention endpoints, of each direct message in a webhook event, and of each message a send request returns. A message in a conversation’s message list has a UUID id instead, and its platform_id is the platform’s own ID. The two are different values for the same message. An API key’s secret starts with sapi_key_, which is not an ID: the id of a key is a UUID, and the secret is shown once when you create the key. Fields named platform_id hold the platform’s own ID for the same object, such as an Instagram comment ID. They are different values from id.

What each endpoint accepts

Connected account: every endpoint that takes an account uses acc_ IDs.
Post targets: page_id and board_id accept the SocialAPI ID (sapi_page_, sapi_board_) or the platform’s own ID.
Comment routes: :postId takes the platform’s post ID. :commentId and comment_id take a sapi_cmt_ ID or the platform’s comment ID.
Review routes: :id takes a sapi_rev_ ID or the platform’s review ID.
Conversation routes: :id takes the conversation id returned by GET /v1/inbox/conversations. It is a UUID, not a sapi_dm_ ID.
Mention replies: media_id takes a sapi_mnt_ ID or the platform’s media ID.
Read a post: GET /v1/posts/{pid} takes the SocialAPI post ID or a platform post ID. A platform post ID that matches more than one post returns 409 ambiguous_post_id: use the SocialAPI post ID.
Post metrics: GET /v1/posts/{pid}/metrics takes the SocialAPI post ID or a platform post ID, with the same 409 ambiguous_post_id.

A SocialAPI interaction ID of the wrong type returns 400 validation.id_invalid: for example a sapi_rev_ ID in a comment route. An interaction ID created for a different platform than the account returns 400 validation.id_platform_mismatch.

Use IDs in requests

List commented posts, then reply to one comment using its id:

curl -X POST "https://api.social-api.ai/v1/inbox/comments/17895695668004550" \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
    "comment_id": "sapi_cmt_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U1I",
    "text": "Thank you!"
  }'

Response (HTTP 200):

{
  "success": true,
  "comment_id": "sapi_cmt_7Q2KDWZ9SFN4RAHB6GXEM3YLTPV1C5UJ"
}

comment_id in the response is the ID of your new reply. In this request, 17895695668004550 is the platform’s post ID. Hide a comment, with the same sapi_cmt_ ID in the path:

curl -X POST "https://api.social-api.ai/v1/inbox/comments/17895695668004550/sapi_cmt_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U1I/hide" \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J"}'

See Comments, Reviews, and Mentions for every route that takes an interaction ID.

What stays stable

Interaction IDs: the same comment, review, or mention always has the same id, in every response and every webhook event. Store it and join on it. For a direct message, the sapi_dm_ ID is stable but the message list does not return it. To match a listed message to a webhook event, compare platform_id.
Connected accounts: an acc_ ID stays the same for the life of the connection. Reconnecting the same platform account to your SocialAPI account keeps its acc_ ID. Disconnecting an account with DELETE /v1/accounts/{id} deletes it, and connecting it again creates a new acc_ ID.
Every other object: an ID never changes for the life of the object.

Store IDs as text, not as a typed uuid column: formats differ per object type, so never assume one format across objects.

Create requests are not idempotent

No create endpoint accepts an idempotency key. When a request times out and you repeat it, check first whether the first request succeeded.

Request	What a repeat does
`POST /v1/brands`	Creates another brand. Brand names are not unique
`POST /v1/keys`	Creates another API key
`POST /v1/webhooks`	Creates another webhook endpoint, even for the same URL
`POST /v1/automations`	Creates another Automation, up to the limit of 50 Automations per account
`POST /v1/invites`	Returns `409 resource.conflict` while an active invite exists for the same brand and platform
`POST /v1/posts`	Returns `409 resource.conflict` when the same account already has a post with the same title and text that was created in the last 24 hours and is now `published`. Send `skip_duplicate_check: true` to publish the same content again. Drafts, scheduled posts, and posts still `publishing` are not compared
Replies and direct messages	Send another reply or message and cost another interaction credit

After a timeout, persist the ID from the first response when you have it. Otherwise list the object (GET /v1/brands, GET /v1/posts) and look for it before you create another. For webhook endpoints, X-SocialAPI-Delivery is the same value on every retry of one delivery. Use it to ignore a duplicate. See Webhooks.

Pagination: cursors are opaque strings too
Comments: routes that take sapi_cmt_ IDs
Reviews: routes that take sapi_rev_ IDs
Track post delivery: post and target fields in post responses
Webhooks: X-SocialAPI-Delivery and duplicate events

Get started

Connect accounts

Inbox

Automations

Publish

Webhooks

API essentials

ID formats

What each endpoint accepts

Use IDs in requests

What stays stable

Create requests are not idempotent

​ID formats

​What each endpoint accepts

​Use IDs in requests

​What stays stable

​Create requests are not idempotent

​Related

ID formats

What each endpoint accepts

Use IDs in requests

What stays stable

Create requests are not idempotent

Related