Skip to content

Save Facebook Pages API

The Save Facebook Pages API saves only the selected Facebook Pages as integrations. It uses POST {{API_BASE_URL}}/v1/connect/facebook/selection/{token}, where token is the one-time selection token supplied in the path. After a successful save, that token is invalidated and cannot be reused.

Save Facebook Pages API — POST {{API_BASE_URL}}/v1/connect/facebook/selection/{token}

Save selected Facebook Pages by calling POST {{API_BASE_URL}}/v1/connect/facebook/selection/{token}. The operation saves only the Pages whose identifiers you include in selectedAccountIds, then invalidates the one-time selection token. Treat the token as single-use after a successful save: do not retry the same token expecting it to save again, and do not add expiry or generation claims that are not part of this contract. The path parameter token is a required string with length at least 1. The request body is application/json and contains one required field, selectedAccountIds, an array of strings with at least 1 item. Send the identifiers exactly as returned by the preceding selection step, and check the 200 response integrations array to confirm which integrations were saved.

Path Parameters — token

The token path parameter is required and must be a string whose length is at least 1. Replace the {token} segment in the request example with the one-time selection token for the current selection flow. If the token is missing, empty, or no longer valid for a new save, the request will not produce a 200 response; handle the 400 and 404 error shapes described below rather than assuming a specific cause, because the captured contract defines only a required string error field for those statuses.

Request Body — selectedAccountIds

Send selectedAccountIds as a required array<string> with at least 1 item. This is the sole request body field in the captured contract. Include only the Facebook Page account identifiers you want saved as integrations; Pages not listed are not saved by this call. Validate locally that the array is present, is an array, contains strings, and is not empty before sending, because an empty selection does not meet the items >= 1 constraint. See the request example titled Save selected Facebook Pages request example for the exact JSON shape.

Response Body — 200 application/json

A 200 application/json response contains success as a required boolean, platform as a required string constrained to "facebook", message as a required string, redirectUri as an optional string, and integrations as a required array of integration objects. Use redirectUri when present to continue the flow after the save. Each integrations item includes id, platform, platformUserId, username, displayName, profileUrl, imageUrl, profileId, appId, app, byok, authStatus, authFailureReason, insightsReadable, and createdAt as required fields, with platformMetadata and profileName as optional fields. The id field is the identifier to use as accountId when creating posts. Check authStatus on each returned integration: it is either "active" or "reconnect_required". Check authFailureReason alongside it: it can be "token_expired", "access_revoked", "security_invalidation", "refresh_rejected", or null while active. Check insightsReadable as boolean or null, where null means not determined yet, true means readable, and false means the account did not grant the insights permission even though auth can still be active. See the field map titled 200 response field map and the example titled 200 response example.

Response Body — 400 and 404 application/json

Both 400 and 404 responses use application/json with a single required field, error, whose type is string. The captured contract does not define distinct error codes, messages, causes, or recovery actions for 400 versus 404, so client code should branch on the HTTP status, surface the error string, and avoid inventing a specific cause from the status alone. See the failure matrix titled Failure matrix for 200, 400, and 404 and the example titled 400 and 404 error response example.

Implementation checklist

Before calling, confirm the method is POST, the path is exactly /v1/connect/facebook/selection/{token} with {{API_BASE_URL}} as the origin, token is a non-empty string, and selectedAccountIds is a non-empty array of strings. After a 200 response, confirm success, platform, message, and the integrations array, store each integration id for later accountId use, inspect authStatus and authFailureReason for any integration needing reconnection, and note that the token has been invalidated. After a 400 or 404 response, read the required error string and do not reuse assumptions about why it failed. Preserve exact field names, types, requiredness, and enums when implementing or matching this endpoint.

Path and request field map
FieldRequiredTypeConstraints / notes
token (path)RequiredstringLength >= 1; one-time selection token, invalidated after a successful save
selectedAccountIds (body)Requiredarray<string>Items >= 1; sole request body field

Captured contract; illustrative_unexecuted

200 response field map
FieldRequiredTypeConstraints / notes
successRequiredboolean
platformRequiredstring"facebook"
messageRequiredstring
redirectUriOptionalstring
integrationsRequiredarray<object>Saved integrations
integrations[].idRequiredstringUse as accountId when creating posts
integrations[].platformRequiredstring"twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness"
integrations[].platformUserIdRequiredstring | nullUser ID on the platform, or null if not yet retrieved
integrations[].usernameRequiredstring | nullPublic username or handle
integrations[].displayNameRequiredstring | nullHuman-readable display name
integrations[].profileUrlRequiredstring | nullFormat: uri
integrations[].imageUrlRequiredstring | nullFormat: uri
integrations[].platformMetadataOptionalobjectProvider-specific public metadata; [key: string]: any
integrations[].profileIdRequiredstring | nullProfile this integration belongs to, or null
integrations[].profileNameOptionalstring | nullName of the profile this integration belongs to, or null
integrations[].appIdRequiredstring | nullOAuth app this integration was connected under, or null
integrations[].appRequiredobject | nullOAuth app metadata, or null; object fields id, name optional string, imageUrl optional string | null
integrations[].byokRequiredbooleanTrue when connected under the customer's own OAuth app
integrations[].authStatusRequiredstring"active" | "reconnect_required"
integrations[].authFailureReasonRequiredstring | null"token_expired" | "access_revoked" | "security_invalidation" | "refresh_rejected" | null
integrations[].insightsReadableRequiredboolean | nullnull = not determined yet, true = readable, false = insights permission not granted
integrations[].createdAtRequiredstringFormat: date-time

Captured contract; illustrative_unexecuted

Failure matrix for 200, 400, and 404
StatusContent typeFieldRequiredType
200application/jsonsuccess, platform, message, redirectUri, integrationssuccess/platform/message/integrations required; redirectUri optionalboolean, string, string, string, array<object>
400application/jsonerrorRequiredstring
404application/jsonerrorRequiredstring

Captured contract; causes not specified in source

Save selected Facebook Pages request example
curl -X POST "{{API_BASE_URL}}/v1/connect/facebook/selection/{token}" \
  -H "Content-Type: application/json" \
  -d '{
    "selectedAccountIds": [
      "string"
    ]
  }'
200 response example
{
  "success": true,
  "platform": "facebook",
  "message": "string",
  "redirectUri": "string",
  "integrations": [
    {
      "id": "string",
      "platform": "twitter",
      "platformUserId": "string",
      "username": "string",
      "displayName": "string",
      "profileUrl": "http://example.com",
      "imageUrl": "http://example.com",
      "platformMetadata": {},
      "profileId": "string",
      "profileName": "string",
      "appId": "string",
      "app": {
        "id": "string",
        "name": "string",
        "imageUrl": "string"
      },
      "byok": true,
      "authStatus": "active",
      "authFailureReason": "token_expired",
      "insightsReadable": true,
      "createdAt": "2019-08-24T14:15:22Z"
    }
  ]
}
400 and 404 error response example
{
  "error": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
response#1responseobject__0
response#1response.successboolean__1Yes
response#1response.platformstring__2Yeskind: schemaValueIn; value: "facebook"
response#1response.messagestring__3Yes
response#1response.redirectUristring__4No
response#1response.integrationsarray<object>__5Yes
response#1response.integrations[]object__6
response#1response.integrations[].idstring__7YesUse this as accountId when creating posts
response#1response.integrations[].platformstring__8Yeskind: schemaValueIn; value: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness"
response#1response.integrations[].platformUserIdstring | null__9YesThe user ID on the platform, or null if not yet retrieved
response#1response.integrations[].platformUserId[variant1]string__9_type:stringThe user ID on the platform, or null if not yet retrieved
response#1response.integrations[].platformUserId[variant2]null__9_type:nullThe user ID on the platform, or null if not yet retrieved
response#1response.integrations[].usernamestring | null__10YesThe public username or handle, including @ for handle-based platforms
response#1response.integrations[].username[variant1]string__10_type:stringThe public username or handle, including @ for handle-based platforms
response#1response.integrations[].username[variant2]null__10_type:nullThe public username or handle, including @ for handle-based platforms
response#1response.integrations[].displayNamestring | null__11YesHuman-readable display name of the connected account
response#1response.integrations[].displayName[variant1]string__11_type:stringHuman-readable display name of the connected account
response#1response.integrations[].displayName[variant2]null__11_type:nullHuman-readable display name of the connected account
response#1response.integrations[].profileUrlstring | null__12YesPublic profile/page URL for the connected account, when it can be derivedkind: schemaFormat; value: uri
response#1response.integrations[].profileUrl[variant1]string__12_type:stringPublic profile/page URL for the connected account, when it can be derivedkind: schemaFormat; value: uri
response#1response.integrations[].profileUrl[variant2]null__12_type:nullPublic profile/page URL for the connected account, when it can be derivedkind: schemaFormat; value: uri
response#1response.integrations[].imageUrlstring | null__13YesProfile image URL for the connected account, or null if unavailablekind: schemaFormat; value: uri
response#1response.integrations[].imageUrl[variant1]string__13_type:stringProfile image URL for the connected account, or null if unavailablekind: ; value: uri
response#1response.integrations[].imageUrl[variant2]null__13_type:nullProfile image URL for the connected account, or null if unavailablekind: ; value: uri
response#1response.integrations[].platformMetadataobject__14NoProvider-specific public metadata for this connected account.
response#1response.integrations[].platformMetadata.[key: string]anytrueNo
response#1response.integrations[].profileIdstring | null__15YesProfile this integration belongs to, or null if it was connected without a profile
response#1response.integrations[].profileId[variant1]string__15_type:stringProfile this integration belongs to, or null if it was connected without a profile
response#1response.integrations[].profileId[variant2]null__15_type:nullProfile this integration belongs to, or null if it was connected without a profile
response#1response.integrations[].profileNamestring | null__16NoName of the profile (social group) this integration belongs to, or null when it has no profile. Only populated on the list endpoint so clients can label the group without fetching the full profiles list.
response#1response.integrations[].profileName[variant1]string__16_type:stringName of the profile (social group) this integration belongs to, or null when it has no profile. Only populated on the list endpoint so clients can label the group without fetching the full profiles list.
response#1response.integrations[].profileName[variant2]null__16_type:nullName of the profile (social group) this integration belongs to, or null when it has no profile. Only populated on the list endpoint so clients can label the group without fetching the full profiles list.
response#1response.integrations[].appIdstring | null__17YesThe OAuth app (customer's own OAuth app) this integration was connected under, or null if the service's system app was used.
response#1response.integrations[].appId[variant1]string__17_type:stringThe OAuth app (customer's own OAuth app) this integration was connected under, or null if the service's system app was used.
response#1response.integrations[].appId[variant2]null__17_type:nullThe OAuth app (customer's own OAuth app) this integration was connected under, or null if the service's system app was used.
response#1response.integrations[].appobject | null__18YesThe OAuth app metadata for BYOK integrations, or null when the service's system app was used.
response#1response.integrations[].app[variant1]object__18_type:objectThe OAuth app metadata for BYOK integrations, or null when the service's system app was used.
response#1response.integrations[].app[variant1].idstring__19No
response#1response.integrations[].app[variant1].namestring__20No
response#1response.integrations[].app[variant1].imageUrlstring | null__21No
response#1response.integrations[].app[variant1].imageUrl[variant1]string__21_type:string
response#1response.integrations[].app[variant1].imageUrl[variant2]null__21_type:null
response#1response.integrations[].app[variant2]null__18_type:nullThe OAuth app metadata for BYOK integrations, or null when the service's system app was used.
response#1response.integrations[].byokboolean__22YesTrue when this integration was connected under the customer's own OAuth app (Bring Your Own Keys), i.e. appId is set. False when the service's system app is used.
response#1response.integrations[].authStatusstring__23YesWhether this integration can authenticate or needs OAuth reconnection
response#1response.integrations[].authStatus[variant1]string__23_extends:__24Whether this integration can authenticate or needs OAuth reconnectionkind: ; value: "active"
response#1response.integrations[].authStatus[variant2]string__23_extends:__25Whether this integration can authenticate or needs OAuth reconnectionkind: ; value: "reconnect_required"
response#1response.integrations[].authFailureReasonstring | null__26YesStable reason reconnection is required, or null while active
response#1response.integrations[].authFailureReason[variant1]string__26_extends:__27Stable reason reconnection is required, or null while activekind: ; value: "token_expired"
response#1response.integrations[].authFailureReason[variant2]string__26_extends:__28Stable reason reconnection is required, or null while activekind: ; value: "access_revoked"
response#1response.integrations[].authFailureReason[variant3]string__26_extends:__29Stable reason reconnection is required, or null while activekind: ; value: "security_invalidation"
response#1response.integrations[].authFailureReason[variant4]string__26_extends:__30Stable reason reconnection is required, or null while activekind: ; value: "refresh_rejected"
response#1response.integrations[].authFailureReason[variant5]null__26_extends:__31Stable reason reconnection is required, or null while active
response#1response.integrations[].insightsReadableboolean | null__32YesWhether this account can read analytics/insights. null = not determined yet, true = readable, false = the account did not grant the insights permission (auth can still be active). Reconnect and approve the analytics permission to fix a false.
response#1response.integrations[].insightsReadable[variant1]boolean__32_type:booleanWhether this account can read analytics/insights. null = not determined yet, true = readable, false = the account did not grant the insights permission (auth can still be active). Reconnect and approve the analytics permission to fix a false.
response#1response.integrations[].insightsReadable[variant2]null__32_type:nullWhether this account can read analytics/insights. null = not determined yet, true = readable, false = the account did not grant the insights permission (auth can still be active). Reconnect and approve the analytics permission to fix a false.
response#1response.integrations[].createdAtstring__33Yeskind: ; value: date-time
response#2responseobject__0
response#2response.errorstring__1Yes