Searching by date of birth
Labelled match strength on every record, and how dob, birthYear and dobPrecision fit together.
Livehttps://api.offendersearch.appSandboxhttps://sandbox.offendersearch.appSearching by date of birth
A date of birth is the strongest identity verifier. Add dob (YYYY-MM-DD) to your query and every returned record carries a matchState telling you exactly how it matched. A record with no date of birth published is never silently dropped: if there is nothing to confirm the date but the name matched, you still get the record, labelled as unverified. Only a true date-of-birth conflict is excluded.
matchState names which one verified this record. That lets you set your own threshold for auto-accept versus review, rather than inherit one.matchState — how each record matched
| matchState | Meaning |
|---|---|
| dob_match | The record has a full date of birth on file and it equals the DOB you queried — the strongest confirmation. |
| year_match | The record has NO full DOB (a year-only source, e.g. Massachusetts), but its birth year equals your DOB’s year. |
| age_match | The record’s age agrees with your query within ageTolerance (default ±1 year, for birthday drift): on a dob search, a record that publishes only an age; on an age search, any record whose date, year or age gives an age in range. |
| no_dob_age_year | The record has no DOB, year, or age to verify against — yet it is still returned because the name matched. Check matchBasis for name_match or alias_match. This is the “no DOB on file, but the name matches” case. |
| age_mismatch | The record’s published age contradicts your query, and you sent onAgeMismatch: "flag", so it is returned rather than dropped — always with unverified: true, so it never reads as a confirmation. |
| dob_near_match | You sent dobTolerance (1 or 2) and the record’s full date of birth is a likely typo of the one you sent: the same month and day with the year off by up to dobTolerance, or the day and month swapped. Returned rather than dropped, always with unverified: true; matchBasis says which (dob:near:year+1, dob:near:year-1, dob:near:dayMonthSwapped). |
| dob_mismatch | The record HAD a DOB, year, or age and it did NOT match your query, so it is filtered OUT of the results. You will not normally see this state — it is documented so you know a true conflict is excluded, never silently shown. |
| null | You did not send a dob or an age, so there was nothing to verify the record against and this field carries no information. It is null, not a string — do not treat it as a failed verification. |
matchState is null when you did not supply a dob or age — it is only meaningful on a date-of-birth or age search. A record whose date, year or age actively conflicts with your query is filtered out of records[], so a mismatch is excluded rather than shown as a false hit — unless you send onAgeMismatch: "flag", which returns an age contradiction labelled age_mismatch.
dobVerification — the same signal, backward-compatible
dobVerification carries the raw token for integrations written before matchState existed. New code should read matchState.
| dobVerification | Meaning |
|---|---|
| dob_match | The record’s full date of birth equals the DOB you supplied — the strongest identity confirmation. |
| year_match | The record is year-only (dobPrecision: year) and its year equals your DOB’s year. |
| age_match | The record’s age agrees with your query within ageTolerance (default ±1 year, for birthday drift). |
| unverified_no_dob_or_age | The record had no DOB, age, or year to check against — kept and flagged (unverified: true). matchState spells it no_dob_age_year. |
| age_mismatch(flagged) | The record’s age contradicts your query and you sent onAgeMismatch: "flag", so it is returned, flagged unverified: true. matchState spells it age_mismatch. |
| dob_near_match | You sent dobTolerance and the record’s birth date is a likely typo of yours — the year off by up to that many years, or day and month swapped. Returned flagged unverified: true; matchBasis carries dob:near:year+1, dob:near:year-2 or dob:near:dayMonthSwapped. |
| "" | You sent no dob or age, so there was nothing to verify. |
What comes back on the record: dob, birthYear, age
Jurisdictions differ in how much of a birth date they publish, so three fields carry the answer and which of them is populated is itself information. Read dobPrecision to know which case you are in.
| What the jurisdiction publishes | dob | birthYear | dobPrecision | Matches your dob query as |
|---|---|---|---|---|
| A full calendar date | "1961-09-25" | 1961 | "exact" | dob_match |
| A birth year only | null | 1961 | "year" | year_match — any date you query inside that year |
| An age only | null | null | "unknown" | age_match — a date consistent with the published age |
| Neither date, year nor age | null | null | "unknown" | no_dob_age_year — kept on the name, unverified: true |
dob is a full YYYY-MM-DD date or null — never a bare year, never a partial date, and never a day and month chosen to fill the field. You can hand it straight to a date parser without a shape check. Where a jurisdiction publishes only the year, that year is in birthYear as an integer, and the record still matches a full-date query. Read birthYear for any year logic — it is populated both from a published year and from the year of a published date, so your code never has to branch on which kind of record it is looking at. It is never inferred from an age: an age is not a date, and this field is served as fact rather than as an estimate.Age tolerance
Where a jurisdiction publishes an age and no date, a name + dob search compares your date against that published age, and ageTolerance (0–10, default 1) sets how much slack that comparison allows — a risk decision that belongs to you. onAgeMismatch decides what happens to a record that matches on name but whose published age contradicts your date: "drop" omits it, "flag" returns it labelled matchState: "age_mismatch" and always unverified, so you can judge it yourself.
{
"query": {
"firstName": "John",
"lastName": "Doe",
"dob": "1980-04-12",
"ageTolerance": 2,
"onAgeMismatch": "flag"
},
"match": "balanced"
}dobTolerance — birth-date typos
Where a registry publishes a full date of birth, a date that differs from yours is dropped, and a typo in your own records (1970 keyed for 1969, or 08/12 for 12/08) would hide a real registrant. dobTolerance (0–2, default 0) returns those records instead: the same month and day with the year off by up to that many years, or the day and month swapped. Each one is labelled matchState: "dob_near_match", always unverified, and matchBasis says how it differed — dob:near:year+1, dob:near:year-2 or dob:near:dayMonthSwapped. A different month and day is not a typo and is still dropped.
{
"query": {
"firstName": "John",
"lastName": "Doe",
"dob": "1980-04-12",
"dobTolerance": 1
}
}matchBasis — why each record is in the results
Alongside matchState, every record carries a matchBasis array explaining why it is in the result set. When there is no date of birth to verify, this is how you tell a name hit apart from a verified one:
| matchBasis value | Meaning |
|---|---|
| lastName:exact / firstName:exact | The field equals the name you sent. |
| lastName:prefix / firstName:prefix | The field starts with the name you sent — a partial-name hit. See Partial name search. |
| firstName:nickname | Matched through a nickname equivalence (bob → Robert). |
| lastName:fuzzy / firstName:fuzzy | Matched through a spelling variant or typo. |
| firstName:absent | The record publishes no first name, so your first name could not be disproved — kept and flagged rather than dropped. |
| alias:exact / alias:prefix | An alias matched, not the registered name. Read matchedName to see which alias. |
| name_match | The record matched on its primary name — the name you searched. |
| alias_match | The record matched on one of its aliases rather than its primary name. |
| unverified_no_dob_or_age | The record was kept without DOB/age verification because there was nothing on file to check against — paired with matchState = no_dob_age_year. |
| dob:near:year+1 / dob:near:year-2 / dob:near:dayMonthSwapped | Kept by dobTolerance: how the record’s birth date differs from the one you sent — year+1 means the registry’s year is one later than yours; dayMonthSwapped means day and month are reversed. Paired with matchState = dob_near_match. |
matchBasis also carries lastName, firstName, and dob tokens indicating which identity fields the record itself provides. So a name hit with no date of birth reads as matchState: "no_dob_age_year" with matchBasis: ["...", "name_match"] (or alias_match when the match was on an alias).
matchState: "no_dob_age_year" and a name_match/alias_match basis. Only a genuine conflict (dob_mismatch) is excluded from the results.{
"matchState": "no_dob_age_year",
"matchBasis": ["lastName", "firstName", "unverified_no_dob_or_age", "name_match"],
"unverified": true,
"name": { "first": "John", "last": "Doe", "full": "John Doe" },
"dob": null,
"dobPrecision": "unknown"
}Jurisdiction is a filter too. Name the jurisdiction(s) you want with jurisdictions (e.g. ["MA", "NY"]), or set query.state with locationScoped: true to run only the jurisdictions covering that state. Omit jurisdictions to search the full dataset.