Jurisdictions & codes

Scoping a search

The jurisdictions array controls which jurisdictions run. Omit it or send null to search the full dataset — the default and the common case. Naming codes narrows the search to exactly those jurisdictions, which reduces both latency and the number of sources reported in sourceStatus.

• jurisdictions: null → the full dataset (default).
• ["IL"] → Illinois only.
• ["IL", "IN"] → Illinois and Indiana only.

{
  "query": { "firstName": "Maria", "lastName": "Lopez" },
  "jurisdictions": ["TX", "NM"]
}

// counts.sourcesQueried === 2
// counts.sourcesSkippedByScope === 56

query.state filters a result; jurisdictions selects the search

These are two different controls and the distinction is worth holding. jurisdictions decides which jurisdictions are queried at all. query.state does not change that — every jurisdiction is queried and state narrows the answer. Set locationScoped: true alongside query.state when you explicitly want the narrower, cheaper fan-out; the response then reports counts.sourcesSkippedByScope and a NARROWED SEARCH warning so the scope decision is visible in the payload.

// Filter: query every jurisdiction, keep Texas-connected records.
{ "query": { "lastName": "Doe", "state": "TX" } }

// Scope: query only the jurisdictions covering Texas.
{ "query": { "lastName": "Doe", "state": "TX" }, "locationScoped": true }

// Scope, explicitly: query exactly these jurisdictions.
{ "query": { "lastName": "Doe" }, "jurisdictions": ["TX"] }

state accepts a 2-letter USPS code or the full state name — identical results. A value that cannot be resolved returns 422 rather than an empty result, so a typo is never mistaken for “no matches”. See Errors & status codes.

Jurisdiction codes

Jurisdiction codes are the standard USPS state & territory abbreviations, and they are the same vocabulary that query.state, registrationState, addressStates and sources[].jurisdiction use — so a value you read off a record can be sent straight back as a filter. Per-jurisdiction coverage detail is at coverage, and live health is on GET /v1/sources.