# NPI Registry Lookup (`npi.lookup`)

US healthcare provider lookup by 10-digit NPI or by name and state: entity type, status, specialty (taxonomy), license, practice address and phone.

Docs: https://primaryapi.com/docs/api-reference/npi/lookup

- Endpoint: `POST https://api.primaryapi.com/v1/run/npi.lookup`
- Category: Validation · Platform: `npi` · Kind: lookup · Status: live
- Price: 1 credit per call. Every call costs the same, including calls that were retried automatically.
- 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=npi.lookup`
- Execution: synchronous (answers 202 only if it outlives the wait window)

## Input

| Field | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| `npi` | string | no |  | pattern: ^\d{10}$ | 10-digit NPI, e.g. "1003000126"; the check digit is verified before any upstream call. |
| `firstName` | string | no |  | max 50 chars | First name, narrows a lastName search. |
| `lastName` | string | no |  | max 60 chars | Search individual providers by last name (when no NPI is given). |
| `organizationName` | string | no |  | max 100 chars | Search organizations by name, e.g. "Mayo Clinic" (when no NPI is given; wins over lastName). |
| `state` | string | no |  | pattern: ^[A-Za-z]{2}$ | Two-letter state of the practice location, narrows a name search, e.g. "MN". |

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 |
|---|---|---|
| `npi` | string | 10-digit NPI |
| `entityType` | enum | individual (NPI-1) or organization (NPI-2) |
| `name` | string \| null | Individual: first middle last; organization: legal business name |
| `credential` | string \| null | e.g. "M.D." (individuals) |
| `status` | enum \| null | Registry status; null when the source has none |
| `isActive` | boolean \| null |  |
| `primarySpecialty` | string \| null | Primary taxonomy description, e.g. "Hospitalist" |
| `taxonomyCode` | string \| null | Primary taxonomy code, e.g. "208M00000X" |
| `licenseNumber` | string \| null | License number of the primary taxonomy |
| `licenseState` | string \| null |  |
| `practiceAddress` | string \| null | Primary practice location, formatted |
| `practicePhone` | string \| null | Practice phone, NNN-NNN-NNNN |
| `mailingAddress` | string \| null |  |
| `enumerationDate` | string \| null | Date the NPI was issued, YYYY-MM-DD |
| `lastUpdated` | string \| null | Date the record was last updated, YYYY-MM-DD |
| `soleProprietor` | boolean \| null |  |
| `taxonomies` | object[] | Every taxonomy (specialty + license) on the record |
| `taxonomies[].code` | string \| null |  |
| `taxonomies[].description` | string \| null |  |
| `taxonomies[].licenseNumber` | string \| null |  |
| `taxonomies[].licenseState` | string \| null |  |
| `taxonomies[].primary` | boolean |  |
| `practiceLocations` | string[] | Additional practice locations, formatted |
| `otherNames` | string[] | Former, professional or doing-business-as names |
| `authorizedOfficialTitle` | string \| null | Organizations: title of the authorized official |
| `nameSearch` | string \| null | The name searched (null for an NPI lookup) |
| `matchCount` | integer | Records returned for the query (1 for an NPI lookup) |
| `matches` | object[] | Further name-search matches (up to 9) |
| `matches[].npi` | string |  |
| `matches[].name` | string \| null |  |
| `matches[].entityType` | enum |  |
| `matches[].primarySpecialty` | string \| null |  |
| `matches[].city` | string \| null |  |
| `matches[].state` | 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/npi.lookup" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"npi":"1003000126"}'
```

## 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": {
      "npi": "1003000126",
      "entityType": "individual",
      "name": "string",
      "credential": "string",
      "status": "active",
      "isActive": true,
      "primarySpecialty": "string",
      "taxonomyCode": "string",
      "licenseNumber": "string",
      "licenseState": "string",
      "practiceAddress": "string",
      "practicePhone": "string",
      "mailingAddress": "string",
      "enumerationDate": "string",
      "lastUpdated": "string",
      "soleProprietor": true,
      "taxonomies": [
        {
          "code": "string",
          "description": "string",
          "licenseNumber": "string",
          "licenseState": "string",
          "primary": true
        }
      ],
      "practiceLocations": [
        "string"
      ],
      "otherNames": [
        "string"
      ],
      "authorizedOfficialTitle": "string",
      "nameSearch": "string",
      "matchCount": 0,
      "matches": [
        {
          "npi": "1003000126",
          "name": "string",
          "entityType": "individual",
          "primarySpecialty": "string",
          "city": "string",
          "state": "string"
        }
      ]
    }
  },
  "provider": "PrimaryAPI",
  "credits": 1,
  "items": 1,
  "requestId": "req_01JBXK6Y2N9V8T4R3Q2P1M0A7Z"
}
```

## Pricing and reliability

- Usual price: 1 credit per 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=npi.lookup`

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

A name search returns the best match (active records first) flattened, plus up to 9 further matches; add state and firstName to narrow it. NPI numbers are checked (Luhn with the 80840 prefix) before any upstream call, so a typo is a free 400. Not found is free. Pair with an exclusion check for credentialing: an NPI is not proof of licensure or good standing.

## Legal

Source: the CMS National Plan and Provider Enumeration System NPI Registry, US government public data. Provider names, addresses and phone numbers are personal data in many jurisdictions: use them for provider verification, not for marketing lists. An NPI does not prove licensure or good standing.

