Get integration details API
The Get integration details API returns one connected social integration by its Integration ID, including its platform account identity, recorded OAuth scopes, and token expiry metadata. OAuth tokens are never returned, so callers can inspect scopes, accessTokenExpiresAt, refreshTokenExpiresAt, and tokenStatus without handling secret tokens.
Get integration details API overview
Use this endpoint when you already have an integration ID and need to verify which platform account it represents, which OAuth scopes were recorded when it was connected, and whether the connection can still authenticate. The request is a GET to {{API_BASE_URL}}/v1/connect/integrations/{id} with the Integration ID placed in the path. Send the access key in the x-access-key header. A successful lookup returns a success flag and an integration object; an unknown ID returns the documented 404 error shape. OAuth tokens are never returned, so treat the response as metadata for decisions about posting, analytics, and reconnection rather than as credentials.
Authorization and path parameter
Authorization uses the x-access-key header with a token value. Place the Integration ID in the path as the required string parameter id. There are no query parameters or request body fields documented for this operation. If the ID does not identify an integration, handle the 404 response and its error field instead of expecting an integration object. See the request example titled Get integration details request for the exact header and path form.
Reading the 200 integration object
The 200 response contains success as a required boolean and integration as a required object. Read platform to branch by social platform, platformUserId for the user ID on that platform, and username and displayName for the public handle and human-readable name. Use profileUrl and imageUrl when present for display, and platformMetadata for provider-specific public metadata when present. The id field is the integration identifier to reuse as accountId when creating posts. Fields marked nullable in the field map can be null, so check for null before rendering or using them as strings.
Identity, app, auth, and capability fields
Group the remaining fields by purpose when implementing checks. Profile fields such as profileId and profileName show which profile group the integration belongs to, with profileName only populated on the list endpoint. App and BYOK fields such as appId, app, and byok show whether the integration was connected under a customer's own OAuth app. Auth and token fields such as authStatus, authFailureReason, insightsReadable, scopes, accessTokenExpiresAt, refreshTokenExpiresAt, and tokenStatus drive reconnect decisions. Timestamps createdAt and updatedAt and the capability flag supportsExternalPostSync complete the object. See the field map titled 200 response field map for types, requiredness, and nullability for every field.
Token and auth status decision matrix
Decide the next action from the combination of authStatus, authFailureReason, and tokenStatus rather than from any single field. When authStatus is active and tokenStatus.valid is true with reconnectRequired false, the integration can authenticate. When authStatus is reconnect_required, use authFailureReason and tokenStatus.reason to explain why reconnection is needed, such as token_expired, access_revoked, security_invalidation, or refresh_rejected. When tokenStatus.reason is insights_permission_missing, valid can still be true because publishing works while analytics calls will fail until the insights permission is granted through reconnection; insightsReadable false points to the same fix. Use autoRefreshes to know whether the platform token is refreshed automatically when needed, and compare accessTokenExpiresAt and refreshTokenExpiresAt against the current time when planning refresh or reconnect prompts. See the decision matrix titled Token and auth status decision matrix for the mapping.
Worked example and 404 handling
For a worked check, request one integration ID and then read platform, username, scopes, accessTokenExpiresAt, refreshTokenExpiresAt, and tokenStatus from the 200 response. Confirm that scopes lists the OAuth scopes recorded at connection time, that the expiry fields are either date-time strings or null when the provider does not report an expiry, and that tokenStatus.reconnectRequired tells you whether to start OAuth again. If the response is 404, read the required string error field and treat the ID as unknown or inaccessible. See the examples titled 200 response example and 404 response example for the exact shapes.
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | Yes | string | Integration ID |
Exact source contract
| Field | Required | Type | Notes |
|---|---|---|---|
| success | Yes | boolean | Top-level success flag |
| integration | Yes | object | The integration object |
| integration.id | Yes | string | Use this as accountId when creating posts |
| integration.platform | Yes | string | Enum: twitter | instagram | youtube | tiktok | pinterest | linkedin | bluesky | facebook | threads | googlebusiness |
| integration.platformUserId | Yes | string | null | User ID on the platform, or null if not yet retrieved |
| integration.username | Yes | string | null | Public username or handle, including @ for handle-based platforms |
| integration.displayName | Yes | string | null | Human-readable display name of the connected account |
| integration.profileUrl | Yes | string | null (uri) | Public profile/page URL when it can be derived |
| integration.imageUrl | Yes | string | null (uri) | Profile image URL, or null if unavailable |
| integration.platformMetadata | No | object | Provider-specific public metadata; [key: string]: any |
| integration.profileId | Yes | string | null | Profile this integration belongs to, or null if connected without a profile |
| integration.profileName | No | string | null | Name of the profile group; only populated on the list endpoint |
| integration.appId | Yes | string | null | Customer's own OAuth app ID, or null if the system app was used |
| integration.app | Yes | object | null | OAuth app metadata for BYOK integrations, or null when the system app was used; object fields id (optional string), name (optional string), imageUrl (optional string | null) |
| integration.byok | Yes | boolean | True when connected under the customer's own OAuth app |
| integration.authStatus | Yes | string | Enum: active | reconnect_required |
| integration.authFailureReason | Yes | string | null | Enum: token_expired | access_revoked | security_invalidation | refresh_rejected | null; null while active |
| integration.insightsReadable | Yes | boolean | null | null = not determined yet; true = readable; false = insights permission not granted |
| integration.createdAt | Yes | string (date-time) | Creation timestamp |
| integration.scopes | Yes | array<string> | OAuth scopes recorded when this integration was connected |
| integration.accessTokenExpiresAt | Yes | string | null (date-time) | Access token expiry, or null when the provider does not report an expiry |
| integration.refreshTokenExpiresAt | Yes | string | null (date-time) | Refresh token expiry, or null when the provider does not report an expiry |
| integration.tokenStatus | Yes | object | Nested token status object; see decision matrix |
| integration.tokenStatus.valid | Yes | boolean | Whether recorded expiry metadata indicates the integration can authenticate |
| integration.tokenStatus.autoRefreshes | Yes | boolean | Whether the platform token is automatically refreshed when needed |
| integration.tokenStatus.reconnectRequired | Yes | boolean | Whether OAuth should be completed again |
| integration.tokenStatus.reason | Yes | string | null | Enum: token_expired | access_revoked | security_invalidation | refresh_rejected | insights_permission_missing | null |
| integration.updatedAt | Yes | string (date-time) | Last update timestamp |
| integration.supportsExternalPostSync | Yes | boolean | Whether this integration can import recent posts published outside the system |
| error (404) | Yes | string | Error message in the 404 application/json response |
Exact source contract; nullable fields marked
| authStatus | authFailureReason / tokenStatus.reason | tokenStatus.valid | tokenStatus.autoRefreshes | tokenStatus.reconnectRequired | Next action |
|---|---|---|---|---|---|
| active | null / null | true | true or false | false | Integration can authenticate; proceed normally |
| active | null / insights_permission_missing | true | true or false | true | Publishing works but analytics will fail; reconnect and approve the analytics/insights permission; insightsReadable false indicates the missing permission |
| reconnect_required | token_expired / token_expired | false or true per recorded expiry metadata | true or false | true | Complete OAuth again; check accessTokenExpiresAt and refreshTokenExpiresAt |
| reconnect_required | access_revoked / access_revoked | false or true per recorded expiry metadata | true or false | true | Complete OAuth again because access was revoked |
| reconnect_required | security_invalidation / security_invalidation | false or true per recorded expiry metadata | true or false | true | Complete OAuth again after security invalidation |
| reconnect_required | refresh_rejected / refresh_rejected | false or true per recorded expiry metadata | true or false | true | Complete OAuth again because the refresh token was rejected |
Derived directly from documented field semantics; no new enums introduced
curl -X GET "{{API_BASE_URL}}/v1/connect/integrations/{id}" \
-H "x-access-key: <token>"{
"success": true,
"integration": {
"id": "string",
"platform": "twitter",
"platformUserId": "string",
"username": "string",
"displayName": "string",
"profileUrl": "http://example.com",
"imageUrl": "http://example.com",
"platformMetadata": {},
"profileId": "string",
"profileName": "string",
"appId": "string",
"app": {
"id": "string",
"name": "string",
"imageUrl": "string"
},
"byok": true,
"authStatus": "active",
"authFailureReason": "token_expired",
"insightsReadable": true,
"createdAt": "2019-08-24T14:15:22Z",
"scopes": [
"string"
],
"accessTokenExpiresAt": "2019-08-24T14:15:22Z",
"refreshTokenExpiresAt": "2019-08-24T14:15:22Z",
"tokenStatus": {
"valid": true,
"autoRefreshes": true,
"reconnectRequired": true,
"reason": "token_expired"
},
"updatedAt": "2019-08-24T14:15:22Z",
"supportsExternalPostSync": true
}
}{
"error": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| response#1 | response | object | __0 | |||
| response#1 | response.success | boolean | __1 | Yes | ||
| response#1 | response.integration | object | __2 | Yes | ||
| response#1 | response.integration.id | string | __3 | Yes | Use this as accountId when creating posts | |
| response#1 | response.integration.platform | string | __4 | Yes | kind: schemaValueIn; value: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness" | |
| response#1 | response.integration.platformUserId | string | null | __5 | Yes | The user ID on the platform, or null if not yet retrieved | |
| response#1 | response.integration.platformUserId[variant1] | string | __5_type:string | The user ID on the platform, or null if not yet retrieved | ||
| response#1 | response.integration.platformUserId[variant2] | null | __5_type:null | The user ID on the platform, or null if not yet retrieved | ||
| response#1 | response.integration.username | string | null | __6 | Yes | The public username or handle, including @ for handle-based platforms | |
| response#1 | response.integration.username[variant1] | string | __6_type:string | The public username or handle, including @ for handle-based platforms | ||
| response#1 | response.integration.username[variant2] | null | __6_type:null | The public username or handle, including @ for handle-based platforms | ||
| response#1 | response.integration.displayName | string | null | __7 | Yes | Human-readable display name of the connected account | |
| response#1 | response.integration.displayName[variant1] | string | __7_type:string | Human-readable display name of the connected account | ||
| response#1 | response.integration.displayName[variant2] | null | __7_type:null | Human-readable display name of the connected account | ||
| response#1 | response.integration.profileUrl | string | null | __8 | Yes | Public profile/page URL for the connected account, when it can be derived | kind: schemaFormat; value: uri |
| response#1 | response.integration.profileUrl[variant1] | string | __8_type:string | Public profile/page URL for the connected account, when it can be derived | kind: schemaFormat; value: uri | |
| response#1 | response.integration.profileUrl[variant2] | null | __8_type:null | Public profile/page URL for the connected account, when it can be derived | kind: schemaFormat; value: uri | |
| response#1 | response.integration.imageUrl | string | null | __9 | Yes | Profile image URL for the connected account, or null if unavailable | kind: schemaFormat; value: uri |
| response#1 | response.integration.imageUrl[variant1] | string | __9_type:string | Profile image URL for the connected account, or null if unavailable | kind: schemaFormat; value: uri | |
| response#1 | response.integration.imageUrl[variant2] | null | __9_type:null | Profile image URL for the connected account, or null if unavailable | kind: schemaFormat; value: uri | |
| response#1 | response.integration.platformMetadata | object | __10 | No | Provider-specific public metadata for this connected account. | |
| response#1 | response.integration.platformMetadata.[key: string] | any | true | No | ||
| response#1 | response.integration.profileId | string | null | __11 | Yes | Profile this integration belongs to, or null if it was connected without a profile | |
| response#1 | response.integration.profileId[variant1] | string | __11_type:string | Profile this integration belongs to, or null if it was connected without a profile | ||
| response#1 | response.integration.profileId[variant2] | null | __11_type:null | Profile this integration belongs to, or null if it was connected without a profile | ||
| response#1 | response.integration.profileName | string | null | __12 | 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.integration.profileName[variant1] | string | __12_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.integration.profileName[variant2] | null | __12_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.integration.appId | string | null | __13 | 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.integration.appId[variant1] | string | __13_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.integration.appId[variant2] | null | __13_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.integration.app | object | null | __14 | Yes | The OAuth app metadata for BYOK integrations, or null when the service's system app was used. | |
| response#1 | response.integration.app[variant1] | object | __14_type:object | The OAuth app metadata for BYOK integrations, or null when the service's system app was used. | ||
| response#1 | response.integration.app[variant1].id | string | __15 | No | ||
| response#1 | response.integration.app[variant1].name | string | __16 | No | ||
| response#1 | response.integration.app[variant1].imageUrl | string | null | __17 | No | ||
| response#1 | response.integration.app[variant1].imageUrl[variant1] | string | __17_type:string | |||
| response#1 | response.integration.app[variant1].imageUrl[variant2] | null | __17_type:null | |||
| response#1 | response.integration.app[variant2] | null | __14_type:null | The OAuth app metadata for BYOK integrations, or null when the service's system app was used. | ||
| response#1 | response.integration.byok | boolean | __18 | 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.integration.authStatus | string | __19 | Yes | Whether this integration can authenticate or needs OAuth reconnection | |
| response#1 | response.integration.authStatus[variant1] | string | __19_extends:__20 | Whether this integration can authenticate or needs OAuth reconnection | kind: ; value: "active" | |
| response#1 | response.integration.authStatus[variant2] | string | __19_extends:__21 | Whether this integration can authenticate or needs OAuth reconnection | kind: ; value: "reconnect_required" | |
| response#1 | response.integration.authFailureReason | string | null | __22 | Yes | Stable reason reconnection is required, or null while active | |
| response#1 | response.integration.authFailureReason[variant1] | string | __22_extends:__23 | Stable reason reconnection is required, or null while active | kind: ; value: "token_expired" | |
| response#1 | response.integration.authFailureReason[variant2] | string | __22_extends:__24 | Stable reason reconnection is required, or null while active | kind: ; value: "access_revoked" | |
| response#1 | response.integration.authFailureReason[variant3] | string | __22_extends:__25 | Stable reason reconnection is required, or null while active | kind: ; value: "security_invalidation" | |
| response#1 | response.integration.authFailureReason[variant4] | string | __22_extends:__26 | Stable reason reconnection is required, or null while active | kind: ; value: "refresh_rejected" | |
| response#1 | response.integration.authFailureReason[variant5] | null | __22_extends:__27 | Stable reason reconnection is required, or null while active | ||
| response#1 | response.integration.insightsReadable | boolean | null | __28 | 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.integration.insightsReadable[variant1] | boolean | __28_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.integration.insightsReadable[variant2] | null | __28_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.integration.createdAt | string | __29 | Yes | kind: ; value: date-time | |
| response#1 | response.integration.scopes | array<string> | __30 | Yes | OAuth scopes recorded when this integration was connected | |
| response#1 | response.integration.scopes[] | string | __31 | |||
| response#1 | response.integration.accessTokenExpiresAt | string | null | __32 | Yes | When the current access token expires, or null when the provider does not report an expiry | kind: ; value: date-time |
| response#1 | response.integration.accessTokenExpiresAt[variant1] | string | __32_type:string | When the current access token expires, or null when the provider does not report an expiry | kind: ; value: date-time | |
| response#1 | response.integration.accessTokenExpiresAt[variant2] | null | __32_type:null | When the current access token expires, or null when the provider does not report an expiry | kind: ; value: date-time | |
| response#1 | response.integration.refreshTokenExpiresAt | string | null | __33 | Yes | When the refresh token expires, or null when the provider does not report an expiry | kind: ; value: date-time |
| response#1 | response.integration.refreshTokenExpiresAt[variant1] | string | __33_type:string | When the refresh token expires, or null when the provider does not report an expiry | kind: ; value: date-time | |
| response#1 | response.integration.refreshTokenExpiresAt[variant2] | null | __33_type:null | When the refresh token expires, or null when the provider does not report an expiry | kind: ; value: date-time | |
| response#1 | response.integration.tokenStatus | object | __34 | Yes | ||
| response#1 | response.integration.tokenStatus.valid | boolean | __35 | Yes | Whether recorded expiry metadata indicates the integration can authenticate. Provider revocation is detected when the integration is used. | |
| response#1 | response.integration.tokenStatus.autoRefreshes | boolean | __36 | Yes | Whether the service automatically refreshes this platform token when needed. | |
| response#1 | response.integration.tokenStatus.reconnectRequired | boolean | __37 | Yes | Whether this integration should complete OAuth again — either the token needs re-auth, or (Instagram/Threads) the insights permission is missing so analytics calls will fail until reconnected. valid can still be true when only insights are missing, since publishing works. | |
| response#1 | response.integration.tokenStatus.reason | string | null | __38 | Yes | ||
| response#1 | response.integration.tokenStatus.reason[variant1] | string | __38_extends:__39 | kind: ; value: "token_expired" | ||
| response#1 | response.integration.tokenStatus.reason[variant2] | string | __38_extends:__40 | kind: ; value: "access_revoked" | ||
| response#1 | response.integration.tokenStatus.reason[variant3] | string | __38_extends:__41 | kind: ; value: "security_invalidation" | ||
| response#1 | response.integration.tokenStatus.reason[variant4] | string | __38_extends:__42 | kind: ; value: "refresh_rejected" | ||
| response#1 | response.integration.tokenStatus.reason[variant5] | string | __38_extends:__43 | kind: ; value: "insights_permission_missing" | ||
| response#1 | response.integration.tokenStatus.reason[variant6] | null | __38_extends:__44 | |||
| response#1 | response.integration.updatedAt | string | __45 | Yes | kind: ; value: date-time | |
| response#1 | response.integration.supportsExternalPostSync | boolean | __46 | Yes | Whether this specific integration can import recent posts published outside the service. | |
| response#2 | response | object | __0 | |||
| response#2 | response.error | string | __1 | Yes |