LinkedIn organization lookup API
Use the LinkedIn organization lookup API when you have a LinkedIn company URL or vanity name and need the matching LinkedIn organization ID and LinkedIn organization URN before making a subsequent call. The endpoint resolves the supplied company value to an organization object containing id, name, vanityName, urn, and url.
Endpoint summary
Send a GET request to /v1/linkedin/organization-lookup to resolve a LinkedIn company URL or vanity name to a LinkedIn organization ID and LinkedIn organization URN. The documented request uses query parameters rather than a request body; company and accountId are query parameters. Use the organization-lookup path exactly as shown, with {{API_BASE_URL}} substituted for the origin in HTTP samples.
Authorization
Include the access key in the x-access-key header. The header name is x-access-key and the value is the token supplied by the caller. A request without this header does not match the documented authorization contract, so check the header name and value before debugging the company value.
Query Parameters
The company parameter is required and is a string with length of at least 1. It accepts a LinkedIn company URL, such as https://www.linkedin.com/company/linkedin, or a vanity name, such as linkedin. The accountId parameter is optional and is a string containing the integration ID of the LinkedIn account used to authorize the lookup. If accountId is omitted, the lookup uses the first connected LinkedIn account, so supply accountId explicitly when more than one connected account could make the result ambiguous.
200 Response
A successful lookup returns HTTP 200 with success set to true and a required organization object. The organization object contains id as a required string, name as a required string or null, vanityName as a required string, urn as a required string, and url as a required URI string. Treat name as nullable in client code: check for null before using it as display text, while id, vanityName, urn, and url can be treated as present strings on a 200 response.
Error Responses
The documented error responses for 400, 404, and 502 each return an object with a required error string. The source contract does not define additional error codes or field-level causes for these statuses, so client code should surface the error string and branch only on the HTTP status. As client-side operational suggestions rather than documented causes, you can inspect the request for a 400, verify the company URL or vanity name for a 404, and apply your own retry policy for a 502.
Worked Example
Start with the source example by passing https://www.linkedin.com/company/linkedin as company, or pass linkedin as the vanity name. On a 200 response, store organization.id as the LinkedIn organization ID, organization.vanityName for the vanity name, organization.urn as the LinkedIn organization URN, and organization.url as the organization URL. Keep name separate from the identifiers because it may be null. If the response is not 200, read the error string and use the status-specific checks described above before retrying with a different company value or accountId.
| Parameter | Required | Type | Description |
|---|---|---|---|
| company | Required | string | LinkedIn company URL or vanity name, for example https://www.linkedin.com/company/linkedin or linkedin. Length: 1 <= length. |
| accountId | Optional | string | Integration ID of the LinkedIn account used to authorize the lookup. If omitted, uses the first connected LinkedIn account. |
Exact source contract for GET /v1/linkedin/organization-lookup.
| Field | Required | Type | Description |
|---|---|---|---|
| success | Required | boolean | Must be true on a successful response. |
| organization | Required | object | Resolved LinkedIn organization object. |
| organization.id | Required | string | LinkedIn organization ID. |
| organization.name | Required | string | null | Organization name; may be null. |
| organization.vanityName | Required | string | Organization vanity name. |
| organization.urn | Required | string | LinkedIn organization URN. |
| organization.url | Required | string (uri) | Organization URL. |
Exact source contract for the 200 response body.
| Status | Response body | Client check |
|---|---|---|
| 400 | error: string | Check that company is present with length >= 1 and that x-access-key is included. |
| 404 | error: string | Verify the company URL or vanity name and surface the error string. |
| 502 | error: string | Surface the error string and apply your own retry policy. |
Source defines only an error string for these statuses; no specific error codes or causes are documented. Client checks are operational suggestions, not documented causes.
Frequently asked questions
What do I send to look up a LinkedIn organization?
Send GET /v1/linkedin/organization-lookup with the required company query parameter and the x-access-key header. The company value can be a LinkedIn company URL or a vanity name, and the 200 response returns the organization id, name, vanityName, urn, and url.
What happens if I omit accountId?
Omit accountId and the lookup uses the first connected LinkedIn account. Supply accountId when you need to authorize the lookup with a specific LinkedIn integration.
How should I handle a failed lookup?
Check that company is present and has length of at least 1, that the x-access-key header is included, and that the company value is a LinkedIn company URL or vanity name. The documented error body is an object with a required error string, and the source does not define more specific error codes for 400, 404, or 502, so branch only on the HTTP status and surface the error string.
curl -X GET "{{API_BASE_URL}}/v1/linkedin/organization-lookup?company=https%3A%2F%2Fwww.linkedin.com%2Fcompany%2Flinkedin" -H "x-access-key: <token>"{
"success": true,
"organization": {
"id": "string",
"name": "string",
"vanityName": "string",
"urn": "string",
"url": "http://example.com"
}
}{
"error": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| company#1 | company | string | __0 | Yes | LinkedIn company URL or vanity name, for example https://www.linkedin.com/company/linkedin or linkedin. | kind: schemaLength; value: 1 <= length |
| accountId#2 | accountId | string | __0 | No | Integration ID of the LinkedIn account used to authorize the lookup. If omitted, uses the first connected LinkedIn account. | |
| response#3 | response | object | __0 | |||
| response#3 | response.success | boolean | __1 | Yes | kind: schemaValueIn; value: true | |
| response#3 | response.organization | object | __2 | Yes | ||
| response#3 | response.organization.id | string | __3 | Yes | ||
| response#3 | response.organization.name | string | null | __4 | Yes | ||
| response#3 | response.organization.name[variant1] | string | __4_extends:__5 | |||
| response#3 | response.organization.name[variant2] | null | __4_extends:__6 | |||
| response#3 | response.organization.vanityName | string | __7 | Yes | ||
| response#3 | response.organization.urn | string | __8 | Yes | ||
| response#3 | response.organization.url | string | __9 | Yes | kind: ; value: uri | |
| response#4 | response | object | __0 | |||
| response#4 | response.error | string | __1 | Yes |