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.
| Field | Required | Type | Constraints / notes |
|---|---|---|---|
| token (path) | Required | string | Length >= 1; one-time selection token, invalidated after a successful save |
| selectedAccountIds (body) | Required | array<string> | Items >= 1; sole request body field |
Captured contract; illustrative_unexecuted
| Field | Required | Type | Constraints / notes |
|---|---|---|---|
| success | Required | boolean | |
| platform | Required | string | "facebook" |
| message | Required | string | |
| redirectUri | Optional | string | |
| integrations | Required | array<object> | Saved integrations |
| integrations[].id | Required | string | Use as accountId when creating posts |
| integrations[].platform | Required | string | "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness" |
| integrations[].platformUserId | Required | string | null | User ID on the platform, or null if not yet retrieved |
| integrations[].username | Required | string | null | Public username or handle |
| integrations[].displayName | Required | string | null | Human-readable display name |
| integrations[].profileUrl | Required | string | null | Format: uri |
| integrations[].imageUrl | Required | string | null | Format: uri |
| integrations[].platformMetadata | Optional | object | Provider-specific public metadata; [key: string]: any |
| integrations[].profileId | Required | string | null | Profile this integration belongs to, or null |
| integrations[].profileName | Optional | string | null | Name of the profile this integration belongs to, or null |
| integrations[].appId | Required | string | null | OAuth app this integration was connected under, or null |
| integrations[].app | Required | object | null | OAuth app metadata, or null; object fields id, name optional string, imageUrl optional string | null |
| integrations[].byok | Required | boolean | True when connected under the customer's own OAuth app |
| integrations[].authStatus | Required | string | "active" | "reconnect_required" |
| integrations[].authFailureReason | Required | string | null | "token_expired" | "access_revoked" | "security_invalidation" | "refresh_rejected" | null |
| integrations[].insightsReadable | Required | boolean | null | null = not determined yet, true = readable, false = insights permission not granted |
| integrations[].createdAt | Required | string | Format: date-time |
Captured contract; illustrative_unexecuted
| Status | Content type | Field | Required | Type |
|---|---|---|---|---|
| 200 | application/json | success, platform, message, redirectUri, integrations | success/platform/message/integrations required; redirectUri optional | boolean, string, string, string, array<object> |
| 400 | application/json | error | Required | string |
| 404 | application/json | error | Required | string |
Captured contract; causes not specified in source
curl -X POST "{{API_BASE_URL}}/v1/connect/facebook/selection/{token}" \
-H "Content-Type: application/json" \
-d '{
"selectedAccountIds": [
"string"
]
}'{
"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"
}
]
}{
"error": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| response#1 | response | object | __0 | |||
| response#1 | response.success | boolean | __1 | Yes | ||
| response#1 | response.platform | string | __2 | Yes | kind: schemaValueIn; value: "facebook" | |
| response#1 | response.message | string | __3 | Yes | ||
| response#1 | response.redirectUri | string | __4 | No | ||
| response#1 | response.integrations | array<object> | __5 | Yes | ||
| response#1 | response.integrations[] | object | __6 | |||
| response#1 | response.integrations[].id | string | __7 | Yes | Use this as accountId when creating posts | |
| response#1 | response.integrations[].platform | string | __8 | Yes | kind: schemaValueIn; value: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness" | |
| response#1 | response.integrations[].platformUserId | string | null | __9 | Yes | The user ID on the platform, or null if not yet retrieved | |
| response#1 | response.integrations[].platformUserId[variant1] | string | __9_type:string | The user ID on the platform, or null if not yet retrieved | ||
| response#1 | response.integrations[].platformUserId[variant2] | null | __9_type:null | The user ID on the platform, or null if not yet retrieved | ||
| response#1 | response.integrations[].username | string | null | __10 | Yes | The public username or handle, including @ for handle-based platforms | |
| response#1 | response.integrations[].username[variant1] | string | __10_type:string | The public username or handle, including @ for handle-based platforms | ||
| response#1 | response.integrations[].username[variant2] | null | __10_type:null | The public username or handle, including @ for handle-based platforms | ||
| response#1 | response.integrations[].displayName | string | null | __11 | Yes | Human-readable display name of the connected account | |
| response#1 | response.integrations[].displayName[variant1] | string | __11_type:string | Human-readable display name of the connected account | ||
| response#1 | response.integrations[].displayName[variant2] | null | __11_type:null | Human-readable display name of the connected account | ||
| response#1 | response.integrations[].profileUrl | string | null | __12 | Yes | Public profile/page URL for the connected account, when it can be derived | kind: schemaFormat; value: uri |
| response#1 | response.integrations[].profileUrl[variant1] | string | __12_type:string | Public profile/page URL for the connected account, when it can be derived | kind: schemaFormat; value: uri | |
| response#1 | response.integrations[].profileUrl[variant2] | null | __12_type:null | Public profile/page URL for the connected account, when it can be derived | kind: schemaFormat; value: uri | |
| response#1 | response.integrations[].imageUrl | string | null | __13 | Yes | Profile image URL for the connected account, or null if unavailable | kind: schemaFormat; value: uri |
| response#1 | response.integrations[].imageUrl[variant1] | string | __13_type:string | Profile image URL for the connected account, or null if unavailable | kind: ; value: uri | |
| response#1 | response.integrations[].imageUrl[variant2] | null | __13_type:null | Profile image URL for the connected account, or null if unavailable | kind: ; value: uri | |
| response#1 | response.integrations[].platformMetadata | object | __14 | No | Provider-specific public metadata for this connected account. | |
| response#1 | response.integrations[].platformMetadata.[key: string] | any | true | No | ||
| response#1 | response.integrations[].profileId | string | null | __15 | Yes | Profile this integration belongs to, or null if it was connected without a profile | |
| response#1 | response.integrations[].profileId[variant1] | string | __15_type:string | Profile this integration belongs to, or null if it was connected without a profile | ||
| response#1 | response.integrations[].profileId[variant2] | null | __15_type:null | Profile this integration belongs to, or null if it was connected without a profile | ||
| response#1 | response.integrations[].profileName | string | null | __16 | No | Name 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#1 | response.integrations[].profileName[variant1] | string | __16_type:string | Name 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#1 | response.integrations[].profileName[variant2] | null | __16_type:null | Name 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#1 | response.integrations[].appId | string | null | __17 | Yes | The OAuth app (customer's own OAuth app) this integration was connected under, or null if the service's system app was used. | |
| response#1 | response.integrations[].appId[variant1] | string | __17_type:string | The OAuth app (customer's own OAuth app) this integration was connected under, or null if the service's system app was used. | ||
| response#1 | response.integrations[].appId[variant2] | null | __17_type:null | The OAuth app (customer's own OAuth app) this integration was connected under, or null if the service's system app was used. | ||
| response#1 | response.integrations[].app | object | null | __18 | Yes | The OAuth app metadata for BYOK integrations, or null when the service's system app was used. | |
| response#1 | response.integrations[].app[variant1] | object | __18_type:object | The OAuth app metadata for BYOK integrations, or null when the service's system app was used. | ||
| response#1 | response.integrations[].app[variant1].id | string | __19 | No | ||
| response#1 | response.integrations[].app[variant1].name | string | __20 | No | ||
| response#1 | response.integrations[].app[variant1].imageUrl | string | null | __21 | No | ||
| response#1 | response.integrations[].app[variant1].imageUrl[variant1] | string | __21_type:string | |||
| response#1 | response.integrations[].app[variant1].imageUrl[variant2] | null | __21_type:null | |||
| response#1 | response.integrations[].app[variant2] | null | __18_type:null | The OAuth app metadata for BYOK integrations, or null when the service's system app was used. | ||
| response#1 | response.integrations[].byok | boolean | __22 | Yes | True 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#1 | response.integrations[].authStatus | string | __23 | Yes | Whether this integration can authenticate or needs OAuth reconnection | |
| response#1 | response.integrations[].authStatus[variant1] | string | __23_extends:__24 | Whether this integration can authenticate or needs OAuth reconnection | kind: ; value: "active" | |
| response#1 | response.integrations[].authStatus[variant2] | string | __23_extends:__25 | Whether this integration can authenticate or needs OAuth reconnection | kind: ; value: "reconnect_required" | |
| response#1 | response.integrations[].authFailureReason | string | null | __26 | Yes | Stable reason reconnection is required, or null while active | |
| response#1 | response.integrations[].authFailureReason[variant1] | string | __26_extends:__27 | Stable reason reconnection is required, or null while active | kind: ; value: "token_expired" | |
| response#1 | response.integrations[].authFailureReason[variant2] | string | __26_extends:__28 | Stable reason reconnection is required, or null while active | kind: ; value: "access_revoked" | |
| response#1 | response.integrations[].authFailureReason[variant3] | string | __26_extends:__29 | Stable reason reconnection is required, or null while active | kind: ; value: "security_invalidation" | |
| response#1 | response.integrations[].authFailureReason[variant4] | string | __26_extends:__30 | Stable reason reconnection is required, or null while active | kind: ; value: "refresh_rejected" | |
| response#1 | response.integrations[].authFailureReason[variant5] | null | __26_extends:__31 | Stable reason reconnection is required, or null while active | ||
| response#1 | response.integrations[].insightsReadable | boolean | null | __32 | Yes | Whether 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#1 | response.integrations[].insightsReadable[variant1] | boolean | __32_type:boolean | Whether 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#1 | response.integrations[].insightsReadable[variant2] | null | __32_type:null | Whether 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#1 | response.integrations[].createdAt | string | __33 | Yes | kind: ; value: date-time | |
| response#2 | response | object | __0 | |||
| response#2 | response.error | string | __1 | Yes |