Connect a social account

curl --request POST \
  --url https://api.social-api.ai/v1/accounts/connect \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "brand_id": "b_01HZ9X3Q4R5M6N7P8V2K0W1J",
  "metadata": {},
  "onboarding": "cloud_api",
  "permissions": [
    "comments.read",
    "comments.write"
  ],
  "platform": "instagram",
  "redirect_uri": "https://app.acme.com/oauth/done",
  "state": "session_abc123"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    brand_id: 'b_01HZ9X3Q4R5M6N7P8V2K0W1J',
    metadata: {},
    onboarding: 'cloud_api',
    permissions: ['comments.read', 'comments.write'],
    platform: 'instagram',
    redirect_uri: 'https://app.acme.com/oauth/done',
    state: 'session_abc123'
  })
};

fetch('https://api.social-api.ai/v1/accounts/connect', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.social-api.ai/v1/accounts/connect"

payload = {
    "brand_id": "b_01HZ9X3Q4R5M6N7P8V2K0W1J",
    "metadata": {},
    "onboarding": "cloud_api",
    "permissions": ["comments.read", "comments.write"],
    "platform": "instagram",
    "redirect_uri": "https://app.acme.com/oauth/done",
    "state": "session_abc123"
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
  "display_name": "Acme Corp",
  "platform": "instagram",
  "username": "acmecorp"
}

{
  "auth_url": "https://www.instagram.com/oauth/authorize/?...",
  "message": "Redirect the user to auth_url",
  "metadata": {},
  "state": "4a8f2c1e9b3d7f06a5c2e8b4d1f3a7e2"
}

{
  "error": {
    "code": "resource.not_found",
    "message": "Account not found",
    "meta": {}
  }
}

{
  "error": {
    "code": "resource.not_found",
    "message": "Account not found",
    "meta": {}
  }
}

{
  "error": {
    "code": "resource.not_found",
    "message": "Account not found",
    "meta": {}
  }
}

Accounts

Connect a social account

Initiates account connection. For OAuth2 platforms returns an auth_url to redirect the user to. For apikey/credentials platforms stores the credentials immediately and returns account_id. For WhatsApp, open auth_url to run Meta’s signup. When the WhatsApp Business account holds several numbers, the redirect to your redirect_uri carries status=selection_required and a connection_id: list the numbers with GET /v1/accounts/pending/ and pick one with POST /v1/accounts/pending//select. Set the top-level redirect_uri field when connecting WhatsApp so the result reaches a page you control.

POST

accounts

connect

curl --request POST \
  --url https://api.social-api.ai/v1/accounts/connect \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "brand_id": "b_01HZ9X3Q4R5M6N7P8V2K0W1J",
  "metadata": {},
  "onboarding": "cloud_api",
  "permissions": [
    "comments.read",
    "comments.write"
  ],
  "platform": "instagram",
  "redirect_uri": "https://app.acme.com/oauth/done",
  "state": "session_abc123"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    brand_id: 'b_01HZ9X3Q4R5M6N7P8V2K0W1J',
    metadata: {},
    onboarding: 'cloud_api',
    permissions: ['comments.read', 'comments.write'],
    platform: 'instagram',
    redirect_uri: 'https://app.acme.com/oauth/done',
    state: 'session_abc123'
  })
};

fetch('https://api.social-api.ai/v1/accounts/connect', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.social-api.ai/v1/accounts/connect"

payload = {
    "brand_id": "b_01HZ9X3Q4R5M6N7P8V2K0W1J",
    "metadata": {},
    "onboarding": "cloud_api",
    "permissions": ["comments.read", "comments.write"],
    "platform": "instagram",
    "redirect_uri": "https://app.acme.com/oauth/done",
    "state": "session_abc123"
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
  "display_name": "Acme Corp",
  "platform": "instagram",
  "username": "acmecorp"
}

{
  "auth_url": "https://www.instagram.com/oauth/authorize/?...",
  "message": "Redirect the user to auth_url",
  "metadata": {},
  "state": "4a8f2c1e9b3d7f06a5c2e8b4d1f3a7e2"
}

{
  "error": {
    "code": "resource.not_found",
    "message": "Account not found",
    "meta": {}
  }
}

{
  "error": {
    "code": "resource.not_found",
    "message": "Account not found",
    "meta": {}
  }
}

{
  "error": {
    "code": "resource.not_found",
    "message": "Account not found",
    "meta": {}
  }
}

Authorizations

Authorization

string

header

required

Prefix your API key with "Bearer ". Example: Authorization: Bearer sapi_key_...

Body

application/json

Platform and metadata

brand_id

string

BrandID optionally specifies which brand to attach the account to. If omitted, a new brand is auto-created.

Example:

"b_01HZ9X3Q4R5M6N7P8V2K0W1J"

metadata

object

Metadata contains platform-specific connection data. For tiktok, connection_type "creator" connects through TikTok's Content Posting API instead of the default Business API ("business").

Show child attributes

onboarding

enum<string>

Onboarding applies to WhatsApp only. cloud_api (default) connects the number for use through the API alone. business_app connects a number that stays in use on the WhatsApp Business app, and imports its recent chats.

Available options:

cloud_api,

business_app

Example:

"cloud_api"

permissions

string[]

Permissions are the permissions to request for this account. If omitted, the brand's existing selection for this platform applies, and a brand with none gets every permission. Valid values: posts.read, posts.write, comments.read, comments.write, messages.read, messages.write, reviews.read, reviews.write, analytics.read.

Example:

["comments.read", "comments.write"]

platform

string

Platform identifies the social platform to connect (e.g. instagram, facebook, google, threads, tiktok, linkedin).

Example:

"instagram"

redirect_uri

string

RedirectURI is the customer's URL to redirect the user to after OAuth completes. If you have registered redirect URIs in the dashboard, the value must match one of them. If you have none registered, any valid https URI is accepted. If omitted, the default HTML success page is shown.

Example:

"https://app.acme.com/oauth/done"

state

string

CustomerState is an opaque value echoed back to the customer's redirect URI. Max 512 chars.

Example:

"session_abc123"

Response

Account connected (direct auth)

account_id

string

Example:

"acc_01HZ9X3Q4R5M6N7P8V2K0W1J"

display_name

string

Example:

"Acme Corp"

platform

string

Example:

"instagram"

username

string

Example:

"acmecorp"

Get started

Endpoints

Connect a social account

Authorizations

Body

Response