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.
| Field | Required | Type | Constraint / Notes |
|---|---|---|---|
| token | Yes | string | 1 <= length; one-time selection token in path |
Exact source contract
| Field | Required | Type | Constraint / Notes |
|---|---|---|---|
| selectedAccountIds | Yes | array<string> | 1 <= items; identifiers of selected personal profile and/or organization pages |
Exact source contract
| Field | Required | Type | Constraint / Notes |
|---|---|---|---|
| success | Yes | boolean | |
| platform | Yes | string | "linkedin" |
| message | Yes | string | |
| redirectUri | No | string | Optional continuation URI |
| integrations | Yes | array<object> | Saved account integrations |
| integrations[].id | Yes | string | Use as accountId when creating posts |
| integrations[].platform | Yes | string | "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness" |
| integrations[].platformUserId | Yes | string | null | User ID on the platform, or null if not yet retrieved |
| integrations[].username | Yes | string | null | Public username or handle |
| integrations[].displayName | Yes | string | null | Human-readable display name |
| integrations[].profileUrl | Yes | string | null | Format: uri |
| integrations[].imageUrl | Yes | string | null | Format: uri |
| integrations[].platformMetadata | No | object | Provider-specific public metadata |
| integrations[].profileId | Yes | string | null | Profile this integration belongs to, or null |
| integrations[].profileName | No | string | null | Name of the profile this integration belongs to, or null |
| integrations[].appId | Yes | string | null | OAuth app this integration was connected under, or null |
| integrations[].app | Yes | object | null | OAuth app metadata, or null |
| integrations[].app.id | No | string | Present when app is an object |
| integrations[].app.name | No | string | Present when app is an object |
| integrations[].app.imageUrl | No | string | null | Present when app is an object |
| integrations[].byok | Yes | boolean | True when connected under the customer's own OAuth app |
| integrations[].authStatus | Yes | string | "active" | "reconnect_required" |
| integrations[].authFailureReason | Yes | string | null | "token_expired" | "access_revoked" | "security_invalidation" | "refresh_rejected" | null |
| integrations[].insightsReadable | Yes | boolean | null | null = not determined yet, true = readable, false = insights permission not granted |
| integrations[].createdAt | Yes | string | Format: date-time |
Exact source contract
| Status | Field | Required | Type |
|---|---|---|---|
| 400 application/json | error | Yes | string |
| 404 application/json | error | Yes | string |
Exact source contract; conditions beyond shape not stated
curl -X POST "{{API_BASE_URL}}/v1/connect/linkedin/selection/string" \
-H "Content-Type: application/json" \
-d '{
"selectedAccountIds": [
"string"
]
}'{
"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"
}
]
}{
"error": "string"
}{
"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.platform | string | __2 | Yes | kind: schemaValueIn; value: "linkedin" | |
| 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 |