Get Facebook Selection API
The Get Facebook Selection API retrieves pending Facebook Page choices after OAuth when a user must choose which Pages to connect. It uses a short-lived, one-time selection token in the path, returns the available accounts with their expiry window, and prepares the next step of saving the selected Pages.
Operation summary and exact request
Use this operation when OAuth has completed but the connecting user still needs to choose which Facebook Pages to connect. The endpoint returns the Facebook Pages available for that pending selection. The selection token is short-lived and one-time, so retrieve the choices promptly after the OAuth step and treat the token as single-use. The exact request is GET {{API_BASE_URL}}/v1/connect/facebook/selection/{token}.
Required token path parameter
The only input is the token path parameter. It is required, typed as string, and must have length at least 1. Replace the token segment with the selection token issued for the pending Facebook Page choice step. Do not add undocumented query parameters or body fields to this GET request, because the supplied contract defines token as the sole path parameter.
200 response field map
A 200 application/json response contains success as a boolean, platform fixed to facebook, expiresInSeconds as a number, and accounts as an array of account objects. Each account object contains id as a string, type fixed to page, platformUserId as a string, displayName as string or null, username as string or null, and imageUrl as string or null with a URI format when present. Use expiresInSeconds to show how long the pending selection remains available, and handle null displayName, username, and imageUrl values when building a Page picker. The worked example titled Get Facebook Selection API request and responses shows the exact request line and both documented response shapes.
404 response and failure checks
A 404 application/json response contains error as a required string. The supplied contract documents the error shape but does not define additional causes, retry behavior, or rate limits, so do not invent a more specific meaning. When you receive 404, first verify that the token in the path matches the pending selection token, that the token has not expired, and that the selection has not already been consumed, because the token is one-time. If the token is no longer valid, restart the OAuth selection step to obtain a new token rather than retrying the same token indefinitely.
Worked example and next step
Call this endpoint to list pending choices; call Save selected Facebook Pages to save the user's chosen Pages. That distinction matters because retrieval only presents the available accounts and their expiry, while saving is the step that records the selection. If expiresInSeconds is low, present the choices immediately and complete the save step before the window closes. If the accounts array is empty, there are no pending Page choices to present for that token, so return the user to the OAuth selection step instead of proceeding to save.
| Field | Type | Required | Notes |
|---|---|---|---|
| success | boolean | Yes | Top-level success flag |
| platform | string | Yes | Fixed value: facebook |
| expiresInSeconds | number | Yes | Seconds until the selection token expires |
| accounts | array<object> | Yes | Pending Facebook Page choices |
| accounts[].id | string | Yes | Account identifier |
| accounts[].type | string | Yes | Fixed value: page |
| accounts[].platformUserId | string | Yes | Platform user identifier for the account |
| accounts[].displayName | string | null | Yes | May be null |
| accounts[].username | string | null | Yes | May be null |
| accounts[].imageUrl | string | null | Yes | URI string when present; may be null |
Exact parity fields from supplied contract; displayName, username, and imageUrl are string | null.
| Status | Field | Type | Required | Handling |
|---|---|---|---|---|
| 404 | error | string | Yes | Verify token value, expiry, and whether the one-time token was already consumed; restart OAuth selection if no longer valid |
| 200 | accounts | array<object> | Yes | If empty, no pending choices are available for that token |
| 200 | expiresInSeconds | number | Yes | Use to time the picker and the save step before expiry |
404 causes beyond the documented error shape are not specified in the supplied source and are not invented here.
Frequently asked questions
What token does the Get Facebook Selection API require?
The token is the required path parameter for GET /v1/connect/facebook/selection/{token}. It must be a string with length at least 1. The selection token is short-lived and one-time, so use the token from the OAuth selection step promptly and do not reuse it after it has been consumed or expired.
What does a successful 200 response contain?
A 200 response returns success, platform set to facebook, expiresInSeconds, and an accounts array. Each account includes id, type set to page, platformUserId, displayName, username, and imageUrl. The displayName, username, and imageUrl fields are string or null, so handle null values when rendering choices.
What should I do when the endpoint returns 404?
A 404 response returns an error string in the documented shape. The supplied contract does not define additional causes for 404, retry behavior, or rate limits, so do not assume a specific cause beyond the documented error shape. Check that the token value in the path is correct and that the selection step is still pending.
When should I call this endpoint versus Save selected Facebook Pages?
Use this endpoint to retrieve pending Facebook Page choices after OAuth when the user must choose which Pages to connect. After the user chooses, use Save selected Facebook Pages as the next step. Do not use this retrieval endpoint as a substitute for saving the selection.
curl -X GET "{{API_BASE_URL}}/v1/connect/facebook/selection/string"
# Illustrative 200 response (application/json)
{
"success": true,
"platform": "facebook",
"expiresInSeconds": 0,
"accounts": [
{
"id": "string",
"type": "page",
"platformUserId": "string",
"displayName": "string",
"username": "string",
"imageUrl": "http://example.com"
}
]
}
# Illustrative 404 response (application/json)
{
"error": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| token#1 | token | string | __0 | Yes | kind: schemaLength; value: 1 <= length | |
| response#2 | response | object | __0 | |||
| response#2 | response.success | boolean | __1 | Yes | ||
| response#2 | response.platform | string | __2 | Yes | kind: schemaValueIn; value: "facebook" | |
| response#2 | response.expiresInSeconds | number | __3 | Yes | ||
| response#2 | response.accounts | array<object> | __4 | Yes | ||
| response#2 | response.accounts[] | object | __5 | |||
| response#2 | response.accounts[].id | string | __6 | Yes | ||
| response#2 | response.accounts[].type | string | __7 | Yes | kind: schemaValueIn; value: "page" | |
| response#2 | response.accounts[].platformUserId | string | __8 | Yes | ||
| response#2 | response.accounts[].displayName | string | null | __9 | Yes | ||
| response#2 | response.accounts[].displayName[variant1] | string | __9_type:string | |||
| response#2 | response.accounts[].displayName[variant2] | null | __9_type:null | |||
| response#2 | response.accounts[].username | string | null | __10 | Yes | ||
| response#2 | response.accounts[].username[variant1] | string | __10_type:string | |||
| response#2 | response.accounts[].username[variant2] | null | __10_type:null | |||
| response#2 | response.accounts[].imageUrl | string | null | __11 | Yes | kind: ; value: uri | |
| response#2 | response.accounts[].imageUrl[variant1] | string | __11_type:string | kind: ; value: uri | ||
| response#2 | response.accounts[].imageUrl[variant2] | null | __11_type:null | kind: ; value: uri | ||
| response#3 | response | object | __0 | |||
| response#3 | response.error | string | __1 | Yes |