POST/social-media/connect-link

Generates a secure connect link that lets someone connect their social accounts to your workspace without a PostFast account. Can be scoped to specific platforms and return the user to your own app when done. Optionally emails the link.

https://api.postfa.st/Auth: pf-api-keyRate limit: 50 requests per hour

Important

The token in the URL is a JWT and can be quite long. Make sure to use the full connectUrl as returned, do not truncate or modify it, or the link will not work.

Usage

Share the connectUrl with your client or collaborator. When they open the link, they can connect their social media accounts directly to your workspace, no PostFast account required.

Knowing when it worked

There is no webhook. The return URL is the completion signal: it carries accountId, so you can act on the new account immediately instead of polling GET /social-media/my-social-accounts and diffing the list.

The connect page offers a Return to <your host> button rather than redirecting on its own, so coming back is always the user's own click.

Facebook and LinkedIn ask the user to pick a page first, and the button appears once that step is done. Pinterest and Google Business Profile return straight away, before the board or location has been chosen. Bluesky and Telegram connect inside the page itself and do not offer the button.

Branding

On Pro and Enterprise, your workspace logo replaces the PostFast logo at the top of the connect page. A small PostFast mark stays in the footer, and each platform's own consent screen always shows PostFast, because the platforms require the name of the registered app.

Request body

expiryDaysnumberoptionaldefault 7

Number of days until the connect link expires. Min: 1, max: 30.

platformsstring[]optional

Restrict the link to these platforms. Omit to offer all 11; an empty array is rejected. The scope is enforced server-side on every path the link can reach, so a link scoped to INSTAGRAM cannot connect anything else, even by calling the API directly.

FACEBOOKINSTAGRAMXTIKTOKLINKEDINYOUTUBEBLUESKYTHREADSPINTERESTTELEGRAMGOOGLE_BUSINESS_PROFILE
redirectUrlstringoptional

Where the connect page offers to send the user once connecting finishes. Must be https, except on localhost, 127.0.0.1 and [::1], where http is accepted so you can develop against it. Max 2000 characters, and a URL carrying credentials is rejected.

externalIdstringoptional

Your own reference for this link, echoed back unchanged on the return URL. Max 128 characters, limited to letters, digits and - . _ ~ : @.

sendEmailbooleanoptionaldefault false

Whether to send the connect link to the specified email address. Delivery is best effort: if the send fails, the request still returns 201 with a valid connectUrl.

emailstringRequired when sendEmail is true

The email address to send the connect link to. Must be a valid email address.

Query params on your return URL

ParamWhenValue
statusAlwayssuccess or error
platformOn successThe platform that was connected, e.g. INSTAGRAM
accountIdOn successThe connected account's id, the same id returned by GET /social-media/my-social-accounts
externalIdWhen you set oneYour reference, unchanged
messageOn errorWhy the connection failed

Existing params on your return URL are preserved, and these are set rather than appended, so a param you already use with one of these names is overwritten.

Response

201 Created A JSON object containing the connect URL.

connectUrlstringoptional

The secure URL that the recipient can use to connect their social media accounts to your workspace.