Skip to content

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.

Path parameters
ParameterRequiredTypeDescription
idYesstringIntegration ID

Exact source contract

200 response field map
FieldRequiredTypeNotes
successYesbooleanTop-level success flag
integrationYesobjectThe integration object
integration.idYesstringUse this as accountId when creating posts
integration.platformYesstringEnum: twitter | instagram | youtube | tiktok | pinterest | linkedin | bluesky | facebook | threads | googlebusiness
integration.platformUserIdYesstring | nullUser ID on the platform, or null if not yet retrieved
integration.usernameYesstring | nullPublic username or handle, including @ for handle-based platforms
integration.displayNameYesstring | nullHuman-readable display name of the connected account
integration.profileUrlYesstring | null (uri)Public profile/page URL when it can be derived
integration.imageUrlYesstring | null (uri)Profile image URL, or null if unavailable
integration.platformMetadataNoobjectProvider-specific public metadata; [key: string]: any
integration.profileIdYesstring | nullProfile this integration belongs to, or null if connected without a profile
integration.profileNameNostring | nullName of the profile group; only populated on the list endpoint
integration.appIdYesstring | nullCustomer's own OAuth app ID, or null if the system app was used
integration.appYesobject | nullOAuth 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.byokYesbooleanTrue when connected under the customer's own OAuth app
integration.authStatusYesstringEnum: active | reconnect_required
integration.authFailureReasonYesstring | nullEnum: token_expired | access_revoked | security_invalidation | refresh_rejected | null; null while active
integration.insightsReadableYesboolean | nullnull = not determined yet; true = readable; false = insights permission not granted
integration.createdAtYesstring (date-time)Creation timestamp
integration.scopesYesarray<string>OAuth scopes recorded when this integration was connected
integration.accessTokenExpiresAtYesstring | null (date-time)Access token expiry, or null when the provider does not report an expiry
integration.refreshTokenExpiresAtYesstring | null (date-time)Refresh token expiry, or null when the provider does not report an expiry
integration.tokenStatusYesobjectNested token status object; see decision matrix
integration.tokenStatus.validYesbooleanWhether recorded expiry metadata indicates the integration can authenticate
integration.tokenStatus.autoRefreshesYesbooleanWhether the platform token is automatically refreshed when needed
integration.tokenStatus.reconnectRequiredYesbooleanWhether OAuth should be completed again
integration.tokenStatus.reasonYesstring | nullEnum: token_expired | access_revoked | security_invalidation | refresh_rejected | insights_permission_missing | null
integration.updatedAtYesstring (date-time)Last update timestamp
integration.supportsExternalPostSyncYesbooleanWhether this integration can import recent posts published outside the system
error (404)YesstringError message in the 404 application/json response

Exact source contract; nullable fields marked

Token and auth status decision matrix
authStatusauthFailureReason / tokenStatus.reasontokenStatus.validtokenStatus.autoRefreshestokenStatus.reconnectRequiredNext action
activenull / nulltruetrue or falsefalseIntegration can authenticate; proceed normally
activenull / insights_permission_missingtruetrue or falsetruePublishing works but analytics will fail; reconnect and approve the analytics/insights permission; insightsReadable false indicates the missing permission
reconnect_requiredtoken_expired / token_expiredfalse or true per recorded expiry metadatatrue or falsetrueComplete OAuth again; check accessTokenExpiresAt and refreshTokenExpiresAt
reconnect_requiredaccess_revoked / access_revokedfalse or true per recorded expiry metadatatrue or falsetrueComplete OAuth again because access was revoked
reconnect_requiredsecurity_invalidation / security_invalidationfalse or true per recorded expiry metadatatrue or falsetrueComplete OAuth again after security invalidation
reconnect_requiredrefresh_rejected / refresh_rejectedfalse or true per recorded expiry metadatatrue or falsetrueComplete OAuth again because the refresh token was rejected

Derived directly from documented field semantics; no new enums introduced

Get integration details request
curl -X GET "{{API_BASE_URL}}/v1/connect/integrations/{id}" \
  -H "x-access-key: <token>"
200 response example
{
  "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
  }
}
404 response example
{
  "error": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
response#1responseobject__0
response#1response.successboolean__1Yes
response#1response.integrationobject__2Yes
response#1response.integration.idstring__3YesUse this as accountId when creating posts
response#1response.integration.platformstring__4Yeskind: schemaValueIn; value: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness"
response#1response.integration.platformUserIdstring | null__5YesThe user ID on the platform, or null if not yet retrieved
response#1response.integration.platformUserId[variant1]string__5_type:stringThe user ID on the platform, or null if not yet retrieved
response#1response.integration.platformUserId[variant2]null__5_type:nullThe user ID on the platform, or null if not yet retrieved
response#1response.integration.usernamestring | null__6YesThe public username or handle, including @ for handle-based platforms
response#1response.integration.username[variant1]string__6_type:stringThe public username or handle, including @ for handle-based platforms
response#1response.integration.username[variant2]null__6_type:nullThe public username or handle, including @ for handle-based platforms
response#1response.integration.displayNamestring | null__7YesHuman-readable display name of the connected account
response#1response.integration.displayName[variant1]string__7_type:stringHuman-readable display name of the connected account
response#1response.integration.displayName[variant2]null__7_type:nullHuman-readable display name of the connected account
response#1response.integration.profileUrlstring | null__8YesPublic profile/page URL for the connected account, when it can be derivedkind: schemaFormat; value: uri
response#1response.integration.profileUrl[variant1]string__8_type:stringPublic profile/page URL for the connected account, when it can be derivedkind: schemaFormat; value: uri
response#1response.integration.profileUrl[variant2]null__8_type:nullPublic profile/page URL for the connected account, when it can be derivedkind: schemaFormat; value: uri
response#1response.integration.imageUrlstring | null__9YesProfile image URL for the connected account, or null if unavailablekind: schemaFormat; value: uri
response#1response.integration.imageUrl[variant1]string__9_type:stringProfile image URL for the connected account, or null if unavailablekind: schemaFormat; value: uri
response#1response.integration.imageUrl[variant2]null__9_type:nullProfile image URL for the connected account, or null if unavailablekind: schemaFormat; value: uri
response#1response.integration.platformMetadataobject__10NoProvider-specific public metadata for this connected account.
response#1response.integration.platformMetadata.[key: string]anytrueNo
response#1response.integration.profileIdstring | null__11YesProfile this integration belongs to, or null if it was connected without a profile
response#1response.integration.profileId[variant1]string__11_type:stringProfile this integration belongs to, or null if it was connected without a profile
response#1response.integration.profileId[variant2]null__11_type:nullProfile this integration belongs to, or null if it was connected without a profile
response#1response.integration.profileNamestring | null__12NoName 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.integration.profileName[variant1]string__12_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.integration.profileName[variant2]null__12_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.integration.appIdstring | null__13YesThe OAuth app (customer's own OAuth app) this integration was connected under, or null if the service's system app was used.
response#1response.integration.appId[variant1]string__13_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.integration.appId[variant2]null__13_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.integration.appobject | null__14YesThe OAuth app metadata for BYOK integrations, or null when the service's system app was used.
response#1response.integration.app[variant1]object__14_type:objectThe OAuth app metadata for BYOK integrations, or null when the service's system app was used.
response#1response.integration.app[variant1].idstring__15No
response#1response.integration.app[variant1].namestring__16No
response#1response.integration.app[variant1].imageUrlstring | null__17No
response#1response.integration.app[variant1].imageUrl[variant1]string__17_type:string
response#1response.integration.app[variant1].imageUrl[variant2]null__17_type:null
response#1response.integration.app[variant2]null__14_type:nullThe OAuth app metadata for BYOK integrations, or null when the service's system app was used.
response#1response.integration.byokboolean__18YesTrue 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.integration.authStatusstring__19YesWhether this integration can authenticate or needs OAuth reconnection
response#1response.integration.authStatus[variant1]string__19_extends:__20Whether this integration can authenticate or needs OAuth reconnectionkind: ; value: "active"
response#1response.integration.authStatus[variant2]string__19_extends:__21Whether this integration can authenticate or needs OAuth reconnectionkind: ; value: "reconnect_required"
response#1response.integration.authFailureReasonstring | null__22YesStable reason reconnection is required, or null while active
response#1response.integration.authFailureReason[variant1]string__22_extends:__23Stable reason reconnection is required, or null while activekind: ; value: "token_expired"
response#1response.integration.authFailureReason[variant2]string__22_extends:__24Stable reason reconnection is required, or null while activekind: ; value: "access_revoked"
response#1response.integration.authFailureReason[variant3]string__22_extends:__25Stable reason reconnection is required, or null while activekind: ; value: "security_invalidation"
response#1response.integration.authFailureReason[variant4]string__22_extends:__26Stable reason reconnection is required, or null while activekind: ; value: "refresh_rejected"
response#1response.integration.authFailureReason[variant5]null__22_extends:__27Stable reason reconnection is required, or null while active
response#1response.integration.insightsReadableboolean | null__28YesWhether 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.integration.insightsReadable[variant1]boolean__28_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.integration.insightsReadable[variant2]null__28_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.integration.createdAtstring__29Yeskind: ; value: date-time
response#1response.integration.scopesarray<string>__30YesOAuth scopes recorded when this integration was connected
response#1response.integration.scopes[]string__31
response#1response.integration.accessTokenExpiresAtstring | null__32YesWhen the current access token expires, or null when the provider does not report an expirykind: ; value: date-time
response#1response.integration.accessTokenExpiresAt[variant1]string__32_type:stringWhen the current access token expires, or null when the provider does not report an expirykind: ; value: date-time
response#1response.integration.accessTokenExpiresAt[variant2]null__32_type:nullWhen the current access token expires, or null when the provider does not report an expirykind: ; value: date-time
response#1response.integration.refreshTokenExpiresAtstring | null__33YesWhen the refresh token expires, or null when the provider does not report an expirykind: ; value: date-time
response#1response.integration.refreshTokenExpiresAt[variant1]string__33_type:stringWhen the refresh token expires, or null when the provider does not report an expirykind: ; value: date-time
response#1response.integration.refreshTokenExpiresAt[variant2]null__33_type:nullWhen the refresh token expires, or null when the provider does not report an expirykind: ; value: date-time
response#1response.integration.tokenStatusobject__34Yes
response#1response.integration.tokenStatus.validboolean__35YesWhether recorded expiry metadata indicates the integration can authenticate. Provider revocation is detected when the integration is used.
response#1response.integration.tokenStatus.autoRefreshesboolean__36YesWhether the service automatically refreshes this platform token when needed.
response#1response.integration.tokenStatus.reconnectRequiredboolean__37YesWhether 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#1response.integration.tokenStatus.reasonstring | null__38Yes
response#1response.integration.tokenStatus.reason[variant1]string__38_extends:__39kind: ; value: "token_expired"
response#1response.integration.tokenStatus.reason[variant2]string__38_extends:__40kind: ; value: "access_revoked"
response#1response.integration.tokenStatus.reason[variant3]string__38_extends:__41kind: ; value: "security_invalidation"
response#1response.integration.tokenStatus.reason[variant4]string__38_extends:__42kind: ; value: "refresh_rejected"
response#1response.integration.tokenStatus.reason[variant5]string__38_extends:__43kind: ; value: "insights_permission_missing"
response#1response.integration.tokenStatus.reason[variant6]null__38_extends:__44
response#1response.integration.updatedAtstring__45Yeskind: ; value: date-time
response#1response.integration.supportsExternalPostSyncboolean__46YesWhether this specific integration can import recent posts published outside the service.
response#2responseobject__0
response#2response.errorstring__1Yes