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.
| Parameter | Location | Required | Type | Constraint |
|---|---|---|---|---|
| token | path | required | string | 20 <= length <= 100 |
Exact input contract from supplied source; no additional parameters documented.
| Field | Required | Type | Enum / Notes |
|---|---|---|---|
| success | required | boolean | Gate for successful response |
| platform | required | string | "instagram" |
| expiresInSeconds | required | number | Expiry timing field |
| accounts | required | array<object> | Selected account objects |
200 application/json response; exact field names and types preserved.
| Field | Required | Type | Enum / Notes |
|---|---|---|---|
| id | required | string | |
| type | required | string | "page" |
| platformUserId | required | string | Instagram user identifier |
| username | required | string | |
| displayName | required | string | |
| imageUrl | optional | string | Only optional account field |
Nested object inside accounts array.
| Status | Content-Type | Body Fields | Client Action |
|---|---|---|---|
| 200 | application/json | success, platform, expiresInSeconds, accounts | Consume accounts and expiresInSeconds |
| 404 | application/json | error (required string) | Read error; do not expect 200 fields |
| Client validation | n/a | token length outside 20-100 | Stop 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.
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"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| token#1 | token | string | __0 | Yes | kind: schemaLength; value: 20 <= length <= 100 | |
| response#2 | response | object | __0 | |||
| response#2 | response.success | boolean | __1 | Yes | ||
| response#2 | response.platform | string | __2 | Yes | kind: schemaValueIn; value: "instagram" | |
| 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[].username | string | __9 | Yes | ||
| response#2 | response.accounts[].displayName | string | __10 | Yes | ||
| response#2 | response.accounts[].imageUrl | string | __11 | No | ||
| response#3 | response | object | __0 | |||
| response#3 | response.error | string | __1 | Yes |