Role Lookup

The Role Lookup endpoint (/api/v2/find/company/role/) finds the person currently holding a specific role at a company. Use it when you want to identify, for example, the CEO or Head of Engineering at a given organization.

What it does

Given a role title and company name, the endpoint returns the LinkedIn profile URL of the person who most closely matches that role at that company. It returns a single best match — not a ranked list.

GET /api/v2/find/company/role/
  ?role=ceo
  &company_name=microsoft

Required parameters: role, company_name

The result is a LinkedIn profile URL. If enrich_profile=enrich is set, the full profile is returned in the same response (costs 1 additional credit).

For ranked lists of role matches, use the Employee Search endpoint or Person Search endpoint instead.

How credits are charged

Cost: 3 credits per 200 OK response.

Credits are charged whenever the API returns HTTP 200, even if the result is null. The endpoint uses external search (SERP) under the hood to find the role match, and that lookup cost is incurred regardless of whether a person is found.

There is no opt-out parameter for null results on this endpoint.

Best practices

• Use specific role titles — Exact or close-to-exact titles (e.g., "Chief Technology Officer" or "CTO") produce better matches than vague descriptions.
• Use the company's common name — Pass the name as it appears publicly (e.g., "Microsoft" rather than "Microsoft Corporation").
• Avoid redundant calls — If a role is unlikely to turn over often (e.g., CEO of a large company), cache the result locally and refresh on a schedule rather than calling on every request.
• Use Person Search for multiple candidates — If you want to see several people matching a role, the Person Search endpoint is more appropriate and lets you filter by title, company, and location.

Coming in API v3

API v3 will not charge credits when the response is null or empty, for all lookup endpoints. If you are migrating to v3, this billing behavior will change automatically — you will only be charged when a result is actually returned.