clearances

Record a verdict — a returned person is, or is not, the subject

Changed on

Records that the person behind one personRef is (this_person) or is not (not_this_person) the subject identified by your subjectId — and, for a platform serving many facilities, your clientId. From then on every search that sends the same subjectId (and clientId) honours the verdict: a not_this_person person leaves records[] and is listed in cleared[]; a this_person person is kept and annotated. Both the sex offender search and the criminal search accept the same subjectId; product says which dataset the verdict belongs to.

The verdict must cite the search that showed the person: searchId must be a search in this account's history (searches are kept 14 days) and that search's stored results must contain the personRef. That is the proof the person was reviewed. A second verdict for the same subject, client and personRef replaces the first; the new clearance's supersedes names the one it replaced.

A clearance matches by personRef only — never by name or date of birth. The person being cleared shares a name, and often a birthday, with the subject, so a name match would also hide the subject's own record. Included in the search price; nothing on this route is metered.

post/v1/clearances

Request

  • Base URL: https://api.offendersearch.app
  • URL: https://api.offendersearch.app/v1/clearances
  • Auth: API key in header X-API-Key

Request body

product'sex_offender' | 'criminal'

The dataset the verdict belongs to: sex_offender for a person returned by POST /v1/search or POST /v1/batch, criminal for one returned by POST /v1/criminal/search. A criminal personRef is scoped to one source, so a criminal clearance clears that source's records for the person.

subjectIdstring required

Your id for the person being screened. The same value you will send on later searches for them. Stored only as a per-account hash.

clientIdstring

Your facility, tenant or client id, when you screen for more than one. A clearance recorded with a clientId applies only to searches that send the same one. Stored only as a per-account hash.

personRefstring required

The person the verdict is about — the personRef the search returned (prs_ and 20 hex characters). The verdict applies to this person and no one else, never to a name or a date of birth.

recordIdstring

The recordId of the result the reviewer looked at, for the audit trail.

searchIdstring required

The search that showed this person. It must be in this account's 14-day history and its stored results must contain personRef — otherwise 404 search_not_found or 409 person_not_in_search.

verdict'not_this_person' | 'this_person' required

not_this_person — the returned person is someone else; later searches for the subject suppress (or annotate) them. this_person — the returned person IS the subject; later searches keep them and annotate the record so your interface can show the confirmed match.

reviewerstring

Who decided, in your own terms — a user id, a desk, a role.

notestring

Why, in the reviewer's words.

Example request

{
  "subjectId": "resident-48213",
  "clientId": "facility-07",
  "personRef": "prs_3c9e1f0a7b2d4e6f8a1b",
  "recordId": "rec_6d066763131ebe8c77ea",
  "searchId": "srch_9f2c1a7b",
  "reviewer": "admissions-desk",
  "note": "Photo and registry address do not match the resident."
}

Response

The verdict was recorded and applies to the next search for this subject.

idstring

clr_ followed by an opaque id.

product'sex_offender' | 'criminal'
verdict'not_this_person' | 'this_person'
personRefstring

The person the verdict is about.

recordIdstring nullable

The result the reviewer looked at, when one was cited.

searchIdstring

The search that showed the person.

subjectIdstring nullable

Echoed from the request that carried it; null on GET /v1/clearances/{clearanceId}.

clientIdstring nullable

Echoed from the request that carried it; null when none was sent and on GET /v1/clearances/{clearanceId}.

reviewerstring nullable
notestring nullable
createdAtstring date-time
revokedAtstring date-time nullable

null while the clearance applies; set by DELETE /v1/clearances/{clearanceId}.

supersedesstring nullable

The id of the clearance this one replaced — a second verdict for the same subject, client and personRef supersedes the first. null for a first verdict.

Example response

{
  "id": "clr_7d2f41c0a9b3e8f6",
  "personRef": "prs_3c9e1f0a7b2d4e6f8a1b",
  "recordId": "rec_6d066763131ebe8c77ea",
  "searchId": "srch_9f2c1a7b",
  "subjectId": "resident-48213",
  "clientId": "facility-07"
}

Changes