Guides

Sex Offender Search API

Each guide teaches one job end to end against the sandbox, then live. Start with the first search.

• Performing your first search — One request, one envelope. This guide runs three sandbox searches, reads each answer field by field, and moves the same code to production.
• Understanding search results — Read the envelope before the records. The order matters.
• Matching and confidence — The API tells you how each name matched and how the birth date agreed. Build the review queue on those two facts, not on the score alone.
• Date-of-birth matching — A date of birth narrows the search and labels every record with how the registry's birth evidence agreed. Here is how to send it and how to read it.
• Regular vs. live searches — Regular answers from the continuously updated copy in under a second. Live asks the named registries now, costs a little more, and tells you exactly which ones answered.
• Selecting registries and jurisdictions — By default a search asks all 58 US registries. Here is how to ask fewer on purpose, what that costs you in coverage, and how to tell a filter from a scope.
• Working with incomplete results — An incomplete search is labelled, never silently short. This guide turns the labels into a retry policy.
• Asynchronous searches — Submit, get a job id, collect the result when it is ready — by polling or by webhook. Built for rosters, backfills and unattended jobs.
• Batch searches — One HTTP call, many searches, results in input order. Each row is a search like any other — billed like one, and read like one.
• Retrieving individual records — A search returns records; this is how you get one of them back later, which identifier to use, and what each identifier is for.
• Verification reports — A timestamped PDF of a search you already ran, with a source citation on every record. This is the document that goes in the file.
• Evidence and supporting documents — The registry's own website, printed to one PDF per registry behind a cover page with a hash. Asynchronous, polled, and downloadable for 30 days.
• Error handling — Every refusal is JSON with a detail, with two documented exceptions. Here is what each status means, what it looks like, and whether a retry can change it.
• Front-desk visitor screening — From the ID scan to the staff screen, the reviewer's verdict, and the roster you keep watching. A complete walkthrough against the sandbox.
• Go-live checklist — Ten checks between a working sandbox integration and production.

Criminal Records API

The surname anchor, what a record means, and the live, batch and async paths — one job per guide.

• Your first criminal search — One request, one surname, one envelope. This guide takes you from a test key to a correctly read answer, including the two refusals every integration must handle.
• Understanding a criminal record — A record keeps the source's own words in the top-level fields and the closed classification in normalized. Knowing which field is which is most of the job.
• Understanding record types — A developer must never be left guessing whether a record is an arrest, a charge, a conviction, a warrant or something else. Here is how to tell.
• Understanding charges — Every case carries charges[] in the source's words, and normalized.cases[].charges[] carries the classification. Read both.
• Understanding dispositions — The disposition is the outcome of a charge in the source's words; normalized…outcome is the same outcome in twelve words. It is the field that separates an accusation from a conviction.
• Arrests vs. charges vs. convictions — A booking is not a charge, a charge is not a conviction, and the API keeps them apart. So must your integration.
• Record normalization — The source's words at the top level; the closed vocabularies in normalized. Nothing is overwritten.
• Matching & confidence scores — The surname anchors, the first name scores, the birth date decides. Three fields explain every match, and matchConfidence is the one you should trust least on its own.
• Date-of-birth matching — One query reaches every kind of birth evidence a record publishes: a full date, a year, or an age. The record tells you which one it had.
• Jurisdiction & location filtering — Two kinds of place: where the record is (jurisdiction) and where the person lives (residence). The request fields tell them apart, and so should you.
• Coverage & data sources — A clear answer is only as good as the sources behind it. The catalog is public, the freshness is per source, and every search says which sources stood behind it.
• Cached vs. live verification — The stored copy answers in under a second. A live re-check asks the source now, costs more, and tells you exactly which sources answered.
• Asynchronous searches — Up to two live sources answer inside the request. More than two, or a source that cannot run inline, becomes a job: a 202, a poll URL, and the same envelope at the end.
• Batch searches — One HTTP call, up to a thousand cached searches, one result per row in input order. Each row that runs is billed as a search, and no row can be live.
• Handling partial results — A cached search is always complete. A live check can fall short at one source, and when it does the envelope says exactly where, why, and whether a retry is worth it.
• Handling false positives — Common names produce candidates. The API gives you the tools to review them and to remember the outcome.
• Retrieving reports — A report is the PDF attestation that a search was performed: the query, the time, the records grouped by match strength, the public source citations, and the notice that it is not a consumer report.
• Error handling — Two body shapes, one rule: branch on error.code from the criminal service and on the HTTP status from the gateway. Then retry only what the message says was never searched.

Monitoring API

Standing watches on people and places: creating monitors, reading alerts, delivery and billing.

• Creating your first monitor — One POST creates a standing watch. This guide takes you from a test key to a delivered alert in four calls.
• Person monitoring — A person monitor follows an identity, not a listing. Get the criteria right and the alert stream stays quiet until something real happens.
• Location monitoring — A location monitor stands watch over a place. Give it a centre and a radius, and it reports who moves in, changes, or moves out.
• Understanding alerts — One alert per person per registry, with a stable id that carries the latest event. Read it in order and de-duplicate on it.
• Email & webhook delivery — Email for people, a webhook for systems. Here is exactly what arrives, what the URL must look like, and how retries work.
• Webhooks, duplicates & cancelling — A webhook per alert, retried next run if it fails, de-duplicated by alert id on your side, and a monitor you cancel when the person leaves.
• Managing & cancelling — A monitor has two states and one lifecycle call. This guide covers listing, inspecting, retiring and what each answer means for your records and your bill.
• Billing & limitations — Flat, per monitor, per cycle, counted when the invoice is prepared. Everything else about cost and coverage follows from that sentence.

FCRA Partner API

For approved partners: orders, results, evidence, disputes and the consumer portal, in the order you build them.

• Partner approval & auth — The FCRA API is not self-serve. This guide shows how to tell whether an account is enabled, what each caller can do, and how to build against the sandbox while approval is pending.
• Registering end users — Every order names an end user. Register each one once, with its certification and the purposes it holds, and the orders follow.
• Creating orders — One consumer, one end user, one purpose, one consent attestation, one or two searches. The order is accepted at once and finishes in the background.
• Statuses & results — A search ends in one of three results, and every record it did not furnish has a reason code. Read the status, then the result, then the withheld counts.
• Evidence & re-verification — Every live check is captured and hash-pinned; every finished search can be run again. Here is how to read the one and trigger the other.
• Webhooks — Signed events carry identifiers and statuses, never personal data. Verify, then fetch the object with your key.
• Managing disputes — A dispute is an endpoint. Open it with the records and the date it reached you, follow it by webhook, and apply the outcome everywhere you hold the record.
• Consumer portal & reports — Every order carries a code the consumer can use, a report you can fetch, and a public receipt anyone can check. This guide wires all three.
• Sandbox & errors — Seven last names cover every outcome; one envelope covers every refusal. Build your test suite on the first and your error handling on the second.

Industry solutions

Researched, end-to-end articles for the industries that screen with these APIs — how screening works there today, where each endpoint fits, and a reference integration you can run. All solutions.