Skip to main content
Before you can publish, a social account has to be connected to a workspace. There are two ways to connect, and a small set of endpoints to keep accounts healthy afterward.

​
1. Connect from the dashboard (all platforms)

The simplest path — and the only one for most platforms — is the Developer Dashboard: open Social Accounts, choose a platform, and complete the OAuth flow. The account immediately becomes available to the API and appears in GET /v1/social/accounts.

​
2. Headless connect (your own UI)

Every supported platform can be connected from your own app — Facebook, Instagram, X (Twitter), LinkedIn, YouTube, TikTok, Threads, Bluesky, Pinterest, Reddit, Snapchat, Tumblr, and Google Business — without sending the user through the SmartlyQ dashboard.
1

Request a connect link

Call POST /v1/social/connect/{platform} with scope social:write. Pass an optional return_url to send the user back to your app afterward.
curl -X POST https://api.smartlyq.com/v1/social/connect/facebook \
  -H "Authorization: Bearer sqk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "return_url": "https://yourapp.com/connected" }'
Response (201)
{
  "success": true,
  "data": {
    "platform": "facebook",
    "connect_url": "https://www.facebook.com/v24.0/dialog/oauth?...",
    "expires_at": "2026-06-06T12:15:00Z"
  }
}
2

Send the user to connect_url

Open connect_url in a browser (redirect, popup, or new tab). The link is single-use and expires in 15 minutes. The user authorizes on the platform.
3

The account connects automatically

When the user approves, the platform’s OAuth callback completes the connection on SmartlyQ’s side and — if you supplied return_url — redirects the user back to your app with ?connected=<count>&platform=<name>. The new account now shows up in GET /v1/social/accounts. Platforms that expose multiple targets (YouTube channels, Google Business locations, Tumblr blogs, a member’s LinkedIn pages) connect them all automatically — there’s no in-flow picker.
4

(Optional) Poll for completion

If your app can’t observe the return_url redirect (e.g. a server-to-server flow, or the user closed the tab), poll with the state_token from the connect_url:
curl https://api.smartlyq.com/v1/social/connect/{state_token} \
  -H "Authorization: Bearer sqk_live_xxxxxxxxxxxx"
Returns status of pending, connected (with the new account), or expired.
Calling POST /v1/social/connect/{platform} with an unrecognized platform returns 422 UNSUPPORTED_PLATFORM (the response lists the supported ones). A platform whose OAuth app isn’t configured on your SmartlyQ instance returns 422 PROVIDER_NOT_CONFIGURED. If headless connect is disabled, the endpoint returns 404 NOT_ENABLED.

​
Managing connected accounts

ActionEndpoint
List accountsGET /v1/social/accounts
Check token healthGET /v1/social/accounts/{id}/health
Get a re-auth linkGET /v1/social/accounts/{id}/reconnect-url
Pause / resume postingPOST /v1/social/accounts/{id}/pause · /resume
DisconnectDELETE /v1/social/accounts/{id}

​
Reconnecting an account

Access tokens expire (lifetimes vary by platform — some in hours, some in months). SmartlyQ refreshes them automatically, but if an account’s health turns unhealthy — or you receive an account.token_expired webhook — get a reconnect link and send the user through it: 
curl https://api.smartlyq.com/v1/social/accounts/123/reconnect-url \
  -H "Authorization: Bearer sqk_live_xxxxxxxxxxxx"
The user re-authorizes and the same account resumes — no new account is created, and scheduled posts keep their target.
Pausing an account (/pause) skips it during publishing without disconnecting it — useful for temporarily taking a brand offline. Disconnecting is irreversible; the user must reconnect to use it again.
See Platforms for which platforms support headless connect, comments, DMs, and analytics.