Submit Instagram Selection API
The Submit Instagram Selection API submits one selected Instagram account during a connect flow. It uses POST /v1/connect/instagram/selection/{token}, where token is the required path parameter, and a JSON request body containing selectedAccountIds. A successful response returns the integration in integrations, including its authStatus and insightsReadable state, so a client can store the integration id for later use and decide whether authentication or insights access needs attention.
Operation summary and request steps
Use this operation when a connect flow has presented Instagram account choices and the user has picked exactly one account. Send the connect token in the path and the chosen account identifier in selectedAccountIds. The request body accepts only one item, so do not send an empty array or multiple account identifiers to this endpoint. After a 200 response, read integrations[0] for the connected account details. Its id is the integration identifier to retain, platformUserId identifies the user on Instagram when retrieved, and username, displayName, profileUrl and imageUrl describe the public account when available. If redirectUri is present in the response, treat it as the next location supplied by the flow; it is optional and may be absent.
How to call it and interpret the result
Build the request in three checks before sending it. First, confirm the token value is a string between 20 and 100 characters long, because the path parameter contract rejects values outside that range. Second, confirm selectedAccountIds contains exactly one string item. Third, send the body as application/json and inspect the status code rather than assuming success from a parsed body alone. On 200, branch on the returned integration authStatus: active means the integration can authenticate, while reconnect_required means OAuth reconnection is needed. When authStatus is reconnect_required, use authFailureReason to distinguish token_expired, access_revoked, security_invalidation and refresh_rejected, and expect that field to be null while the integration is active. Separately check insightsReadable: null means insights access is not yet determined, true means analytics and insights are readable, and false means the account did not grant the insights permission even though authentication can still be active, so reconnect and approve the analytics permission to fix a false value. On 400, 404 or 409, read the error string from the response body and surface it without assuming a more specific cause than the contract states.
| Location | Field | Required | Type | Constraints |
|---|---|---|---|---|
| Path | token | Required | string | Length 20 <= length <= 100 |
| Request body | selectedAccountIds | Required | array<string> | Items 1 <= items <= 1 |
Exact captured input contract
| Field | Required | Type | Notes |
|---|---|---|---|
| success | Required | boolean | Success flag |
| platform | Required | string | Enum: "instagram" |
| message | Required | string | Response message |
| redirectUri | Optional | string | Redirect URI when supplied |
| integrations | Required | array<object> | Returned integrations; each item includes id, platform, platformUserId, username, displayName, profileUrl, imageUrl, platformMetadata, profileId, profileName, appId, app, byok, authStatus, authFailureReason, insightsReadable and createdAt with the captured requiredness, nullable variants, enums and formats |
Exact captured 200 response contract
| Status | Field | Required | Type |
|---|---|---|---|
| 400 | error | Required | string |
| 404 | error | Required | string |
| 409 | error | Required | string |
Exact captured error contract; no specific causes stated in source
curl -X POST "{{API_BASE_URL}}/v1/connect/instagram/selection/{token}" \
-H "Content-Type: application/json" \
-d '{
"selectedAccountIds": [
"<selected-account-id>"
]
}'| 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: "instagram" | |
| 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 |