# LinkedIn Profile Search (`linkedin.search_profiles`)

Search LinkedIn people by keyword with job-title, location, company, school, seniority and other filters; each hit is a full profile.

Docs: https://primaryapi.com/docs/api-reference/linkedin/search_profiles

- Endpoint: `POST https://api.primaryapi.com/v1/run/linkedin.search_profiles`
- Category: Social · Platform: `linkedin` · Kind: search · Status: live
- Price: 5 credits per result, at least 130 credits a call. Every call costs the same, including calls that were retried automatically.
- Billing unit: per result returned, rounded up to whole credits per call (a call that returns nothing costs nothing)
- Reliability: routed to a healthy upstream and retried automatically when an attempt fails; live 30-day status: `GET https://api.primaryapi.com/v1/status/apis?sku=linkedin.search_profiles`
- Execution: synchronous (answers 202 only if it outlives the wait window)
- Restricted: yes. Requires an approved account that accepted the permissible-purpose terms (`403 restricted_api` otherwise)

## Input

| Field | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| `query` | string | yes |  | max 500 chars | Name or keywords (fuzzy search). |
| `jobTitle` | string | no |  | max 200 chars | Current job-title filter, e.g. "CTO". |
| `location` | string | no |  | max 200 chars | Location text, e.g. "United States". |
| `currentCompanies` | string[] | no |  | max 20 items; items max 200 chars | People who currently work at any of these companies, by name or LinkedIn company URL. |
| `pastCompanies` | string[] | no |  | max 20 items; items max 200 chars | People who previously worked at any of these companies. |
| `schools` | string[] | no |  | max 20 items; items max 200 chars | People who attended any of these schools. |
| `pastJobTitles` | string[] | no |  | max 20 items; items max 200 chars | A past job title the person held, e.g. ["Product Manager"]. |
| `firstNames` | string[] | no |  | max 20 items; items max 200 chars | First names to match. |
| `lastNames` | string[] | no |  | max 20 items; items max 200 chars | Last names to match. |
| `profileLanguages` | string[] | no |  | max 20 items; items max 200 chars | Primary profile language, e.g. ["en"]. |
| `companyHeadquarterLocations` | string[] | no |  | max 20 items; items max 200 chars | Location of the current company headquarters, by place name. |
| `excludeCurrentCompanies` | string[] | no |  | max 20 items; items max 200 chars | Exclude people currently at any of these companies. |
| `excludePastCompanies` | string[] | no |  | max 20 items; items max 200 chars | Exclude people who previously worked at any of these companies. |
| `excludeCurrentJobTitles` | string[] | no |  | max 20 items; items max 200 chars | Exclude these current job titles. |
| `excludePastJobTitles` | string[] | no |  | max 20 items; items max 200 chars | Exclude these past job titles. |
| `excludeSchools` | string[] | no |  | max 20 items; items max 200 chars | Exclude people who attended any of these schools. |
| `excludeLocations` | string[] | no |  | max 20 items; items max 200 chars | Exclude people in any of these locations. |
| `excludeCompanyHeadquarterLocations` | string[] | no |  | max 20 items; items max 200 chars | Exclude people whose current company is headquartered in these locations. |
| `seniorityLevelIds` | (string \| integer)[] | no |  | max 20 items | Seniority codes: 100 In Training, 110 Entry, 120 Senior, 130 Strategic, 200 Entry Manager, 210 Experienced Manager, 220 Director, 300 VP, 310 CXO, 320 Owner/Partner. |
| `excludeSeniorityLevelIds` | (string \| integer)[] | no |  | max 20 items | Exclude these seniority codes. |
| `functionIds` | (string \| integer)[] | no |  | max 20 items | Job-function codes (LinkedIn function ids, e.g. 8 = Engineering, 25 = Sales). |
| `excludeFunctionIds` | (string \| integer)[] | no |  | max 20 items | Exclude these job-function codes. |
| `companyHeadcount` | (string \| integer)[] | no |  | max 20 items | Current company size codes: A self-employed, B 1-10, C 11-50, D 51-200, E 201-500, F 501-1,000, G 1,001-5,000, H 5,001-10,000, I 10,001+. |
| `yearsAtCurrentCompanyIds` | (string \| integer)[] | no |  | max 20 items | Tenure at the current company: 1 under 1 year, 2 1-2 years, 3 3-5 years, 4 6-10 years, 5 over 10 years. |
| `yearsOfExperienceIds` | (string \| integer)[] | no |  | max 20 items | Total years of experience: 1 under 1 year, 2 1-2 years, 3 3-5 years, 4 6-10 years, 5 over 10 years. |
| `recentlyChangedJobs` | boolean | no |  |  | Only people who recently changed jobs. |
| `recentlyPostedOnLinkedIn` | boolean | no |  |  | Only people who recently posted on LinkedIn. |
| `limit` | integer | no | 10 | 1–25 | Maximum number of results to return (1-25, default 10). |
| `cursor` | string | no |  |  | Opaque pagination cursor: pass the previous response's nextCursor. |

Unknown fields are rejected with `400 invalid_input`. The routing controls `preferLatencyUnderMs` and `maxCredits` may be sent in the same JSON body.

## Output

When `output.found` is `true`, `output.data` has this shape:

| Field | Type | Description |
|---|---|---|
| `items` | object[] |  |
| `items[].id` | string \| null | LinkedIn member id |
| `items[].publicIdentifier` | string \| null | Vanity handle from the profile URL |
| `items[].url` | string \| null |  |
| `items[].name` | string \| null |  |
| `items[].firstName` | string \| null |  |
| `items[].lastName` | string \| null |  |
| `items[].headline` | string \| null |  |
| `items[].about` | string \| null |  |
| `items[].photo` | string \| null |  |
| `items[].location` | string \| null | Location text as shown on the profile |
| `items[].city` | string \| null |  |
| `items[].state` | string \| null |  |
| `items[].country` | string \| null |  |
| `items[].countryCode` | string \| null |  |
| `items[].connectionsCount` | integer \| null |  |
| `items[].followerCount` | integer \| null |  |
| `items[].openToWork` | boolean \| null |  |
| `items[].hiring` | boolean \| null |  |
| `items[].premium` | boolean \| null |  |
| `items[].influencer` | boolean \| null |  |
| `items[].creator` | boolean \| null |  |
| `items[].verified` | boolean \| null |  |
| `items[].currentPosition` | object \| null | Current employer, when shown |
| `items[].currentPosition.companyName` | string \| null |  |
| `items[].currentPosition.companyLinkedinUrl` | string \| null |  |
| `items[].experience` | object[] |  |
| `items[].experience[].title` | string \| null | Position title |
| `items[].experience[].companyName` | string \| null |  |
| `items[].experience[].companyLinkedinUrl` | string \| null |  |
| `items[].experience[].companyId` | string \| null |  |
| `items[].experience[].location` | string \| null |  |
| `items[].experience[].duration` | string \| null | Duration as shown, e.g. "1 yr 7 mos" |
| `items[].experience[].description` | string \| null |  |
| `items[].experience[].employmentType` | string \| null |  |
| `items[].experience[].workplaceType` | string \| null |  |
| `items[].experience[].startDate` | string \| null | Date as LinkedIn shows it, e.g. "Jan 2024" or "Present". |
| `items[].experience[].endDate` | string \| null | Date as LinkedIn shows it, e.g. "Jan 2024" or "Present". |
| `items[].experience[].skills` | string[] |  |
| `items[].education` | object[] |  |
| `items[].education[].school` | string \| null |  |
| `items[].education[].schoolUrl` | string \| null |  |
| `items[].education[].degree` | string \| null |  |
| `items[].education[].fieldOfStudy` | string \| null |  |
| `items[].education[].startDate` | string \| null | Date as LinkedIn shows it, e.g. "Jan 2024" or "Present". |
| `items[].education[].endDate` | string \| null | Date as LinkedIn shows it, e.g. "Jan 2024" or "Present". |
| `items[].skills` | string[] |  |
| `items[].topSkills` | string[] |  |
| `items[].certifications` | object[] |  |
| `items[].certifications[].title` | string \| null |  |
| `items[].certifications[].issuedBy` | string \| null |  |
| `items[].certifications[].issuedAt` | string \| null |  |
| `items[].languages` | object[] |  |
| `items[].languages[].name` | string \| null |  |
| `items[].languages[].proficiency` | string \| null |  |
| `items[].projects` | object[] |  |
| `items[].publications` | object[] |  |
| `items[].honorsAndAwards` | object[] |  |
| `items[].handle` | string \| null | Vanity handle (same as publicIdentifier) |
| `nextCursor` | string \| null |  |

When the thing you asked about does not exist (or a search matches nothing) the call still succeeds: `output.found` is `false`, `output.data` is `null` and `output.reason` says why (`not_found`, `private`, `no_results`, …). Misses are free unless the notes below say misses are billed.

Pagination: pass the previous response’s `nextCursor` as `cursor` to get the next page; `nextCursor: null` means there are no more results.

## Example request

```bash
curl -sS -X POST "https://api.primaryapi.com/v1/run/linkedin.search_profiles" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"head of data","jobTitle":"CTO","location":"United States","limit":10}'
```

## Example response

_Values are placeholders that follow the output schema; `credits` is what this call would cost at the usual price._

```json
{
  "output": {
    "found": true,
    "data": {
      "items": [
        {
          "id": "string",
          "publicIdentifier": "string",
          "url": "https://example.com",
          "name": "string",
          "firstName": "string",
          "lastName": "string",
          "headline": "string",
          "about": "string",
          "photo": "string",
          "location": "United States",
          "city": "string",
          "state": "string",
          "country": "string",
          "countryCode": "string",
          "connectionsCount": 0,
          "followerCount": 0,
          "openToWork": true,
          "hiring": true,
          "premium": true,
          "influencer": true,
          "creator": true,
          "verified": true,
          "currentPosition": {
            "companyName": "string",
            "companyLinkedinUrl": "https://example.com"
          },
          "experience": [
            {
              "title": "string",
              "companyName": "string",
              "companyLinkedinUrl": "https://example.com",
              "companyId": "string",
              "location": "United States",
              "duration": "string",
              "description": "string",
              "employmentType": "string",
              "workplaceType": "string",
              "startDate": "string",
              "endDate": "string",
              "skills": [
                "string"
              ]
            }
          ],
          "education": [
            {
              "school": "string",
              "schoolUrl": "https://example.com",
              "degree": "string",
              "fieldOfStudy": "string",
              "startDate": "string",
              "endDate": "string"
            }
          ],
          "skills": [
            "string"
          ],
          "topSkills": [
            "string"
          ],
          "certifications": [
            {
              "title": "string",
              "issuedBy": "string",
              "issuedAt": "string"
            }
          ],
          "languages": [
            {
              "name": "string",
              "proficiency": "string"
            }
          ],
          "projects": [
            {}
          ],
          "publications": [
            {}
          ],
          "honorsAndAwards": [
            {}
          ],
          "handle": "string"
        }
      ],
      "nextCursor": null
    }
  },
  "provider": "PrimaryAPI",
  "credits": 130,
  "items": 1,
  "requestId": "req_01JBXK6Y2N9V8T4R3Q2P1M0A7Z",
  "nextCursor": null
}
```

## Pricing and reliability

- Usual price: 5 credits per result, at least 130 credits a call
- Price ceiling: the usual price, even when a call is retried. A quote’s `maxCredits` is the most a given call can cost; the `maxCredits` routing control caps it per call
- Live 30-day status, success rate, uptime and latency: `GET https://api.primaryapi.com/v1/status/apis?sku=linkedin.search_profiles`

## Errors to handle

`invalid_input`, `unauthorized`, `insufficient_balance`, `key_limit_reached`, `trial_cap_reached`, `forbidden`, `not_found`, `idempotency_conflict`, `rate_limited`, `all_sources_failed`, `service_unavailable`, `timeout`, `restricted_api`. See https://primaryapi.com/docs/errors.

## Notes

One call reads one search page (up to 25 people) and serves the first page only. People search depends on what LinkedIn shows for the query: some results can be partial. The per-call fee is charged even when the search finds nobody.

## Legal

Restricted: needs an approved account and an accepted permissible purpose. Public LinkedIn data only. LinkedIn’s User Agreement restricts automated collection and LinkedIn enforces it; use the data for lawful purposes, keep copies only as long as you need them, and treat post and article text as the author’s content (analysis, not republication). Results contain personal data about identifiable people (GDPR, UK GDPR, CCPA): have a lawful basis, honour deletion requests, and never use it for spam or unsolicited bulk outreach. Bulk people search is the highest-risk LinkedIn use: keep to the purpose you declared.

