# LinkedIn Email Finder (`linkedin.email`)

Find the verified work email behind a LinkedIn profile URL, with the person’s name, headline and current company attached.

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

- Endpoint: `POST https://api.primaryapi.com/v1/run/linkedin.email`
- Category: Enrichment · Platform: `linkedin` · Kind: enrichment · Status: live
- Price: 13 credits per call; up to 20 credits if a call is retried elsewhere. A quote’s `maxCredits` is the most a given call can cost.
- Billing unit: per successful call
- 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.email`
- 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 |
|---|---|---|---|---|---|
| `profileUrl` | string | yes |  | max 2048 chars | LinkedIn profile URL (https://www.linkedin.com/in/<id>) or its public identifier, e.g. "williamhgates". |

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 |
|---|---|---|
| `email` | string \| null | Best address: the first deliverable one, else the first found; null if none |
| `emails` | object[] | Every address found, best first, with its verification result |
| `emails[].email` | string |  |
| `emails[].status` | string \| null | Verification status, e.g. "valid" or "risky" (catch-all domain) |
| `emails[].deliverable` | boolean \| null |  |
| `emails[].catchAllDomain` | boolean \| null |  |
| `emails[].qualityScore` | integer \| null |  |
| `firstName` | string \| null |  |
| `lastName` | string \| null |  |
| `headline` | string \| null |  |
| `linkedinUrl` | string \| null |  |
| `company` | string \| null | Current company name |

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.email" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profileUrl":"https://www.linkedin.com/in/williamhgates"}'
```

## 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": {
      "email": "string",
      "emails": [
        {
          "email": "string",
          "status": "string",
          "deliverable": true,
          "catchAllDomain": true,
          "qualityScore": 0
        }
      ],
      "firstName": "string",
      "lastName": "string",
      "headline": "string",
      "linkedinUrl": "https://example.com",
      "company": "string"
    }
  },
  "provider": "PrimaryAPI",
  "credits": 13,
  "items": 1,
  "requestId": "req_01JBXK6Y2N9V8T4R3Q2P1M0A7Z"
}
```

## Pricing and reliability

- Usual price: 13 credits per call
- Price ceiling: up to 20 credits 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.email`

## 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

Addresses are SMTP-checked; catch-all domains are marked risky. When the profile exists but no address is found, the call succeeds with email null and is billed, because the search itself was run. A profile that does not exist is a miss. Validate addresses before sending.

## 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. Email discovery is regulated personal-data processing (GDPR, CCPA, CAN-SPAM, PECR).

