Skip to content

Get Instagram Selection API

The Get Instagram Selection API retrieves the selected Instagram account or accounts for a given token. Call GET {{API_BASE_URL}}/v1/connect/instagram/selection/{token} with a valid token to receive the selection, its expiry timing in expiresInSeconds, and the accounts array containing platformUserId, username, displayName, and optional imageUrl for each account.

Get Instagram Selection API operation summary

Use this operation when a flow has produced a token and you need to resolve that token to the Instagram selection it represents. The request is a single GET with no documented body, query parameters, or headers in the supplied contract. Replace the token segment with the token value you received, keeping the path exactly as /v1/connect/instagram/selection/{token} after the configured base URL. Before sending, check that the token is a string whose length is between 20 and 100 characters inclusive; a value outside that range does not satisfy the input contract and should be treated as a client-side failure rather than sent as a valid selection lookup.

Token path parameter input contract

The only input is the token path parameter. It is required, typed as string, and constrained to 20 <= length <= 100. There are no optional path parameters and no documented query parameters for this operation. Keep the token in the path segment exactly where the contract places it, and do not move it to a query string or header, because the documented route is defined by that path position.

Successful 200 response field map

A successful call returns 200 with an application/json body. The top-level object requires success as a boolean, platform as a string with the single enum value instagram, expiresInSeconds as a number, and accounts as an array of account objects. Treat success as the gate for consuming the rest of the payload: only when it is present as documented should you read platform, expiresInSeconds, and accounts as a successful selection. The platform value confirms the selection is for Instagram, and expiresInSeconds reports the expiry timing field returned with the selection.

Account object field map

Each entry in accounts is an object with required id, type, platformUserId, username, and displayName fields, plus an optional imageUrl field. The type field is a string with the single enum value page. Use id as the account object identifier, platformUserId as the Instagram user identifier, username for the handle, and displayName for presentation. Read imageUrl only when it is present, since it is the one optional field in the account object; do not assume every account will include it. When building a picker or summary view, prefer platformUserId for stable identification and username or displayName for display, rather than relying on imageUrl.

Worked example

The worked example below shows the origin-modular request using {{API_BASE_URL}} before the unchanged path, followed by the documented 200 and 404 response shapes. Use it to align your client parsing with the exact field names and types: success, platform, expiresInSeconds, accounts, and the nested account fields. Replace the example token value with a real token value in your own client, and parse the response by status code first so the 404 error shape is never mistaken for a successful selection.

Failure handling

A 404 response returns application/json with a required error string field. When you receive 404, read error for the failure message and do not expect success, platform, expiresInSeconds, or accounts in that body. Separately, guard against invalid token length on the client: if the token is shorter than 20 or longer than 100 characters, stop and surface a validation failure before calling, because the input contract does not accept such a value. The source defines accounts as a required array with no minimum length, so do not invent an additional empty-array rule beyond the documented contract.

Token path parameter input contract
ParameterLocationRequiredTypeConstraint
tokenpathrequiredstring20 <= length <= 100

Exact input contract from supplied source; no additional parameters documented.

200 response field map
FieldRequiredTypeEnum / Notes
successrequiredbooleanGate for successful response
platformrequiredstring"instagram"
expiresInSecondsrequirednumberExpiry timing field
accountsrequiredarray<object>Selected account objects

200 application/json response; exact field names and types preserved.

Account object field map
FieldRequiredTypeEnum / Notes
idrequiredstring
typerequiredstring"page"
platformUserIdrequiredstringInstagram user identifier
usernamerequiredstring
displayNamerequiredstring
imageUrloptionalstringOnly optional account field

Nested object inside accounts array.

Failure matrix
StatusContent-TypeBody FieldsClient Action
200application/jsonsuccess, platform, expiresInSeconds, accountsConsume accounts and expiresInSeconds
404application/jsonerror (required string)Read error; do not expect 200 fields
Client validationn/atoken length outside 20-100Stop before calling; input contract not satisfied

Documented failure contracts; specific 404 conditions beyond error field not specified in source.

Frequently asked questions

How do I retrieve an Instagram selection by token?

Send GET to {{API_BASE_URL}}/v1/connect/instagram/selection/{token} with a token string of length 20 to 100. On 200, read success, platform, expiresInSeconds, and the accounts array. On 404, read the required error string.

Which account fields should I consume?

Each accounts entry requires id, type, platformUserId, username, and displayName. type is the enum value "page". imageUrl is optional. Use platformUserId to identify the Instagram user, username and displayName for presentation, and imageUrl only when present.

What should I check when the token is invalid or not found?

Validate the token length before calling: it must be a string with 20 <= length <= 100. If the call returns 404 application/json, handle the body as an object with a required error string field rather than expecting the 200 fields.

Worked request and response example
curl -X GET "{{API_BASE_URL}}/v1/connect/instagram/selection/stringstringstringst"

# Illustrative 200 response (unexecuted example)
{
  "success": true,
  "platform": "instagram",
  "expiresInSeconds": 0,
  "accounts": [
    {
      "id": "string",
      "type": "page",
      "platformUserId": "string",
      "username": "string",
      "displayName": "string",
      "imageUrl": "string"
    }
  ]
}

# Illustrative 404 response (unexecuted example)
{
  "error": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
token#1tokenstring__0Yeskind: schemaLength; value: 20 <= length <= 100
response#2responseobject__0
response#2response.successboolean__1Yes
response#2response.platformstring__2Yeskind: schemaValueIn; value: "instagram"
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[].usernamestring__9Yes
response#2response.accounts[].displayNamestring__10Yes
response#2response.accounts[].imageUrlstring__11No
response#3responseobject__0
response#3response.errorstring__1Yes