Result completeness & per-source status
An incomplete search is labelled, never silently empty. counts, sourceStatus and incompleteReason.
Livehttps://api.offendersearch.appSandboxhttps://sandbox.offendersearch.appPer-source status on every response
Every jurisdiction a search touches is reported individually in sourceStatus[], on every response, whether or not it contributed a record. That is what makes a result auditable: a search is never a single number you have to trust, and an incomplete search is always labelled as one.
| status | Meaning |
|---|---|
| ok | Queried successfully; matched holds the count from this source. |
| error | This source did not complete for this request; see note. |
| restricted | Reserved for a source whose terms restrict this use; no source returns it today. |
| no_coverage | The source could not cover this query; see note. |
{
"searchId": "srch_9f2a7c",
"status": "complete",
"counts": {
"records": 1,
"sourcesQueried": 2,
"sourcesComplete": 2,
"sourcesIncomplete": 0,
"sourcesSkippedByScope": 0
},
"warnings": [],
"sourceStatus": [
{ "source": "NJ", "status": "ok", "matched": 1, "fromCache": true,
"note": null, "incomplete": false, "incompleteReason": null,
"cappedOmitted": false },
{ "source": "PA", "status": "ok", "matched": 1, "fromCache": true,
"note": null, "incomplete": false, "incompleteReason": null,
"cappedOmitted": false }
],
"records": [ /* … */ ]
}{
"searchId": "srch_31c9de",
"status": "partial",
"counts": {
"records": 4,
"sourcesQueried": 58,
"sourcesComplete": 56,
"sourcesIncomplete": 2,
"sourcesSkippedByScope": 0
},
"warnings": [
"INCOMPLETE SEARCH: 2 of 58 registries could not be searched to completion — 1 returned more candidates than the search could examine (TX); 1 could not be read for this request and can be recovered by retrying (WA). The records below are a LOWER BOUND: …"
],
"sourceStatus": [
{ "source": "TX", "status": "ok", "matched": 0,
"incomplete": true, "incompleteReason": "truncated" },
{ "source": "WA", "status": "error", "matched": 0,
"incomplete": true, "incompleteReason": "unavailable",
"note": "source did not complete for this request" },
{ "source": "NJ", "status": "ok", "matched": 4,
"incomplete": false, "incompleteReason": null }
],
"records": [ /* … */ ]
}sourceStatus[].incomplete, not status. sourceStatus[].status describes whether the source responded; incomplete describes whether the search of that source finished. They are different questions and a source can be "ok" and incomplete: true at the same time.The SourceStatus object — per-registry status fields
One registry's outcome within a search. Each registry the search touched has one entry in sourceStatus[], so coverage is stated per response rather than assumed.
Returned or accepted by POST /v1/search, GET /v1/searches/{searchId}, POST /v1/search.
| Field | Type | Description |
|---|---|---|
| source | string | The registry code. Example "IL" |
| status | string one of "ok", "error", "restricted", "no_coverage", "complete", "partial" | ok: the registry was searched (its records can still be []). error: the registry failed for this request. restricted: reserved for a registry whose terms restrict this use; no registry returns it today. no_coverage: the registry does not cover this query. ok describes whether the registry answered, not whether the search finished — read incomplete for that. A row appended by a live re-check reads complete (finished) or partial (incomplete: true) instead. |
| matched | integer | Records this registry contributed before records were merged across registries. A lower bound when incomplete is true. |
| fromCache | boolean | true when the answer came from the continuously updated dataset; false when it was checked live. |
| note | string or null | Free-text detail for logs. Its wording changes; never branch on it. Use incomplete and incompleteReason. |
| incomplete | boolean | true when this registry was not searched to the end, so a matching person here may not be in records. Independent of status. This is the field that decides whether an empty result means nobody matched. |
| incompleteReason | string or null one of "deadline", "truncated", "excluded", "not_searched", "unavailable", "error" | Why this registry did not finish; set exactly when incomplete is true. deadline: it did not answer in time — retry, or raise deadlineMs if you lowered it. truncated: the query matched more candidates than one search examines — narrow it (add a surname); retrying does not help. excluded: a retired option on your request dropped this registry; send the request without it and its records come back. not_searched: nothing was available to search for this registry — treat the answer as a lower bound and re-run later. unavailable: the registry could not be read for this request — retry. error: the registry failed — retry. See Result completeness. |
| cappedOmitted | boolean | true when this registry matched people and none of them are in this response because the response was capped. Its matched count is exact; what is missing is the records. Always present; false on uncapped searches. |
| notFoundLive | integer | Present only on a registry whose live check completed in this search: how many of this answer's records from it the live answer did not include (each carries liveResult: "not_found_live"). 0 when every record was returned. See Live verification. |
Reading an empty result
An empty records array is not, on its own, evidence that a person is not registered. Two very different events produce the same empty list, and the response tells you which one you are holding.
| What happened | What the response says |
|---|---|
| Every jurisdiction completed and nobody matched. This is an answer. | status: "complete", counts.sourcesIncomplete: 0, counts.sourcesComplete === counts.sourcesQueried |
| One or more jurisdictions did not complete. This is a lower bound, not a closed answer. | status: "partial", counts.sourcesIncomplete > 0, and a warnings[] sentence naming the jurisdictions |
counts.sourcesIncomplete === 0 first. A pipeline that records “not found” on an incomplete search will record people who are registered as absent. Record it as not determined and re-query more narrowly.const { status, counts, records } = await search(query);
if (counts.sourcesIncomplete > 0) {
// Not an answer about anyone: a lower bound.
return { outcome: "not_determined", counts };
}
if (records.length === 0) {
// Every queried source completed and nobody matched.
return { outcome: "no_match", counts };
}
return { outcome: "matches", records, counts };How much of the search finished — counts
status is one word, and one word cannot tell you how partial a partial result is. A search that reached 57 of 58 jurisdictions and one that reached 7 of 58 both say "partial", and they are very different answers: the first you can act on, the second you should retry. The counts carry the positive number as well as the negative one.
The five counts — sourcesQueried, sourcesComplete, sourcesIncomplete, sourcesSkippedByScope and records, plus recordsReturned — are defined field by field in the POST /v1/search response fields.
status: "complete" means exactly counts.sourcesComplete === counts.sourcesQueried. If you log one number per search, log that ratio rather than the word.incompleteReason — every value, and what to do about each
A closed enum of six values, and it is total over the condition it describes: incomplete: true always carries exactly one of these, and incomplete: false always carries null. There is no third state, so an exhaustive switch on this field is safe to write. Adding a seventh value would be a breaking change and is treated as one.
| Value | What to do | What it means |
|---|---|---|
| deadline | Retry the same request | This source did not complete within the time bound set for this request, so it contributed no records. Transient — the identical request will usually complete. |
| truncated | Narrow the query — a retry returns the same answer | The query matches more candidate rows inside this one jurisdiction than a single search examines, and the examined set is not ranked, so a matching person can fall outside it. Deterministic: the identical request returns the identical answer. Add a first name, a date of birth or an age, or a city, and search again. |
| excluded | Remove the parameter from your request | A retired option on your request dropped this registry from the search. Send the request without it and the registry is searched again. |
| not_searched | Treat as not determined; retry later | This source did not contribute to this request, so a zero from it is not an answer about anyone. |
| unavailable | Retry with backoff | This source did not respond to this request and contributed no records. |
| error | Retry with backoff | This source returned no usable answer for this request and contributed no records. |
0 from a jurisdiction means nobody matched or not determined. Per-jurisdiction currency is a separate question with its own endpoint: GET /v1/sources reports every jurisdiction live.The defined per-source limits
Two kinds of per-jurisdiction limit — how many candidate rows one search examines, and how long it waits — are defined in the contract so that one over-broad query cannot degrade the service for everyone. Both are always reported, never silent.
| Limit | Value | What reaches it |
|---|---|---|
| truncated | At least 15,000 candidate rows per jurisdiction | Your query matches more rows inside that one jurisdiction than a single search examines. The examined set is not ranked, so a matching person can fall outside it. Reported, never silent. |
| truncated | 2,000 typo candidates per jurisdiction | match: "broad" only. Broad evaluates a second, speculative set of candidates for spelling variants of your surname; that arm carries its own, much smaller budget so it can never spend the candidate budget above. |
| deadline | 15 seconds or more per jurisdiction, inside the search’s overall time budget | That jurisdiction did not complete within the bound and contributed zero records. Retrying usually completes it; if you lowered deadlineMs, raise it. |
dob or age is never what gets displaced. When your query constrains the birth year, the records whose birth year matches are examined first, against the full candidate limit; records where the jurisdiction publishes no birth date are examined within a separate budget of their own, and a shortfall there is reported as truncated like any other. Those records are still returned when the name matches, flagged dobVerification: "unverified_no_dob_or_age", because a jurisdiction that publishes no birth date cannot rule a person out.perPage slices an answer you can walk in full — counts.records is the true total, it does not change as you page, and page = 1 … totalPages returns every record exactly once. A candidate limit is the opposite: there is no “next 15,000” to ask for. That is why it is reported and paging is not. See Pagination.Which query shapes reach a limit
The limit counts every row in a jurisdiction your query could touch, not the rows that finally matched. In order of safety:
| Query shape | Behaviour |
|---|---|
lastName + city or zipcode | Safest. A city or ZIP narrows the rows examined inside each jurisdiction, not only the answer. Use this shape for any automated reconciliation job. |
lastName alone | Fine for most surnames. Reaches the limit on short or very common surname tokens — Lee, Ford, Hill, Wood, Ward, Ray, West, James, Allen, Thomas — because alias and address matching widen the reach of a surname. |
firstName with no lastName | Declined with 422. A first name on its own has nothing to narrow on, so it cannot be answered completely. Pair it with a surname, or with a date of birth or age. |
city, zipcode, dob or age with no name | Reaches the limit in large jurisdictions — a single birth year still matches tens of thousands of people, so a date is not a substitute for a name. With a name, the date is never what is displaced. |
state scopes the answer, and with locationScoped: true it reduces the jurisdictions queried — but it does not shrink an individual jurisdiction’s candidate set, because state is applied when records are matched, not when they are selected. The reliable narrowing lever is a surname.