# NPI Registry · Search

Find companies, people and contact details with NPI Registry · Search from Alexandria through one Spiral API key. Search the CMS NPPES NPI Registry for healthcare providers (individuals or organizations) by name, organization, taxonomy/specialty, city, state, postal code or country. It runs in the background and returns structured JSON. Pay as you go, with no subscription.

- Provider: Alexandria
- Category: Lead Gen
- Runs: In the background
- Returns: json
- Tool id: `alexandria` / `npiregistry-cms-hhs-gov/providers/search`
- Page: https://spiral.ai/tools/alexandria/npiregistry-cms-hhs-gov/providers/search

## Pricing

$0.00873 per call.

## Limits

- Longest queue wait: 1 hour
- Run deadline: 5 minutes
- Longest run, end to end: 225 minutes
- Largest inline input: 1 MB
- Largest input file: 2 GB
- Largest output: 5 GB

## Input

| Field | Kind | Allowed | Default | Description |
| --- | --- | --- | --- | --- |
| `city` | text |  | — | City of the mailing or practice address. Up to 100 ASCII characters (NPPES rejects accented letters; O'Brien, Smith-Jones and St. John are fine); one trailing `*` wildcard is allowed after at least two characters. |
| `skip` | number | 0 to 1200 | 0 | Records to skip; pass next_skip from the previous page. NPPES allows at most 1200. |
| `limit` | number | 1 to 200 | 10 | Records per page. |
| `state` | text |  | — | Two-letter US state/territory code. Needs another criterion. Pattern: ^[A-Za-z]{2}$. |
| `last_name` | text |  | — | Individual provider last name (NPI-1 only). Up to 100 ASCII characters (NPPES rejects accented letters; O'Brien, Smith-Jones and St. John are fine); one trailing `*` wildcard is allowed after at least two characters. |
| `first_name` | text |  | — | Individual provider first name (NPI-1 only). Up to 100 ASCII characters (NPPES rejects accented letters; O'Brien, Smith-Jones and St. John are fine); one trailing `*` wildcard is allowed after at least two characters. |
| `postal_code` | text |  | — | 5- or 9-digit ZIP, or a prefix followed by `*` (e.g. 941*). |
| `country_code` | text |  | — | Two-letter country code; US is the default in NPPES. Pattern: ^[A-Za-z]{2}$. |
| `address_purpose` | one of | location, mailing, primary, secondary | — | Which address the city/state/postal_code filters apply to. Default: any. |
| `enumeration_type` | one of | individual, organization | — | individual (NPI-1) or organization (NPI-2). Omit for both. |
| `organization_name` | text |  | — | Organization legal name or other name (NPI-2 only); also matches Doing Business As names. Up to 100 ASCII characters (NPPES rejects accented letters; O'Brien, Smith-Jones and St. John are fine); one trailing `*` wildcard is allowed after at least two characters. |
| `taxonomy_description` | text |  | — | Specialty / taxonomy description such as Cardiology, Dermatology, Family Medicine, Hospice Care, Community Based, or a taxonomy code like 208800000X. Up to 100 ASCII characters (NPPES rejects accented letters; O'Brien, Smith-Jones and St. John are fine); one trailing `*` wildcard is allowed after at least two characters. |
| `use_first_name_alias` | true or false |  | — | Also match common first-name aliases (Bob for Robert). Requires first_name. NPPES default is true. |

## Example

```bash
curl https://api.spiral.ai/v1/runs \
  -H "Authorization: Bearer $SPIRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "provider": "alexandria",
    "model": "npiregistry-cms-hhs-gov/providers/search",
    "input": {
      "city": "<city>"
    }
  }'
```

Try it in the Playground: https://spiral.ai/start?provider=alexandria&model=npiregistry-cms-hhs-gov%2Fproviders%2Fsearch

## Common questions

### NPI Registry · Search

**How much does NPI Registry · Search cost?**

$0.00873 per call. You pay as you go from one Spiral balance, with no subscription, and a failed run is not charged.

**How do I use NPI Registry · Search through an API?**

Send `POST /v1/runs` with `"provider": "alexandria"`, `"model": "npiregistry-cms-hhs-gov/providers/search"` and the input fields on this page, using one Spiral API key. It runs in the background: poll the run, or name a webhook to be told when it finishes.

**Do I need an account with Alexandria to use NPI Registry · Search?**

No. Spiral runs it on its own Alexandria account and charges your Spiral balance.

**Can my AI agent use NPI Registry · Search?**

Yes. Agents find and run it through Spiral's MCP server, CLI or agent skill, with the same API key.

