Skip to content

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.

200 response field map
FieldTypeRequiredNotes
successbooleanYesTop-level success flag
platformstringYesFixed value: facebook
expiresInSecondsnumberYesSeconds until the selection token expires
accountsarray<object>YesPending Facebook Page choices
accounts[].idstringYesAccount identifier
accounts[].typestringYesFixed value: page
accounts[].platformUserIdstringYesPlatform user identifier for the account
accounts[].displayNamestring | nullYesMay be null
accounts[].usernamestring | nullYesMay be null
accounts[].imageUrlstring | nullYesURI string when present; may be null

Exact parity fields from supplied contract; displayName, username, and imageUrl are string | null.

Failure and handling matrix
StatusFieldTypeRequiredHandling
404errorstringYesVerify token value, expiry, and whether the one-time token was already consumed; restart OAuth selection if no longer valid
200accountsarray<object>YesIf empty, no pending choices are available for that token
200expiresInSecondsnumberYesUse 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.

Get Facebook Selection API request and responses
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"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
token#1tokenstring__0Yeskind: schemaLength; value: 1 <= length
response#2responseobject__0
response#2response.successboolean__1Yes
response#2response.platformstring__2Yeskind: schemaValueIn; value: "facebook"
response#2response.expiresInSecondsnumber__3Yes
response#2response.accountsarray<object>__4Yes
response#2response.accounts[]object__5
response#2response.accounts[].idstring__6Yes
response#2response.accounts[].typestring__7Yeskind: schemaValueIn; value: "page"
response#2response.accounts[].platformUserIdstring__8Yes
response#2response.accounts[].displayNamestring | null__9Yes
response#2response.accounts[].displayName[variant1]string__9_type:string
response#2response.accounts[].displayName[variant2]null__9_type:null
response#2response.accounts[].usernamestring | null__10Yes
response#2response.accounts[].username[variant1]string__10_type:string
response#2response.accounts[].username[variant2]null__10_type:null
response#2response.accounts[].imageUrlstring | null__11Yeskind: ; value: uri
response#2response.accounts[].imageUrl[variant1]string__11_type:stringkind: ; value: uri
response#2response.accounts[].imageUrl[variant2]null__11_type:nullkind: ; value: uri
response#3responseobject__0
response#3response.errorstring__1Yes