Skip to content

Submit LinkedIn Selection API

The Submit LinkedIn Selection API saves the LinkedIn accounts chosen during a headless mode connect flow. Use it only after GET /v1/connect/linkedin/selection/:token has returned the pending choices, passing the one-time token in the path and the chosen account identifiers in the request body. A successful call saves the selected personal profile and/or organization pages, returns the resulting integrations, and invalidates the one-time selection token.

Operation summary and prerequisite headless flow

This operation is the final step of a headless LinkedIn connect flow. First retrieve the pending choices with GET /v1/connect/linkedin/selection/:token, present the personal profile and organization pages to the user, then submit the identifiers the user selected. The endpoint is POST /v1/connect/linkedin/selection/{token}, where {token} is replaced with the one-time selection token from the prerequisite call. After a successful save, that token is invalidated, so treat the submission as a single-use step and do not reuse the same token for another selection. The request sample titled Submit LinkedIn selection request shows the origin-modular form using {{API_BASE_URL}} before the unchanged path.

Path Parameters

The path parameter token is required and is a string with length 1 <= length. It identifies the pending headless selection created by the prerequisite GET call. Send it exactly as the path segment in POST /v1/connect/linkedin/selection/{token}; do not move it into the body or query string. If the token is missing or empty, the request cannot satisfy the documented length constraint.

Request Body

The request body is application/json and contains one required field, selectedAccountIds. It is an array of strings with 1 <= items, so send at least one account identifier and include only identifiers returned as pending choices for that token. The array represents the personal profile and/or organization pages the user chose to save. Validate the array locally before sending: confirm it is present, is an array, contains at least one string item, and matches the choices shown to the user.

Response Body

A 200 application/json response contains success as a required boolean, platform as a required string with the value "linkedin", message as a required string, redirectUri as an optional string, and integrations as a required array of objects. Use redirectUri, when present, as the continuation target returned for this flow, and use integrations to confirm which accounts were saved. Each integration object includes required fields such as id, platform, platformUserId, username, displayName, profileUrl, imageUrl, profileId, appId, app, byok, authStatus, authFailureReason, insightsReadable, and createdAt, with optional platformMetadata and profileName. In particular, check authStatus to see whether the saved integration is active or reconnect_required, and check platformUserId for the platform-side user identifier, which may be null if not yet retrieved. The 200 response example illustrates these fields with placeholder values.

Failure handling

Both documented failure responses use the same minimal shape: a required string field named error. A 400 application/json response returns {"error": "string"} and a 404 application/json response returns {"error": "string"}, as shown in the 400 response example and the 404 response example. Handle these separately from a 200 response: do not read integrations or redirectUri from an error body, and surface the error string to the caller for diagnosis. The source contract does not state more specific error conditions, so do not assume additional fields or meanings beyond the documented shape.

Input contract checklist

Before calling, run this checklist: confirm the prerequisite GET /v1/connect/linkedin/selection/:token succeeded, copy its token into the POST path, confirm selectedAccountIds has at least one item, and confirm the identifiers match the pending choices. After the call, confirm the status is 200, read success, platform, and message, store each integrations entry by its id, inspect authStatus and platformUserId, and follow redirectUri only when it is present. If the status is 400 or 404, read only the error field and stop, because the token has not produced a successful saved selection in that response.

Path parameter field map
FieldRequiredTypeConstraint / Notes
tokenYesstring1 <= length; one-time selection token in path

Exact source contract

Request body field map
FieldRequiredTypeConstraint / Notes
selectedAccountIdsYesarray<string>1 <= items; identifiers of selected personal profile and/or organization pages

Exact source contract

200 response field map
FieldRequiredTypeConstraint / Notes
successYesboolean
platformYesstring"linkedin"
messageYesstring
redirectUriNostringOptional continuation URI
integrationsYesarray<object>Saved account integrations
integrations[].idYesstringUse as accountId when creating posts
integrations[].platformYesstring"twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness"
integrations[].platformUserIdYesstring | nullUser ID on the platform, or null if not yet retrieved
integrations[].usernameYesstring | nullPublic username or handle
integrations[].displayNameYesstring | nullHuman-readable display name
integrations[].profileUrlYesstring | nullFormat: uri
integrations[].imageUrlYesstring | nullFormat: uri
integrations[].platformMetadataNoobjectProvider-specific public metadata
integrations[].profileIdYesstring | nullProfile this integration belongs to, or null
integrations[].profileNameNostring | nullName of the profile this integration belongs to, or null
integrations[].appIdYesstring | nullOAuth app this integration was connected under, or null
integrations[].appYesobject | nullOAuth app metadata, or null
integrations[].app.idNostringPresent when app is an object
integrations[].app.nameNostringPresent when app is an object
integrations[].app.imageUrlNostring | nullPresent when app is an object
integrations[].byokYesbooleanTrue when connected under the customer's own OAuth app
integrations[].authStatusYesstring"active" | "reconnect_required"
integrations[].authFailureReasonYesstring | null"token_expired" | "access_revoked" | "security_invalidation" | "refresh_rejected" | null
integrations[].insightsReadableYesboolean | nullnull = not determined yet, true = readable, false = insights permission not granted
integrations[].createdAtYesstringFormat: date-time

Exact source contract

Failure matrix
StatusFieldRequiredType
400 application/jsonerrorYesstring
404 application/jsonerrorYesstring

Exact source contract; conditions beyond shape not stated

Submit LinkedIn selection request
curl -X POST "{{API_BASE_URL}}/v1/connect/linkedin/selection/string" \
  -H "Content-Type: application/json" \
  -d '{
    "selectedAccountIds": [
      "string"
    ]
  }'
200 response example
{
  "success": true,
  "platform": "linkedin",
  "message": "string",
  "redirectUri": "string",
  "integrations": [
    {
      "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"
    }
  ]
}
400 response example
{
  "error": "string"
}
404 response example
{
  "error": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
response#1responseobject__0
response#1response.successboolean__1Yes
response#1response.platformstring__2Yeskind: schemaValueIn; value: "linkedin"
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