Get LinkedIn Selection API
The Get LinkedIn Selection API supports LinkedIn account selection in headless mode. It belongs in the flow after LinkedIn OAuth is launched with headless=true and the redirect back to redirectUri carries status=selection_required plus a selectionToken. Calling it with that token gives your app the choices to show: a personal profile and any organization pages tied to the signed-in user.
When to call this endpoint after a headless LinkedIn OAuth callback
Reach for this endpoint only once a headless LinkedIn OAuth flow has arrived at its account-choice stage. The signal is precise: the OAuth launch used headless=true, and the redirectUri callback arrived with status=selection_required alongside a selectionToken. Without those two callback values, the call has no valid input, since the token it needs originates there. With the token in hand, substitute it for token and fetch the pending options. That list is what the user may pick from, spanning a personal profile plus any organization pages linked to the account. Build the picker from each entry's displayName and imageUrl where available, and preserve the pairing of id with platformUserId so a later save step can act on the exact account chosen. Check expiresInSeconds in the reply and reflect that window in the interface instead of treating the token as open-ended.
Request: GET {{API_BASE_URL}}/v1/connect/linkedin/selection/{token}
Issue a GET against the selection path, replacing token with the selectionToken received in the callback. That path parameter is a required string and must contain at least one character, so a blank value cannot make a valid request. Handle the token as opaque: pass it through unchanged rather than trimming, shortening, or rebuilding it. When the callback lacks a token, halt and treat the OAuth flow as incomplete; do not call with a made-up placeholder. The request example below demonstrates the call in origin-modular form, keeping the method and path exactly as specified.
Response Body: 200 application/json field map
On success, the API answers 200 with an application/json object containing four required fields. success is a boolean, platform is the string "linkedin", expiresInSeconds is a number describing the token lifetime, and accounts is an array of account objects. Every account object carries a required string id, a required type set to "person" for a personal profile or "organization" for organization pages, and a required string platformUserId. Three further fields — displayName, username, and imageUrl — are required by the schema yet nullable, so parsers must accept string or null for each and never assume a name, handle, or picture exists. A non-null imageUrl is a URI. In the choice UI, distinguish person entries from organization entries, since they represent different kinds of LinkedIn presence despite sharing one field shape.
Response Body: 404 application/json and error handling
A 404 reply is an application/json object holding one required string field, error. On receiving it, surface that error value as the reason the lookup failed; there is no accounts list to parse. The source leaves the triggers for a 404, the possible error strings, and any distinction between missing and invalid tokens unspecified, so this guide does not invent messages or retry rules beyond the documented error field. As a practical check, confirm the callback truly included status=selection_required and a non-empty selectionToken before calling, and treat a 404 as a failed lookup that sends the user back through LinkedIn OAuth instead of blindly reusing the same token.
Next step: save selected LinkedIn accounts
Once the user has picked from the returned accounts, saving that choice is a separate operation covered on its own page. This reference mentions it only to mark the sequence: fetch the pending options with this GET request first, then submit the selection using identifiers taken from the accounts array. Skipping the fetch would leave your app guessing which personal profile and organization pages are actually available for that selectionToken.
| Parameter | Location | Required | Type | Constraints |
|---|---|---|---|---|
| token | Path | Yes | string | 1 <= length |
Exact captured input contract.
| Field | Type | Required | Notes |
|---|---|---|---|
| success | boolean | Yes | |
| platform | string | Yes | "linkedin" |
| expiresInSeconds | number | Yes | |
| accounts | array<object> | Yes | |
| accounts[].id | string | Yes | |
| accounts[].type | string | Yes | "person" | "organization" |
| accounts[].platformUserId | string | Yes | |
| accounts[].displayName | string | null | Yes | Nullable |
| accounts[].username | string | null | Yes | Nullable |
| accounts[].imageUrl | string | null | Yes | Nullable; string form is a uri |
Exact captured 200 response contract.
| Status | Content type | Field | Type | Required |
|---|---|---|---|---|
| 404 | application/json | error | string | Yes |
Only the captured 404 contract is documented; unspecified error conditions are not invented.
curl -X GET "{{API_BASE_URL}}/v1/connect/linkedin/selection/{token}"{
"success": true,
"platform": "linkedin",
"expiresInSeconds": 0,
"accounts": [
{
"id": "string",
"type": "person",
"platformUserId": "string",
"displayName": "string",
"username": "string",
"imageUrl": "http://example.com"
}
]
}{
"error": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| token#1 | token | string | __0 | Yes | kind: schemaLength; value: 1 <= length | |
| response#2 | response | object | __0 | |||
| response#2 | response.success | boolean | __1 | Yes | ||
| response#2 | response.platform | string | __2 | Yes | kind: schemaValueIn; value: "linkedin" | |
| response#2 | response.expiresInSeconds | number | __3 | Yes | ||
| response#2 | response.accounts | array<object> | __4 | Yes | ||
| response#2 | response.accounts[] | object | __5 | |||
| response#2 | response.accounts[].id | string | __6 | Yes | ||
| response#2 | response.accounts[].type | string | __7 | Yes | ||
| response#2 | response.accounts[].type[variant1] | string | __7_extends:__8 | kind: ; value: "person" | ||
| response#2 | response.accounts[].type[variant2] | string | __7_extends:__9 | kind: ; value: "organization" | ||
| response#2 | response.accounts[].platformUserId | string | __10 | Yes | ||
| response#2 | response.accounts[].displayName | string | null | __11 | Yes | ||
| response#2 | response.accounts[].displayName[variant1] | string | __11_type:string | |||
| response#2 | response.accounts[].displayName[variant2] | null | __11_type:null | |||
| response#2 | response.accounts[].username | string | null | __12 | Yes | ||
| response#2 | response.accounts[].username[variant1] | string | __12_type:string | |||
| response#2 | response.accounts[].username[variant2] | null | __12_type:null | |||
| response#2 | response.accounts[].imageUrl | string | null | __13 | Yes | kind: ; value: uri | |
| response#2 | response.accounts[].imageUrl[variant1] | string | __13_type:string | kind: ; value: uri | ||
| response#2 | response.accounts[].imageUrl[variant2] | null | __13_type:null | kind: ; value: uri | ||
| response#3 | response | object | __0 | |||
| response#3 | response.error | string | __1 | Yes |