# LinkedIn Jobs with Details (`linkedin.jobs`)

Search LinkedIn job listings by title and location and get full records, up to 25 per call: description, salary when disclosed, applicants, seniority, employment type, company and posting date.

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

- Endpoint: `POST https://api.primaryapi.com/v1/run/linkedin.jobs`
- Category: Social · Platform: `linkedin` · Kind: search · Status: live
- Price: 0.45 credits per result, at least 2 credits a call; up to 1.25 credits per result if a call is retried elsewhere. A quote’s `maxCredits` is the most a given call can cost.
- 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.jobs`
- Execution: synchronous (answers 202 only if it outlives the wait window)

## Input

| Field | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| `query` | string | yes |  | max 500 chars | Job title or keywords, e.g. "data engineer". |
| `location` | string | no |  | max 200 chars | City, region or country text, e.g. "London". |
| `company` | string | no |  | max 200 chars | Only jobs at this company, by name, e.g. "Google". |
| `companyId` | string | no |  | pattern: ^\d{1,20}$ | Only jobs at this company, by LinkedIn numeric company id, e.g. "1441". |
| `easyApply` | boolean | no |  |  | When true, only jobs that offer LinkedIn Easy Apply. |
| `under10Applicants` | boolean | no |  |  | When true, only jobs with fewer than 10 applicants. |
| `postedLimit` | enum | no |  | one of: 24h, week, month | Only jobs posted within this window: past 24 hours, week or month. |
| `limit` | integer | no | 25 | 1–25 | Maximum number of results to return (1-25, default 25). |

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 | LinkedIn job id |
| `items[].url` | string \| null |  |
| `items[].title` | string \| null |  |
| `items[].descriptionText` | string \| null | Plain-text job description |
| `items[].descriptionHtml` | string \| null |  |
| `items[].location` | string \| null | Location as LinkedIn shows it |
| `items[].city` | string \| null |  |
| `items[].state` | string \| null |  |
| `items[].country` | string \| null |  |
| `items[].countryCode` | string \| null |  |
| `items[].employmentType` | string \| null | e.g. "Full-time", "Contract" |
| `items[].workplaceType` | string \| null | e.g. "Remote", "Hybrid", "On-site" |
| `items[].remote` | boolean \| null |  |
| `items[].experienceLevel` | string \| null | e.g. "Mid-Senior level" |
| `items[].salary` | object \| null | Pay range when the posting discloses one |
| `items[].salary.min` | number \| null |  |
| `items[].salary.max` | number \| null |  |
| `items[].salary.currency` | string \| null |  |
| `items[].salary.text` | string \| null |  |
| `items[].applicants` | integer \| null |  |
| `items[].views` | integer \| null |  |
| `items[].applyUrl` | string \| null |  |
| `items[].easyApplyUrl` | string \| null |  |
| `items[].easyApply` | boolean \| null |  |
| `items[].createdUtc` | integer \| null | Posting time, Unix seconds |
| `items[].expireUtc` | integer \| null | Expiry time, Unix seconds |
| `items[].jobState` | string \| null | e.g. "LISTED", "CLOSED" |
| `items[].industries` | string[] |  |
| `items[].benefits` | string[] |  |
| `items[].company` | object \| null |  |
| `items[].company.name` | string \| null |  |
| `items[].company.url` | string \| null |  |
| `items[].company.universalName` | string \| null |  |
| `items[].company.logoUrl` | string \| null |  |
| `items[].applicantTrackingSystem` | string \| null |  |
| `items[].hiringTeam` | object[] | People shown as hiring for the job, when listed |
| `items[].hiringTeam[].name` | string \| null |  |
| `items[].hiringTeam[].position` | string \| null |  |
| `items[].hiringTeam[].linkedinUrl` | string \| null |  |
| `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.

## Example request

```bash
curl -sS -X POST "https://api.primaryapi.com/v1/run/linkedin.jobs" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"data engineer","location":"London","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",
          "url": "https://example.com",
          "title": "string",
          "descriptionText": "string",
          "descriptionHtml": "string",
          "location": "London",
          "city": "string",
          "state": "string",
          "country": "string",
          "countryCode": "string",
          "employmentType": "string",
          "workplaceType": "string",
          "remote": true,
          "experienceLevel": "string",
          "salary": {
            "min": 0,
            "max": 0,
            "currency": "string",
            "text": "string"
          },
          "applicants": 0,
          "views": 0,
          "applyUrl": "https://example.com",
          "easyApplyUrl": "https://example.com",
          "easyApply": true,
          "createdUtc": 0,
          "expireUtc": 0,
          "jobState": "string",
          "industries": [
            "string"
          ],
          "benefits": [
            "string"
          ],
          "company": {
            "name": "string",
            "url": "https://example.com",
            "universalName": "string",
            "logoUrl": "https://example.com"
          },
          "applicantTrackingSystem": "string",
          "hiringTeam": [
            {
              "name": "string",
              "position": "string",
              "linkedinUrl": "https://example.com"
            }
          ]
        }
      ],
      "nextCursor": null
    }
  },
  "provider": "PrimaryAPI",
  "credits": 2,
  "items": 1,
  "requestId": "req_01JBXK6Y2N9V8T4R3Q2P1M0A7Z",
  "nextCursor": null
}
```

## Pricing and reliability

- Usual price: 0.45 credits per result, at least 2 credits a call
- Price ceiling: up to 1.25 credits per result if a call is retried elsewhere. 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.jobs`

## 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`. See https://primaryapi.com/docs/errors.

## Notes

One call returns the first results of the search, up to 25 jobs; you pay per job returned. For deeper paging use linkedin.jobs_thin and look up the jobs you need with linkedin.job. Searches with no matches are not charged.

## Legal

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.

