Create a Connect Link

Get a one-time link that lets someone connect a social account to your workspace without logging in to Orshot

Published

POST
/v1/social/connect-sessions
curl -X POST "https://api.orshot.com/v1/social/connect-sessions" \
  -H "Authorization: Bearer <ORSHOT_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "<PLATFORM>",
    "return_url": "<RETURN_URL>",
    "external_id": "<EXTERNAL_ID>",
    "reconnect_account_id": 1
  }'

Create a connect session: a one-time link for one platform and one account. Hand the link to the person who owns the social account (a client, a franchisee, a team member in your own app). They approve the platform login in their browser, and the account lands in your workspace, ready for the publish endpoints. They never need an Orshot login.

The link works once and for five minutes. The first click binds it to that browser, so a forwarded link is dead. Read the outcome with Get a Connect Session, or let the person come back to your return_url.

See the Connect accounts from your app guide for the full flow.

What the link opens, left to right: the connect page naming your workspace and the platform, the account picker (LinkedIn and Facebook), and the connected result.

Endpoint#

POST /social/connect-sessions#

Endpoint
https://api.orshot.com/v1/social/connect-sessions

Request Example#

JavaScript
await fetch("https://api.orshot.com/v1/social/connect-sessions", {
  method: "POST",
  headers: {
    Authorization: "Bearer <ORSHOT_API_KEY>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    platform: "instagram",
    return_url: "https://crm.example.com/socials/done",
    external_id: "office_142",
  }),
});

Request Parameters#

ParameterTypeRequiredDescription
platformStringYesOne of twitter, instagram, facebook, linkedin, tiktok, youtube, pinterest, reddit, threads. Other platforms are connected from the dashboard.
return_urlStringNoWhere the person's browser goes once the connection has an outcome. https only, up to 512 characters, no credentials or fragment. The host must be one of your workspace's allowed domains (Embed settings) or orshot.com. Without it the person sees Orshot's own result page.
external_idStringNoYour reference for the person or account, up to 128 characters of letters, digits, _, ., : or -. Stored on the connected account and returned by List Social Accounts. Do not put emails or other personal data in it.
reconnect_account_idIntegerNoAn existing account of this workspace and platform. The login is pinned to that account's identity; signing in as anyone else fails with account_mismatch.
expected_usernameStringNoThe handle the person must sign in with. Any other identity fails with account_mismatch.
post_idIntegerNoA waiting post of this workspace. Echoed back on the session; waiting posts for the platform attach to the new account on their own.

Response Example#

JSON
{
  "data": {
    "id": "cs_9kq2N0xYv3b8ZtQ1mL7wPA",
    "object": "social_connect_session",
    "status": "pending",
    "platform": "instagram",
    "external_id": "office_142",
    "post_id": null,
    "reconnect_account_id": null,
    "return_url": "https://crm.example.com/socials/done",
    "created_at": "2026-11-02T10:00:00.000Z",
    "expires_at": "2026-11-02T10:05:00.000Z",
    "opened_at": null,
    "completed_at": null,
    "account": null,
    "attached_posts": 0,
    "error": null,
    "connect_url": "https://orshot.com/connect/social/cst_Vb3…",
    "billing": {
      "amount": 12,
      "currency": "usd",
      "interval": "month",
      "recurring": true,
      "billed_to": "workspace_owner"
    }
  }
}

connect_url is returned once, here. Treat it as a secret: it is the only credential the person needs. billing states what a connected account adds to the workspace owner's subscription, see Pricing.

Session Status#

StatusMeaning
pendingCreated, link not opened yet
openedContinue pressed, platform login in progress
selectingThe platform returned several identities (LinkedIn organisation, Facebook page) and the person is choosing
connectedDone. account holds the connected account
failedEnded without an account. error.code says why
cancelledCancelled with Cancel a Connect Session
expiredNobody opened the link within five minutes, or the login was not finished within 15 minutes of Continue. An opened session that expired can still end as connected when the platform reports the login late

Rate Limits#

Besides the 20 requests per minute shared by all social endpoints, a workspace can create 30 connect links per hour and complete 100 connections per day.

Error Responses#

CodecodeDescription
400invalid_platformUnknown platform, or one that is dashboard-only. supported lists the valid values
400invalid_return_urlNot https, too long, or a host outside your allowed domains
400invalid_external_idToo long or unexpected characters
400invalid_fieldexpected_username, reconnect_account_id or post_id malformed
403enterprise_requiredConnect links from a workspace API key need the Enterprise flag on this workspace's plan, and so does any link with external_id or return_url. Contact hi@orshot.com
403first_party_onlyThe caller is a third-party OAuth app. Use a workspace API key
403social_requires_paid_accountThe workspace owner has no paid plan. upgrade_url is included
403shopify_billedSocial accounts are not available on Shopify-billed plans yet
403insufficient_roleThe OAuth token's person is not an owner or admin of the workspace
404account_not_foundreconnect_account_id is not an account of this workspace
404post_not_foundpost_id is not a post of this workspace
429rate_limitedLinks per hour or connections per day reached. Retry-After is set
503connect_unavailableConnect links are briefly unavailable. Retry shortly
Was this page helpful?

Ready to automate?

Start rendering images, PDFs and videos from your templates in under 2 minutes. Free plan, no credit card.

Get your API key
  • Image, PDF and video generation via API
  • Visual editor with AI and smart layouts
  • Zapier, Make, MCP and 40+ integrations
  • White-label embed for your own app
  • 100 free credits a month, no credit card required