API keys: scopes, pace, quota and headers.

Making a key

Keys are created in the app. The secret is shown exactly once, at the moment it is minted, and is never recoverable afterwards — we hold a hash of it and the public prefix, which is what appears in the list of your keys. If it is lost, make another and revoke the old one.

A key can never hold a scope its creator does not hold themselves, so a key is a ceiling on what somebody could already do rather than a way around it. A key may be given an expiry date, or none. Revoking a key stops it working immediately and keeps the record of it, because the audit trail of what it did has to stay readable.

Send it as a bearer token:

Authorization: Bearer npi_live_<prefix>_<secret>

An invalid key always gets the same answer, whether it never existed, was revoked or has expired — a refusal that distinguishes those is a refusal that helps somebody guessing.

The scopes

Scopes are named for the thing they let a key do. A key asked to do something outside its scopes is refused by name, and keys cannot be widened after the fact: make a new one with the scopes you need.

Two limits, two reactions

Pace and volume are deliberately different answers, and telling them apart is most of writing a well-behaved client.

The headers

Every response carries what it is allowed to say, so a client never has to guess where it stands.

What is metered, and the one exception

A call the API answers adds one to the month's calls, and the records it returns are charged against the month's rows — the same allowance an export spends, because a row read through a key is the same row. Both are written in the same transaction as the read, before the answer leaves, and a refusal on either charges nothing at all.

A page costs one call and as many rows as it returned: fifty for a page of fifty, twelve for a page of twelve, none for a page that found nothing. One record costs one row. A lookup that finds nothing costs the call and no rows, because the lookup happened. Counts, place lists, specialty lists and published list pages name no record and cost no rows at all.

The page you ask for is checked against the rows you have left before anything is read, so a page bigger than your remaining allowance is a 409 rather than a short page. Ask for a page that fits and it is served whole.

The exception is the per-minute pace counter, which does count a call it refused. That is on purpose — a limiter that forgets the calls it turned away is a limiter a fast client can hammer for free. It affects only the minute you are in, never the monthly quota.

A reveal through the API spends a call and a reveal and no rows, for the reasons on the reveals page; charging the same disclosure twice under two names would make both numbers meaningless. The converse holds too — a work email arriving in an ordinary row is metered as a row and never touches your reveals. Starting an export costs a call and no rows, its rows are charged when the file is written, and downloading that file again costs neither. An unlimited allowance sends no header for itself rather than a made-up ceiling.

What the API will not do

Home address and cell phone are not available through the API at all. A call that asks for them is refused by name rather than returning an empty column, so a script can never quietly produce a file of blanks and call it coverage. They are revealed in the app, one provider at a time, under a contract — see home address and cell phone.

The full reference — every endpoint, the scope each needs, the filters, the shapes and the error codes — is public at the API reference. Version 1 changes only by adding.