Social accounts

Social accounts are the OAuth links between your workspace and each destination network. They are created in the dashboard through OAuth and cannot be created through the API. You can, however, list, inspect, and disconnect them.

List

GET /api/v1/social_accounts

Optional filter: platform=instagram.

{
  "object": "list",
  "data": [
    {
      "object": "social_account",
      "id": "sa_9c8b7a6d5e4f",
      "platform": "instagram",
      "account_type": "business",
      "platform_user_id": "17841400000000000",
      "platform_username": "acme.studio",
      "is_active": true,
      "connected_at": "2026-05-20T10:00:00Z"
    }
  ],
  "has_more": false
}

Retrieve

GET /api/v1/social_accounts/{id}

Disconnect

DELETE /api/v1/social_accounts/{id}

Marks the account inactive and revokes the stored access token. Fires the social_account.disconnected webhook with reason: "api".

Reconnecting requires the user to complete OAuth again in the dashboard.

Connection state webhooks

Two related events surface changes without polling:

• social_account.connected when a user finishes OAuth or the WhatsApp callback resolves.
• social_account.disconnected when a user removes the app, when Meta calls the data-deletion callback, or when this endpoint is called.

Both include the platform, platform_user_id, and platform_username so you can reconcile with your own records.