Create connect session
Creates a hosted onboarding session for a customer-owned social account. Use the returned URL to send the end user into UniPost's managed Connect flow. For OAuth platforms, this endpoint defaults to workspace-credential mode: the workspace must already have Platform Credentials uploaded unless you explicitly pass
allow_quickstart_creds=true. On Basic, the requested OAuth platform must also match the workspace's shared custom platform slot. Facebook Page sessions connect the first publishable Page returned by Meta for the authorizing user. See the Connect Sessions guide for shared-app and workspace-credential behavior.Authorization
AuthorizationBearer <token>In header
Workspace API key.
Request Body
platformstring
Destination platform for the hosted onboarding flow.
Valuestwitter | linkedin | bluesky | youtube | tiktok | instagram | threads | facebook | pinterest
profile_idOptionalstring
Profile that should own the resulting connected account. Required when the workspace has multiple profiles.
external_user_idstring
Your stable end-user identifier.
external_user_emailOptionalstring
Optional email for reconciliation and support.
return_urlOptionalstring
Where UniPost redirects the user after completion, cancellation, or a handled OAuth failure. This is not the OAuth callback URL or platform redirect_uri.
allow_quickstart_credsOptionalboolean
Optional escape hatch for OAuth platforms. Defaults to false. When false, the workspace must already have Platform Credentials uploaded for that platform. On Basic, that platform must also match the workspace's shared custom platform slot. When true, UniPost may fall back to the shared Quickstart OAuth app if no workspace credentials exist; workspace credentials still take priority when present.
Response Body
201
idstring
Connect session ID.
urlstring
Hosted onboarding URL to redirect the user to.
allow_quickstart_credsboolean
Whether this session is allowed to fall back to UniPost's shared Quickstart OAuth app when no workspace-specific credentials exist. Workspace credentials still take priority when present.
managed_account_idstring
Present after the session completes. Alias of completed_social_account_id for hosted Connect callers.
statusstring
Session lifecycle state. Create responses start as pending.
Valuespending | completed | expired | cancelled
expires_atstring | null
Expiration timestamp for the hosted session. New sessions expire after 30 minutes.
401
error.codestring
Usually "UNAUTHORIZED".
error.normalized_codestring
Lowercase alias such as "unauthorized".
error.messagestring
Human-readable error message.
request_idstring
Request identifier for debugging and support.
402
error.codestring
Usually "UNAUTHORIZED".
error.normalized_codestring
Lowercase alias such as "unauthorized".
error.messagestring
Human-readable error message.
request_idstring
Request identifier for debugging and support.
422
error.codestring
Usually "UNAUTHORIZED".
error.normalized_codestring
Lowercase alias such as "unauthorized".
error.messagestring
Human-readable error message.
request_idstring
Request identifier for debugging and support.
500
error.codestring
Usually "UNAUTHORIZED".
error.normalized_codestring
Lowercase alias such as "unauthorized".
error.messagestring
Human-readable error message.
request_idstring
Request identifier for debugging and support.
Callback URLs
return_urlonly controls where the browser lands after UniPost finishes handling the session. Platform OAuth callback URLs are generated by UniPost. Quickstart sessions use UniPost's registered callbacks; workspace Platform Credentials must allow-list the exact callback URL shown in the Platform Credentials guides.