Sex Offender Search API · v1.0.0

The Record object

One normalized 37-key record across every jurisdiction, and how to read its empty values.

Livehttps://api.offendersearch.appSandboxhttps://sandbox.offendersearch.app

One schema across 58 jurisdictions

Every match in a search response is a normalized Record — 37 top-level keys, with nested name, addresses[], offense and offenses[], the 36-field extensive stateData block, and per-source provenance. It is a strict superset of the legacy record shape plus scoring, verification, and provenance fields. The same schema is returned by /v1/search and by /v1/records/{id}, so one type definition covers the whole API.

Which jurisdictions is this person on? — sources[]

A person can appear on more than one registry: registered in one state, working in another, and listed federally as well. They come back as one record, not three — and sources[] names every jurisdiction that record was built from, one entry per jurisdiction, de-duplicated.

KeyWhat it holds
jurisdictionThe jurisdiction’s code (IL, CNMI, TRIBAL…) — the same vocabulary jurisdictions accepts, so you can send it straight back.
registryNameThe registry’s own name, in full, as that jurisdiction publishes it. This is the name to show a user or print in a report — the specimen values in the payloads below are placeholders, not the strings any particular registry returns.
recordUrlThat jurisdiction’s own link to this registrant, so anyone can verify the entry at the source. "" where the jurisdiction publishes no addressable page per registrant.
recordedAt / lastCheckedAtWhen this jurisdiction’s copy of the record was first recorded, and when it was last confirmed.
sourceUpdatedAtThe date the jurisdiction itself states it last changed the record. null where a jurisdiction publishes no such date.

source (singular) is whichever entry supplied the top-level values; it always appears in sources[] too. Which of the three identifiers on a record to store is the subject of the next section.

Record identity

A record carries three identifiers, and each answers a different question. Read them as a set and store the one that matches the question you will ask later.

FieldWhat it identifies
personRefThe person behind a listing, within one registry — prs_ and 20 hex characters. It stays the same when a registry republishes the listing under a new number, so it is the value to store when you want to recognise the same person next time: a diff between two runs, a roster re-screen, a monitor. Every entry in sources[] carries its own personRef; the top-level one belongs to source.
recordIdThis merged result, for this query — rec_ and 20 hex characters. It is what GET /v1/records/{recordId} takes, and it is the handle to cite when you mean a specific result: a dispute, a report, a line in an audit file. It describes the merge that produced the record, so the same person can carry a different recordId on a state-scoped search and on a search of every US registry. Keep it for citing; do not key a person on it.
sources[].recordUrlA link for a person to follow — the registry’s own page, so a reviewer can verify the entry at the source. On some registries it is a registry-wide page rather than the registrant’s own, and it is "" where the registry publishes no page per registrant. It is not a key: do not de-duplicate or diff on it.
Store personRef with its jurisdiction to recognise the same person next time. Keep recordId to cite a specific result, and show recordUrl to whoever needs to check the registry’s page. Some registries re-issue the number a listing is published under; a search never returns the same registrant twice from one registry, the superseded number still resolves on GET /v1/records/{recordId}, and personRef does not change.

personRef is also what a clearance names: tell us once that a returned person is not the subject you are screening, and every later search for that subject honours it, at no extra charge. See Clearances.

Reading empty values

No key is ever omitted. Every top-level key is present on every record, on every endpoint, in every mode — so you test the value, never for key existence. There are three empty values and they mean different things:

ValueMeaning
""No value is held for this field on this record. That is a property of the jurisdiction — either it publishes no such field, or it publishes one and this registrant has none recorded.
nullNot known or not applicable; the precise meaning is per-field. On dob it means no full date of birth is published. On matchState it means you did not filter by date of birth or age. On flags.absconder / flags.predator it means the jurisdiction does not publish it — which is not false.
[]No items of this kind are held (no aliases, no addresses) — same reading as "", plus a third case on the array fields: see below.

Read "" as “no value on file for this field”, never as a statement about the person. Jurisdictions differ in which fields they publish at all: some print scars, marks and tattoos on every profile, and others publish no such field anywhere. So marks: "" means either that the jurisdiction publishes no such field, or that it publishes one and this registrant has none recorded — both are properties of the jurisdiction, and neither is evidence about the person. The same reading applies to aliases and to the physical description.

Maine and the District of Columbia are worth calling out, because it is easy to read them wrong. Neither publishes a race, and there is no ethnicity to fall back to, so race: "" on a Maine or DC record is final. Neither publishes a sex on its own site either; where a Maine or DC record carries one it reads "M"/"F" rather than "Male". Maine goes further and publishes no physical description at all: state law releases height, weight, eye colour and identifying marks only against a written request naming the requester, so those stay empty permanently. A field is never filled by inference — an empty value is an empty value, not a guess.

The array fields carry a third case: the jurisdiction does not publish that category for anybody. stateData.vehicles, stateData.professionalLicenses and the non-residence entries of addresses[] return [] when the registrant genuinely has none and when that jurisdiction never publishes the category at all. Read [] as “none known”, never as “none exists”. Vehicles are published by only some jurisdictions, so an [] from one that does not publish them says nothing about the person. The sharpest illustration: Utah and Wyoming run identical registry software, and Wyoming’s build publishes work addresses while Utah’s omits the category entirely — so a Utah record will never carry an employment address.

Nothing is held back by default. stateData is populated on every record, like offenses and images, so an empty value is a fact about the registrant. The one way to get a null that is not a fact is to ask for a lighter payload with exclude: ["stateData"] — the response then lists it in omittedFields, so you never have to guess which case you are in.

Types and formats to key your parser on

Three details worth stating plainly: age is a string, not a number; addresses[].type is an open vocabulary — beyond residence, employment and school you will also see last_known (Minnesota) and other, so always have a default branch; and every date field is ISO-8601.

Date format, as of the 2026-08-04 contract revision. The four offense date fields and the five stateData ones are ISO-8601. Two things to read before you write the parser. A partial date stays partial — a jurisdiction that publishes only a month or a year gives you "1998-11" or "1998", because inventing a day would make a fabricated date indistinguishable from a real one; the companion datePrecision object names the precision for every date key. And nothing is discarded — where a jurisdiction publishes something that is not a date at all, the field is "" and its literal text is kept in datesAsPublished.

dob shape, as of the 2026-08-06 contract revision. dob is guaranteed to be a full YYYY-MM-DD date or null — you can parse it without a length check. Where a jurisdiction publishes only a birth year, dob is null and the year is in the integer field birthYear. If you have persisted -01-01 birthdays saved from this API, re-fetch those records: the ones whose dobPrecision is "year" now return dob: null with the year in birthYear, and the ones whose dobPrecision is "exact" are real 1 January birthdays and are unchanged. Matching is unaffected: a year-only record still matches any date you query inside that year. See Searching by date of birth.

There is no date filter on the offense or stateData dates — dob is the one date you can narrow a query on, alongside the createdAt* / updatedAt* provenance ranges. Read the others off the record.

Field reference — every field on the sex offender Record object

One registrant, normalized to the same shape across every US registry. Every key is present on every record; an empty value is "", [] or null as stated per field, never a missing key.

Returned or accepted by POST /v1/search, GET /v1/searches/{searchId}, GET /v1/searches/{searchId}/results, POST /v1/search, POST /v1/batch, GET /v1/records/{recordId}, GET /v1/map/records/{markerId}.

FieldTypeDescription
recordId
stringThe handle for this result: rec_ and 20 hex characters. Use it with GET /v1/records/{recordId}, and cite it when you mean a specific result (a dispute, a report). It identifies this merged result, so it changes when the query scope changes which registries merge into the person; do not key a person on it. Store personRef with its jurisdiction for that. A registry identifier that a registry has since replaced still resolves on GET /v1/records/{recordId} to the person's current record.
Example "rec_ab12cd34ef56gh78ij90"
personRef
stringThe person behind this listing within the registry named in source: prs_ and 20 hex characters. It stays the same when that registry republishes the listing under a new number, so it is the value to store to recognise the same person next time. Each sources[] entry carries its own personRef.
Example "prs_3c9e1f0a7b2d4e6f8a1b"
uuid
stringThe registry's own id for the person, verbatim; "" when the registry publishes none. Unique only together with source.jurisdiction.
Example "IL:X24A0926"
recordType
default "sex_offender"
string
one of "sex_offender"
Always sex_offender on this endpoint.
matchConfidence
number or nullA 0–1 score of how much identity evidence supports the match. Widened name matches are capped (a nickname at 0.75; an initial, prefix, typo or middle-name match at 0.60), so a widened match never reads as certain. Branch on matchState for date-of-birth confirmation. null when unscored.
matchBasis
array of stringWhy the record is in the result. Tokens shaped field:strategy (lastName:exact, firstName:nickname, alias:prefix) are the match reasons. Bare lastName, firstName and dob say only that the record has that field. matchDetail carries the same facts already separated.
matchDetail
objectThe same information as matchBasis, split into its parts.
matchDetail.strategies
objectHow each name field matched, as {field: strategy}. Keys are lastName, firstName and, when an alias matched, alias.
Example {"lastName":"exact","firstName":"nickname"}
matchDetail.fieldsPresent
array of stringIdentity fields the record carries (lastName, firstName, dob).
Example ["lastName","firstName","dob"]
matchDetail.signals
array of string
one of "matchedLegalName", "matchedAlias", "matchedMiddleName", "unverifiable", "linkedByRegistryId"
Facts about the match as a whole: matchedLegalName, matchedAlias, matchedMiddleName (your given name is the person's middle name), unverifiable (no birth data to check). linkedByRegistryId: the record was pulled in through a registry id that links it to a matched record rather than by its own name.
matchDetail.matchedNameType
string or null
one of "legal", "alias"
legal or alias; null when no name was queried.
matchDetail.verification
string or nullThe dobVerification token; null when no dob or age was queried.
matchDetail.other
array of stringPresent only when the record carries a match token outside the vocabularies above, so no token is dropped.
matchedName
object or nullWhich name matched your query and whether it was the registered name or an alias. null when the query carried no name.
matchedName.value
stringThe name string that matched.
matchedName.type
string
one of "legal", "alias"
legal for the registered name, alias for one of the record's aliases.
name
NameThe registered name. See the Name object.
aliases
array of stringOther names the registry publishes for the person, verbatim. Shapes vary (SURNAME, GIVEN and Given Surname both occur), so do not parse positionally. [] when the registry publishes none for the person.
nicknames
array of stringNickname equivalents of name.first from our fixed given-name table (Robert gives Bob, Bobby, Rob…). Computed by OffenderSearch for name recall; not registry data. [] when the name has none.
Example ["john","johnny","jack"]
dob
string (date) or nullDate of birth as a full YYYY-MM-DD date, or null. Never a year alone and never a partial date. null when the registry publishes only a year (in birthYear) or only an age (in age); dobPrecision says which.
birthYear
integer or nullYear of birth as an integer whenever the registry published a full date or a year. Never derived from an age. null when neither was published.
Example 1976
dobPrecision
string
one of "exact", "year", "year_month", "unknown"
How much of the birth date the registry published. exact: a full date, in dob. year: a year only, in birthYear, and dob is null. unknown: neither; read age. year_month is reserved and not currently emitted.
age
stringAge in years as a string ("58"), as published. "" when the registry publishes no age.
sex
stringSex as the registry publishes it (Male, M). Not normalized across registries. "" when not published.
race
stringRace as the registry publishes it. Not normalized. Where a registry publishes one column for race and ethnicity, Hispanic values are in ethnicity and the rest in race, so read the two together. "" when not published.
ethnicity
stringEthnicity as the registry publishes it (Hispanic, Non-Hispanic). Not normalized. "" when not published.
height
stringHeight as published, with the registry's own format (5'10'', 510). "" when not published.
weight
stringWeight as published (165lbs). "" when not published.
eyeColor
stringEye color as published. "" when not published.
hairColor
stringHair color as published. "" when not published.
marks
stringScars, marks and tattoos as the registry records them, free text. "" when the registry publishes none for the person.
Example "Tattooed Arm, left upper; Scar on Chest; Pierced ear, left"
addresses
array of AddressEvery address the registry publishes for the person, each typed (residence, employment, school…). [] when none is published. See the Address object.
registrationState
stringThe state or territory whose registry holds the person — not where they live. In the same vocabulary query.state accepts. "" when the holding registry is not a state registry (a tribal registry, for example); source.jurisdiction then carries its code.
Example "FL"
addressStates
array of stringEvery distinct state in addresses[], in first-seen order. A person can have addresses in several states. [] when no published address carries a state.
Example ["FL","GA"]
offense
OffenseThe primary offense; the same object as offenses[0]. Always an object, never null. See the Offense object.
offenses
array of OffenseEvery published offense, the primary one first. Returned on every record.
stateData
StateData or nullExtended per-state detail, populated on every record by default. null only when the request sent exclude: ["stateData"] (then listed in omittedFields) or when the registry publishes none of it. See the StateData object.
flags
objectRegistry designations. Each is true or false when the registry publishes it and null when it does not — null is not false.
flags.absconder
boolean or nulltrue when the registry reports the person as an absconder; false when it reports they are not; null when it does not publish this.
flags.predator
boolean or nulltrue when the registry designates the person a predator; false when it reports they are not; null when it does not publish this.
housingStatus
string or null
one of "homeless", "incarcerated", "housed"
Whether the registrant is housed, homeless or incarcerated, normalized from however the registry states it. null when the registry states none of these.
images
array of objectPhotos the registry publishes. [] when the registry publishes none. Returned on every record.
images[].url
string (uri)The photo URL. A photo we host (https://photos.offendersearch.app/v1/media/…) is signed: it loads in a plain <img> tag with no API key, for at least 7 days and any number of loads. Use it exactly as returned; after it expires, search again for a fresh link or fetch the bare URL with your X-API-Key.
source
SourceRef or nullThe registry that supplied this record's top-level values. Always also present in sources[]. See the SourceRef object.
sources
array of SourceRefEvery registry that holds this person, one entry each, each with its own link to the registrant. More than one entry is cross-registry corroboration. sources[].recordUrl with its jurisdiction is the durable key to store for a person.
matchState
string or null
one of "dob_match", "year_match", "age_match", "no_dob_age_year", "age_mismatch", "dob_near_match", "dob_mismatch"
How this record was checked against the dob or age you sent, strongest first. dob_match: the registry's full date equals yours. year_match: the registry publishes only a year and it equals your date's year. age_match: the registry publishes only an age and it agrees with your date. no_dob_age_year: the registry publishes none of these, so nothing could be checked; the record matched on name and unverified is true. age_mismatch: the published age contradicts your date; returned only with onAgeMismatch: "flag". dob_near_match: you sent dobTolerance and the registry's full date is a likely typo of yours (year off, or day and month swapped); returned unverified. dob_mismatch: excluded from results, documented for completeness. null when the query carried no dob or age. See Searching by date of birth.
dobVerification
string
one of "", "dob_match", "year_match", "age_match", "unverified_no_dob_or_age", "dob_mismatch(filtered)", "age_mismatch(filtered)", "age_mismatch(flagged)", "dob_near_match"
The engine's raw DOB/age verification token. Read matchState instead — it is the clean vocabulary (dob_match, year_match, age_match, no_dob_age_year, age_mismatch, dob_mismatch, or null when nothing was scored). The (filtered) tokens surface only where the contract exposes rejected candidates; "" = no DOB or age was sent.
unverified
booleantrue when the record publishes no date of birth, birth year or age to check your query against. It is returned on the name and flagged.
liveResult
string
one of "confirmed_live", "not_found_live", "not_checked"
Present only on a search that ran live checks. confirmed_live: the live answer included this record. not_found_live: its registry was checked live in this search and the check completed, but the answer did not include this record — it is returned from our records, and warnings[] carries a NOT FOUND IN LIVE CHECK: sentence. not_checked: its registry was not checked live in this search, or its check could not complete. See Live verification.
clearance
RecordClearanceThe clearance that names this person, present only when the request carried subjectId and this record was kept despite — or because of — a verdict: annotate mode, a this_person verdict, or a cleared person who has re-surfaced (staleReason set). Absent on every other record; a search without subjectId never carries it.

Sex offender Record JSON example

Example — a real response, identity replaced with placeholders
Record
{
  "recordId": "rec_717a89b01deda9457ced",
  "personRef": "prs_3c9e1f0a7b2d4e6f8a1b",
  "uuid": "0000000",
  "recordType": "sex_offender",
  "matchConfidence": 1.0,
  "matchBasis": ["lastName", "firstName", "dob", "lastName:exact", "name_match"],
  "matchDetail": {
    "strategies": { "lastName": "exact" },
    "fieldsPresent": ["lastName", "firstName", "dob"],
    "signals": ["matchedLegalName"],
    "matchedNameType": "legal",
    "verification": null
  },
  "matchedName": { "value": "EXAMPLE PLACEHOLDER SURNAME", "type": "legal" },
  "name": {
    "first": "EXAMPLE", "middle": "PLACEHOLDER", "last": "SURNAME",
    "suffix": "", "full": "EXAMPLE PLACEHOLDER SURNAME"
  },
  "aliases": [],
  "nicknames": [],
  "dob": "1968-02-09",
  "birthYear": 1968,
  "dobPrecision": "exact",

What to notice: ethnicity, registrationDate and caseNumber are "" — Ohio does not publish them. So are the conviction-locale fields: Ohio publishes no County of Conviction field, and convictionCounty is the COURT’s county, never the residence county in addresses (which is Butler here — do not read one as the other). federal is null, meaning Ohio publishes no federal-vs-state column at all; only Oklahoma does, and there you would see true or false. flags.absconder is null (Ohio does not publish it) while flags.predator is true (it affirmatively does). stateData is null only because this call omitted include; images is empty because this Ohio record has no photo — images and offenses are never withheld. matchState is null because the query supplied no dob or age — the record has a date of birth, which is a different thing. And convictionDate is "1988-10-11": Ohio publishes "10/11/1988", which you can still read in datesAsPublished — the value is normalised without discarding what the jurisdiction published.

Two things to key your integration on, from this one record. birthYear is 1968 even though the year was never published on its own — it is the year of the full date, so year logic reads one field whatever the jurisdiction published. And recordId is not the identifier to key a person on. It is derived from the merge that produced this person for this query, so the same man returned by a state-scoped search and by a search of every US registry can carry two different recordId values — a diff keyed on it reports people as missing who were returned both times. Store personRef with its jurisdiction: it names the person behind the Ohio listing and stays the same if Ohio republishes that listing under a new number. Keep recordId for citing this result. See Record identity.

The Name object

A person's name as the registry publishes it, split into parts. Each part is "" when the registry does not publish it.

Returned or accepted by POST /v1/search, GET /v1/searches/{searchId}, GET /v1/searches/{searchId}/results, POST /v1/search, POST /v1/batch, GET /v1/records/{recordId}, GET /v1/map/records/{markerId}.

FieldTypeDescription
first
stringGiven name.
middle
stringMiddle name or names.
last
stringSurname.
suffix
stringSuffix (JR, III).
full
stringThe parts joined in order: first, middle, last, suffix.

The Address object — registrant address fields

One published address. A record carries every address the registry publishes, each typed.

Returned or accepted by POST /v1/search, GET /v1/searches/{searchId}, GET /v1/searches/{searchId}/results, POST /v1/search, POST /v1/batch, GET /v1/records/{recordId}, GET /v1/map/records/{markerId}.

FieldTypeDescription
type
default "residence"
stringThe kind of address: residence, employment, school, last_known or other. Treat it as an open set and handle a value you do not recognise.
Example "residence"
line1
stringStreet line as published. Some registries publish a block rather than a house number, and an employment or school line can begin with the employer or school name.
city
stringCity.
county
stringCounty as published.
state
stringTwo-letter state code.
zipcode
stringZIP code as published.
lat
number or nullLatitude, when the address has a published or computed location; null otherwise. null does not mean the address is missing.
lng
number or nullLongitude, when the address has a published or computed location; null otherwise.

The Offense object — offense and conviction fields

One offense as the registry publishes it. Every field is present; a field the registry does not publish is "" (or null for federal). Dates are ISO-8601, at the precision the registry published.

Returned or accepted by POST /v1/search, GET /v1/searches/{searchId}, GET /v1/searches/{searchId}/results, POST /v1/search, POST /v1/batch, GET /v1/records/{recordId}, GET /v1/map/records/{markerId}.

FieldTypeDescription
crime
stringThe offense description as published.
statute
stringThe statute cited, as published.
riskLevel
stringThe registry's risk classification, verbatim (Tier 3, Level 2, Sexually Violent Predator). Each state uses its own scale, so values are not comparable across states. "" when the registry publishes none. It does not carry registration status; that is stateData.status.
tier
stringThe registry's tier, where it publishes one separately from riskLevel, verbatim. "" when not published.
convictionDate
stringConviction date, ISO-8601: YYYY-MM-DD, or YYYY-MM / YYYY when the registry publishes only a month or a year. "" when not published. datePrecision.convictionDate states which.
offenseDate
stringWhen the offense was committed, same format as convictionDate. A different fact from the conviction date.
registrationDate
stringRegistration date, same format as convictionDate.
releaseDate
stringRelease date, same format as convictionDate.
datePrecision
objectFor each of the four date fields, how much of it the registry published: exact, year_month, year, none, or unparseable. Always all four keys.
datesAsPublished
objectThe registry's original text for any date that was reformatted or could not be read, keyed by field ({"convictionDate": "10/11/1988"}). {} when every date was published as emitted.
caseNumber
stringCourt case number as published.
victimAge
stringVictim age as published.
victimSex
stringVictim sex as published.
jurisdiction
stringThe two-letter state where the conviction was entered.
convictionCounty
stringCounty where the conviction was entered. Not the registrant's county of residence.
convictionCity
stringCity where the conviction was entered.
convictionCount
stringHow many convictions this offense entry represents, as published. "" when not published; it does not mean one.
federal
boolean or nulltrue when the registry marks the conviction as federal, false when it marks it as state, null when it does not publish this.

The SourceRef object — source registry and record link fields

Where a record came from: the registry, its own link to the registrant, and three timestamps. source is the registry that supplied the record's top-level values; sources[] lists every registry that holds the person.

Returned or accepted by POST /v1/search, GET /v1/searches/{searchId}, GET /v1/searches/{searchId}/results, POST /v1/search, POST /v1/batch, GET /v1/records/{recordId}, GET /v1/map/records/{markerId}.

FieldTypeDescription
jurisdiction
stringThe registry's code (IL).
Example "IL"
registryName
stringThe registry's name.
recordUrl
string (uri)The registry's own link to this registrant, for a reviewer to follow and double-check the match on the registry's site. On some registries it is a registry-wide page rather than the registrant's own; "" when the registry publishes no page per registrant. It is a link, not a key: store personRef with jurisdiction to recognise the person.
personRef
string or nullThe person behind this registry's listing: prs_ and 20 hex characters, the same value when the registry republishes the listing under a new number. null when this entry carries no person reference.
Example "prs_3c9e1f0a7b2d4e6f8a1b"
recordedAt
string (date-time) or nullWhen OffenderSearch first recorded this registry's record, ISO-8601. query.createdAtStart and createdAtEnd filter on it.
lastCheckedAt
string (date-time) or nullWhen this registry's record was last confirmed, ISO-8601.
sourceUpdatedAt
string (date-time) or nullWhen the registry itself says it last changed the record, ISO-8601; null when the registry publishes no such date. query.updatedAtStart and updatedAtEnd filter on it.

The StateData object — extended per-state registry fields

The extended per-state detail. Returned only when the request sends include: ["stateData"]; otherwise stateData is null and omittedFields names it. Each field is "", [] or null when the registry does not publish it.

Returned or accepted by POST /v1/search, GET /v1/searches/{searchId}, GET /v1/searches/{searchId}/results, POST /v1/search, POST /v1/batch, GET /v1/records/{recordId}, GET /v1/map/records/{markerId}.

FieldTypeDescription
stateOffenderId
stringThe registry's own offender number.
status
stringWhere the registrant stands with the registry, in its own words (Compliant, Absconded, Confinement, Released - Subject to Registration). Each state has its own vocabulary; match on the exact strings the state you care about publishes. Not a risk level.
designation
stringThe registry's statutory classification, verbatim (Sexual Predator, Sexual Offender).
registrationEnds
stringWhen the registration term ends, ISO-8601 at the published precision. "" when not published or when the registry publishes a duration instead of a date (Lifetime, 15 Years) — then datePrecision.registrationEnds is unparseable and the text is in datesAsPublished.
datePrecision
objectFor each date field on this object, how much of it the registry published: exact, year_month, year, none, or unparseable.
datesAsPublished
objectThe registry's original text for any date field that was reformatted or is not a date ({"registrationEnds": "Lifetime"}). {} when none.
verificationRequirement
stringHow often the registrant must verify with the registry, as published.
lawAgency
stringThe law enforcement agency responsible for the registrant.
judgmentOfConvictionUrl
string (uri)Link to the judgment of conviction, where the registry publishes one.
vehicles
array of objectVehicles the registrant has reported. Keys vary by registry; the common ones are listed below. [] when none are published.
vehicles[].plate
stringLicense plate as printed (UT F814NW).
vehicles[].make
stringMake (Ford).
vehicles[].model
stringModel (F150).
vehicles[].year
stringModel year, as a string ("2018").
vehicles[].color
stringColor as published.
photos
array of objectAdditional photos the registry publishes in its extended detail.
complianceStatus
stringRegistration compliance as published (Compliant, Non-Compliant).
isLifetimeRegistration
boolean or nulltrue when registration is for life, false when the registry states a fixed term, null when not published.
lastVerificationDate
stringWhen the registrant last verified with the registry, ISO-8601.
addressVerificationDate
stringWhen the registrant's address was last verified, ISO-8601.
incarcerationStatus
stringCustody status as published (Incarcerated, Released).
comments
stringFree-text remarks from the registry.
criminalHistory
stringNarrative criminal history, as published.
adjudication
stringAdult or juvenile adjudication, as published.
registrationDuration
stringThe registration term as text (10 years, Lifetime).
skinTone
stringSkin tone as published (Iowa).
residencyRestriction
stringResidency restriction, free text (Iowa).
employmentRestriction
stringEmployment restriction, free text (Iowa).
exclusionZones
array of stringAreas the registrant is barred from (Iowa).
district
stringPolice district (District of Columbia).
psa
stringPolice Service Area (District of Columbia).
quadrant
stringCity quadrant: NW, NE, SW or SE (District of Columbia).
birthCity
stringPlace of birth, city.
birthState
stringPlace of birth, state.
birthCountry
stringPlace of birth, country.
sentenceCompletionDate
stringWhen the sentence completes, ISO-8601. Distinct from registrationEnds and from offense.releaseDate.
registrationStarts
stringWhen registration began, ISO-8601.
professionalLicenses
array of stringProfessional licenses the registrant holds, as the registry prints them.
shoeSize
stringShoe size (Texas).
Example "10½"
build
stringBody build (Minnesota).
Example "Large"
shoeWidth
stringShoe width code such as D or EEE (Texas).
Example "D"
GET/v1/records/{recordId}Auth: X-API-Key

Get a record

Fetch a single normalized record by id — for re-displaying or refreshing a specific person you already found.

Pass either identifier a search published for the person: our recordId (rec_…) or the registry’s own uuid. This is our equivalent of a legacy uuid / personUuid lookup. Returns the full Record object, including every source that corroborated the person.

A recordId resolves from the results of the search that returned it, on the account that ran it, for as long as that search is retained (14 days). A uuid resolves against the full dataset, for as long as the registry keeps publishing it.

A 404 means the identifier is not current — never that the person is unregistered. A uuid belongs to the publishing jurisdiction, and jurisdictions re-issue their own identifiers, sometimes for an entire registry at once; the registrant is then published under a new uuid. Re-search by name and state and store the id the new search returns. Treat a uuid as a cache key to refresh, not as a primary key.

Contract revision 2026-08-04 — recordId is namespaced by jurisdiction. recordId is derived from jurisdiction + uuid, so it is unique across jurisdictions and remains deterministic for a given merge. Values issued before that revision are superseded: re-run your searches and key on sources[].recordUrl with its jurisdiction, which is the durable identifier.

A uuid is unique only together with its jurisdiction, so this endpoint can return 409. It is the jurisdiction’s own identifier, and jurisdictions assign them independently — 20059 identifies a Florida registrant, a Pennsylvania one *and* a Wisconsin one; 55,893 identifiers are shared across jurisdictions, covering 147,624 records. This endpoint returns a single record and does not disambiguate on your behalf: an explicit 409 is the correct contract when an identifier is ambiguous. Use recordId, which is namespaced per jurisdiction and never collides.

Request
curl https://api.offendersearch.app/v1/records/rec_4b1e \
  -H "X-API-Key: $OFFENDERSEARCH_KEY"
Response
200 OK
{
  "recordId": "rec_4b1e",
  "uuid": "b1e4-…",
  "recordType": "sex_offender",
  "name": { "first": "John", "middle": "A", "last": "Doe", "full": "John A. Doe" },
  "dob": "1980-04-12",
  "dobPrecision": "exact",
  "dobVerification": "dob_match",
  "unverified": false,
  "source": {
    "jurisdiction": "NJ",
    "registryName": "State Sex Offender Registry",
    "recordUrl": "https://…",
    "lastCheckedAt": "2026-07-25T09:14:00Z"
  }
}

404 when no record carries this identifier. A recordId resolves while the search that returned it is retained (14 days); after that, re-search by name and state, because the registry may also have re-issued its uuid. 409 when the identifier matches records in more than one jurisdiction; the detail names them, and you disambiguate by using the recordId.

Get a sex offender record by id: request and response fields

GET/v1/records/{recordId}Auth: X-API-Key

Fetch one Record by the recordId or the registry uuid a search returned. A recordId resolves while the search that returned it is retained (14 days).

Request

Path parameters
FieldTypeDescription
recordId
required
stringA recordId (rec_…) or a registry uuid from a search result.
Example "rec_ab12cd34ef56gh78ij90"

Response

200 · application/json

The record.

The body is the Record object. One registrant, normalized to the same shape across every US registry. Every key is present on every record; an empty value is "", [] or null as stated per field, never a missing key.

Errors
StatusCodeWhen
401—The X-API-Key header is missing or the key is not valid.
402—The account has no active subscription and no free-trial searches left. detail says which.
404—No record carries this identifier. A recordId resolves while the search that returned it is retained (14 days); after that, run the search again for a current recordId, or look the person up by registry uuid and state. A 404 never means the person is unregistered.
409—A uuid matches records in more than one registry. detail names them; fetch by recordId instead.

Product overview