Skip to content

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.

Input contract
LocationFieldRequiredTypeConstraints
PathtokenRequiredstringLength 20 <= length <= 100
Request bodyselectedAccountIdsRequiredarray<string>Items 1 <= items <= 1

Exact captured input contract

200 response field map
FieldRequiredTypeNotes
successRequiredbooleanSuccess flag
platformRequiredstringEnum: "instagram"
messageRequiredstringResponse message
redirectUriOptionalstringRedirect URI when supplied
integrationsRequiredarray<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

Error responses
StatusFieldRequiredType
400errorRequiredstring
404errorRequiredstring
409errorRequiredstring

Exact captured error contract; no specific causes stated in source

Submit Instagram Selection request
curl -X POST "{{API_BASE_URL}}/v1/connect/instagram/selection/{token}" \
  -H "Content-Type: application/json" \
  -d '{
    "selectedAccountIds": [
      "<selected-account-id>"
    ]
  }'
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
response#1responseobject__0
response#1response.successboolean__1Yes
response#1response.platformstring__2Yeskind: schemaValueIn; value: "instagram"
response#1response.messagestring__3Yes
response#1response.redirectUristring__4No
response#1response.integrationsarray<object>__5Yes
response#1response.integrations[]object__6
response#1response.integrations[].idstring__7YesUse this as accountId when creating posts
response#1response.integrations[].platformstring__8Yeskind: schemaValueIn; value: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness"
response#1response.integrations[].platformUserIdstring | null__9YesThe user ID on the platform, or null if not yet retrieved
response#1response.integrations[].platformUserId[variant1]string__9_type:stringThe user ID on the platform, or null if not yet retrieved
response#1response.integrations[].platformUserId[variant2]null__9_type:nullThe user ID on the platform, or null if not yet retrieved
response#1response.integrations[].usernamestring | null__10YesThe public username or handle, including @ for handle-based platforms
response#1response.integrations[].username[variant1]string__10_type:stringThe public username or handle, including @ for handle-based platforms
response#1response.integrations[].username[variant2]null__10_type:nullThe public username or handle, including @ for handle-based platforms
response#1response.integrations[].displayNamestring | null__11YesHuman-readable display name of the connected account
response#1response.integrations[].displayName[variant1]string__11_type:stringHuman-readable display name of the connected account
response#1response.integrations[].displayName[variant2]null__11_type:nullHuman-readable display name of the connected account
response#1response.integrations[].profileUrlstring | null__12YesPublic profile/page URL for the connected account, when it can be derivedkind: schemaFormat; value: uri
response#1response.integrations[].profileUrl[variant1]string__12_type:stringPublic profile/page URL for the connected account, when it can be derivedkind: schemaFormat; value: uri
response#1response.integrations[].profileUrl[variant2]null__12_type:nullPublic profile/page URL for the connected account, when it can be derivedkind: schemaFormat; value: uri
response#1response.integrations[].imageUrlstring | null__13YesProfile image URL for the connected account, or null if unavailablekind: schemaFormat; value: uri
response#1response.integrations[].imageUrl[variant1]string__13_type:stringProfile image URL for the connected account, or null if unavailablekind: ; value: uri
response#1response.integrations[].imageUrl[variant2]null__13_type:nullProfile image URL for the connected account, or null if unavailablekind: ; value: uri
response#1response.integrations[].platformMetadataobject__14NoProvider-specific public metadata for this connected account.
response#1response.integrations[].platformMetadata.[key: string]anytrueNo
response#1response.integrations[].profileIdstring | null__15YesProfile this integration belongs to, or null if it was connected without a profile
response#1response.integrations[].profileId[variant1]string__15_type:stringProfile this integration belongs to, or null if it was connected without a profile
response#1response.integrations[].profileId[variant2]null__15_type:nullProfile this integration belongs to, or null if it was connected without a profile
response#1response.integrations[].profileNamestring | null__16NoName 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#1response.integrations[].profileName[variant1]string__16_type:stringName 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#1response.integrations[].profileName[variant2]null__16_type:nullName 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#1response.integrations[].appIdstring | null__17YesThe OAuth app (customer's own OAuth app) this integration was connected under, or null if the service's system app was used.
response#1response.integrations[].appId[variant1]string__17_type:stringThe OAuth app (customer's own OAuth app) this integration was connected under, or null if the service's system app was used.
response#1response.integrations[].appId[variant2]null__17_type:nullThe OAuth app (customer's own OAuth app) this integration was connected under, or null if the service's system app was used.
response#1response.integrations[].appobject | null__18YesThe OAuth app metadata for BYOK integrations, or null when the service's system app was used.
response#1response.integrations[].app[variant1]object__18_type:objectThe OAuth app metadata for BYOK integrations, or null when the service's system app was used.
response#1response.integrations[].app[variant1].idstring__19No
response#1response.integrations[].app[variant1].namestring__20No
response#1response.integrations[].app[variant1].imageUrlstring | null__21No
response#1response.integrations[].app[variant1].imageUrl[variant1]string__21_type:string
response#1response.integrations[].app[variant1].imageUrl[variant2]null__21_type:null
response#1response.integrations[].app[variant2]null__18_type:nullThe OAuth app metadata for BYOK integrations, or null when the service's system app was used.
response#1response.integrations[].byokboolean__22YesTrue 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#1response.integrations[].authStatusstring__23YesWhether this integration can authenticate or needs OAuth reconnection
response#1response.integrations[].authStatus[variant1]string__23_extends:__24Whether this integration can authenticate or needs OAuth reconnectionkind: ; value: "active"
response#1response.integrations[].authStatus[variant2]string__23_extends:__25Whether this integration can authenticate or needs OAuth reconnectionkind: ; value: "reconnect_required"
response#1response.integrations[].authFailureReasonstring | null__26YesStable reason reconnection is required, or null while active
response#1response.integrations[].authFailureReason[variant1]string__26_extends:__27Stable reason reconnection is required, or null while activekind: ; value: "token_expired"
response#1response.integrations[].authFailureReason[variant2]string__26_extends:__28Stable reason reconnection is required, or null while activekind: ; value: "access_revoked"
response#1response.integrations[].authFailureReason[variant3]string__26_extends:__29Stable reason reconnection is required, or null while activekind: ; value: "security_invalidation"
response#1response.integrations[].authFailureReason[variant4]string__26_extends:__30Stable reason reconnection is required, or null while activekind: ; value: "refresh_rejected"
response#1response.integrations[].authFailureReason[variant5]null__26_extends:__31Stable reason reconnection is required, or null while active
response#1response.integrations[].insightsReadableboolean | null__32YesWhether 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#1response.integrations[].insightsReadable[variant1]boolean__32_type:booleanWhether 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#1response.integrations[].insightsReadable[variant2]null__32_type:nullWhether 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#1response.integrations[].createdAtstring__33Yeskind: ; value: date-time
response#2responseobject__0
response#2response.errorstring__1Yes