Accounts API

Manage connected social media accounts. Use the OAuth flow to connect end-user accounts, then check their health and manage them. Supported platforms: TikTok, Instagram, Facebook, Twitter/X, LinkedIn, YouTube, Threads, Bluesky, Pinterest, and Telegram.

Endpoints

GET/api/v1/accountsList connected accounts

GET/api/v1/accounts/:id/healthCheck single account health

GET/api/v1/accounts/healthBulk health check

DELETE/api/v1/accounts/:idDisconnect account

GET/api/v1/connect/:platformGet OAuth URL

GET/api/v1/connect/:platform/entitiesList sub-entities

POST/api/v1/connect/:platform/selectSelect sub-entity

List connected accounts

GET/api/v1/accountsList connected accounts

Returns all social media accounts connected to your Schedulala account. Optionally filter by brand or platform.

Query Parameters

Name	Type	Required	Description
`brandId`	`string`	Optional	Filter accounts belonging to a specific workspace. Matches API Profile ids (source: api) and dashboard Brand ids (source: dashboard).
`platform`	`string`	Optional	Filter by platform `tiktokinstagramfacebooktwitterlinkedinyoutubethreadsblueskypinteresttelegram`

brandId

stringOptional

Filter accounts belonging to a specific workspace. Matches API Profile ids (source: api) and dashboard Brand ids (source: dashboard).

platform

stringOptional

Filter by platform

tiktokinstagramfacebooktwitterlinkedinyoutubethreadsblueskypinteresttelegram

curl https://schedulala.com/api/v1/accounts \
  -H "Authorization: Bearer sk_live_abc123xyz789..."

{
  "success": true,
  "accounts": [
    {
      "id": "acc_123abc",
      "brandId": "brand_456def",
      "platform": "tiktok",
      "username": "@creator",
      "displayName": "Content Creator",
      "profilePicture": "https://p16-sign.tiktokcdn.com/...",
      "isConnected": true,
      "connectedAt": "2026-01-10T08:30:00Z",
      "capabilities": {
        "canPostVideo": true,
        "canPostPhoto": true,
        "canPostCarousel": true,
        "canPostStory": false,
        "maxVideoDuration": 600
      }
    },
    {
      "id": "acc_789ghi",
      "brandId": "brand_456def",
      "platform": "instagram",
      "username": "creator.ig",
      "displayName": "Creator on IG",
      "profilePicture": "https://scontent.cdninstagram.com/...",
      "isConnected": true,
      "connectedAt": "2026-01-12T14:00:00Z",
      "capabilities": {
        "canPostVideo": true,
        "canPostPhoto": true,
        "canPostCarousel": true,
        "canPostStory": true,
        "maxVideoDuration": 90
      }
    },
    {
      "id": "17841400000000000",
      "brandId": "665f1a2b3c4d5e6f70819202",
      "brandName": "Acme Brand",
      "platform": "instagram",
      "platformUserId": "17841400000000000",
      "username": "acmebrand",
      "isConnected": false,
      "connectedAt": null,
      "lastValidated": "2026-07-10T09:15:00Z",
      "needsReconnect": true,
      "reconnectReason": "expired",
      "source": "dashboard"
    }
  ]
}

brandId means the API Profile for source: "api" accounts and the dashboard workspace (Brand) for source: "dashboard" accounts — use it to group accounts, not as a posting target. isConnected: false with needsReconnect: true means the platform revoked or expired the account's credentials: don't post to it; reconnect it in the Schedulala dashboard first. lastValidated is only reported where a real validation signal exists and is otherwise null.

Check account health

GET/api/v1/accounts/:id/healthCheck single account health

Check the connection status and token validity of a single account. Use this to proactively detect expired tokens before posting fails.

Path Parameters

Name	Type	Required	Description
`id`	`string`	Required	The account ID (e.g. acc_123abc)

id

stringRequired

The account ID (e.g. acc_123abc)

curl https://schedulala.com/api/v1/accounts/acc_123abc/health \
  -H "Authorization: Bearer sk_live_abc123xyz789..."

{
  "success": true,
  "health": {
    "accountId": "acc_123abc",
    "platform": "tiktok",
    "status": "healthy",
    "tokenExpiresAt": "2026-03-15T00:00:00Z",
    "checkedAt": "2026-03-01T10:00:00Z"
  }
}

Bulk health check

GET/api/v1/accounts/healthBulk health check

Check the health of all connected accounts in a single request. Returns per-account status plus a summary with counts.

curl https://schedulala.com/api/v1/accounts/health \
  -H "Authorization: Bearer sk_live_abc123xyz789..."

{
  "success": true,
  "results": [
    {
      "accountId": "acc_123abc",
      "platform": "tiktok",
      "username": "@creator",
      "status": "healthy",
      "tokenExpiresAt": "2026-03-15T00:00:00Z",
      "checkedAt": "2026-03-01T10:00:00Z"
    },
    {
      "accountId": "acc_789ghi",
      "platform": "instagram",
      "username": "creator.ig",
      "status": "expired",
      "tokenExpiresAt": "2026-02-01T00:00:00Z",
      "error": "Token expired",
      "checkedAt": "2026-03-01T10:00:00Z"
    }
  ],
  "summary": {
    "total": 2,
    "healthy": 1,
    "expired": 1,
    "error": 0
  }
}

Disconnect account

DELETE/api/v1/accounts/:idDisconnect account

Disconnect a social media account. This clears stored tokens and removes the account from your Schedulala workspace. Scheduled posts targeting this account will fail to publish unless it is reconnected.

Path Parameters

Name	Type	Required	Description
`id`	`string`	Required	The account ID to disconnect

id

stringRequired

The account ID to disconnect

curl -X DELETE https://schedulala.com/api/v1/accounts/acc_123abc \
  -H "Authorization: Bearer sk_live_abc123xyz789..."

{
  "success": true,
  "message": "Account disconnected successfully",
  "account": {
    "id": "acc_123abc",
    "platform": "tiktok",
    "username": "@creator",
    "disconnectedAt": "2026-03-01T10:00:00Z"
  }
}

Warning: Disconnecting clears the account's stored tokens. The user will need to re-authorize via the OAuth flow to reconnect, and scheduled posts targeting the account will fail to publish until then.

Get OAuth URL

GET/api/v1/connect/:platformGet OAuth URL

Generate an OAuth authorization URL for a specific platform. Redirect your user to this URL to begin the account connection flow.

Path Parameters

Name	Type	Required	Description
`platform`	`string`	Required	The OAuth platform to connect. Bluesky and Telegram use POST with credentials instead (see Connecting Accounts). `tiktokinstagramfacebooktwitterlinkedinyoutubethreadspinterest`

platform

stringRequired

The OAuth platform to connect. Bluesky and Telegram use POST with credentials instead (see Connecting Accounts).

tiktokinstagramfacebooktwitterlinkedinyoutubethreadspinterest

Query Parameters

Name	Type	Required	Description
`brandId`	`string`	Optional	The brand to associate the new account with. Defaults to your default brand.
`redirectUrl`	`string`	Optional	Where to redirect the user after authorization completes. Defaults to Schedulala's hosted completion page.

brandId

stringOptional

The brand to associate the new account with. Defaults to your default brand.

redirectUrl

stringOptional

Where to redirect the user after authorization completes. Defaults to Schedulala's hosted completion page.

curl "https://schedulala.com/api/v1/connect/tiktok?brandId=brand_456def&redirectUrl=https://myapp.com/callback" \
  -H "Authorization: Bearer sk_live_abc123xyz789..."

{
  "success": true,
  "platform": "tiktok",
  "authUrl": "https://schedulala.com/oauth/tiktok?state=st_abc123...",
  "expiresIn": 600
}

OAuth flow

Get the OAuth URL

Call GET /api/v1/connect/:platform, optionally with a brandId and redirectUrl

Redirect your user

Send the user to the returned authUrl. The URL expires after expiresIn seconds (default 600).

User authorizes

The user logs in to the platform and grants Schedulala permission to post on their behalf.

Handle the callback

The user is redirected back to your redirectUrl with query parameters indicating the result.

Callback parameters

After the user completes authorization, they are redirected to your redirectUrl with the following query parameters:

On success:

https://myapp.com/callback?success=true&account_id=acc_123abc&platform=tiktok&username=creator

On failure:

https://myapp.com/callback?error=oauth_denied&message=User+denied+authorization&platform=tiktok

Tip: Some platforms (Facebook, LinkedIn, Pinterest, YouTube) require an additional sub-entity selection step after OAuth. Their callback returns success=pending with a selectionToken parameter; if present, you need to call the entities endpoint to let the user pick which Page, Organization, Board, or Channel to connect.

List sub-entities

GET/api/v1/connect/:platform/entitiesList sub-entities

Some platforms require selecting a specific entity after OAuth authorization. For example, a Facebook user may manage multiple Pages, or a LinkedIn user may have access to multiple Organizations. Use this endpoint to retrieve the available entities so the user can choose.

Platform	Entity Type	Selection Required?
Facebook	Pages	Yes
LinkedIn	Organizations	Yes (if org access)
YouTube	Channels	Yes (if multiple)
Pinterest	Boards	Yes

Telegram doesn't use OAuth or entity selection. Register the channels a bot can post to with POST /api/v1/connect/telegram/channels (see the Connecting Accounts guide).

Query Parameters

Name	Type	Required	Description
`selectionToken`	`string`	Required	The token returned in the OAuth callback query parameters. Identifies the pending authorization session.

selectionToken

stringRequired

The token returned in the OAuth callback query parameters. Identifies the pending authorization session.

curl "https://schedulala.com/api/v1/connect/facebook/entities?selectionToken=sel_abc123..." \
  -H "Authorization: Bearer sk_live_abc123xyz789..."

{
  "success": true,
  "platform": "facebook",
  "entities": [
    {
      "id": "ent_page1",
      "name": "My Business Page",
      "type": "page",
      "profilePicture": "https://graph.facebook.com/..."
    },
    {
      "id": "ent_page2",
      "name": "Side Project Page",
      "type": "page",
      "profilePicture": "https://graph.facebook.com/..."
    }
  ],
  "expiresIn": 540
}

Select sub-entity

POST/api/v1/connect/:platform/selectSelect sub-entity

After the user picks an entity from the list, call this endpoint to complete the account connection. This finalizes the OAuth flow and creates the connected account.

Request Body

Name	Type	Required	Description
`selectionToken`	`string`	Required	The selection token from the OAuth callback
`entityId`	`string`	Required	The entity ID chosen by the user (from the entities list)
`brandId`	`string`	Optional	The brand to associate this account with. Defaults to the brand from the OAuth flow.

selectionToken

stringRequired

The selection token from the OAuth callback

entityId

stringRequired

The entity ID chosen by the user (from the entities list)

brandId

stringOptional

The brand to associate this account with. Defaults to the brand from the OAuth flow.

curl -X POST https://schedulala.com/api/v1/connect/facebook/select \
  -H "Authorization: Bearer sk_live_abc123xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "selectionToken": "sel_abc123...",
    "entityId": "ent_page1"
  }'

{
  "success": true,
  "account": {
    "id": "acc_newpage",
    "platform": "facebook",
    "username": "My Business Page",
    "displayName": "My Business Page",
    "profilePicture": "https://graph.facebook.com/...",
    "isConnected": true,
    "connectedAt": "2026-03-01T10:30:00Z",
    "capabilities": {
      "canPostVideo": true,
      "canPostPhoto": true,
      "canPostCarousel": true,
      "canPostStory": true,
      "maxVideoDuration": 14400
    },
    "selectedEntity": {
      "id": "ent_page1",
      "name": "My Business Page",
      "type": "page"
    }
  }
}

Next steps

Posts API — Create and schedule posts to your connected accounts Webhooks — Get notified when account tokens expire or connections break Analytics API — Track post performance across your connected accounts