Clearances

Clearances: dismiss a false-positive match once, per subject

A search for a common name returns people who are not the person you are screening. A clearance records, for one subject you screen — a resident, a visitor, an applicant, an employee, identified by your own subjectId — that one returned person is or is not that subject. Every later search that sends the same subjectId honours it: a person marked not_this_person leaves records[] and is listed in cleared[], so the same reviewer is never asked the same question twice.

Clearances are keyed on personRef — the durable identifier every record and every sources[] entry carries (see Record identity). They are included in your search price, no extra charge, and the flow is the same on the Criminal Search API.

Who uses clearances

The clearance flow: search, review, clear, search again

1. Search with a subjectId

Send your id for the person being screened as subjectId — and, if you screen for more than one facility or client, your id for that client as clientId. Nothing else about the request changes. The response gains counts.clearedSuppressed and cleared[]; on a first search both are empty.

curl -X POST https://api.offendersearch.app/v1/search \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "query": { "firstName": "Jordan", "lastName": "Rivera", "dob": "1988-04-12" },
        "subjectId": "resident-48213",
        "clientId": "facility-07"
      }'

{
  "searchId": "srch_9f2c1a7b",
  "status": "complete",
  "counts": { "records": 1, "recordsReturned": 1, "sourcesQueried": 58,
              "sourcesComplete": 58, "sourcesIncomplete": 0, "sourcesSkippedByScope": 0,
              "clearedSuppressed": 0 },
  "cleared": [],
  "records": [
    { "recordId": "rec_6d066763131ebe8c77ea",
      "personRef": "prs_3c9e1f0a7b2d4e6f8a1b",
      "name": { "first": "Jordan", "last": "Rivera", "full": "Jordan Rivera" },
      "dob": "1988-04-12", "matchState": "dob_match", "matchConfidence": 1.0,
      "source": { "jurisdiction": "TX", "personRef": "prs_3c9e1f0a7b2d4e6f8a1b",
                  "recordUrl": "https://…" } }
  ]
}

2. A person reviews the match

The registrant shares the resident’s name and date of birth, so matchState is dob_match. A reviewer compares the photograph, the registry’s address and the registry’s own page (source.recordUrl) with the resident in front of them and decides. Keep the searchId, the personRef and the recordId: the verdict cites all three.

3. Record the verdict

POST /v1/clearances with the verdict. searchId must be a search in your account’s 14-day history whose stored results contain the personRef — the proof that the person was reviewed from a real result. A second verdict for the same subject, client and person replaces the first.

curl -X POST https://api.offendersearch.app/v1/clearances \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "product": "sex_offender",
        "subjectId": "resident-48213",
        "clientId": "facility-07",
        "personRef": "prs_3c9e1f0a7b2d4e6f8a1b",
        "recordId": "rec_6d066763131ebe8c77ea",
        "searchId": "srch_9f2c1a7b",
        "verdict": "not_this_person",
        "reviewer": "admissions-desk",
        "note": "Photo and registry address do not match the resident."
      }'

{
  "id": "clr_7d2f41c0a9b3e8f6",
  "product": "sex_offender",
  "verdict": "not_this_person",
  "personRef": "prs_3c9e1f0a7b2d4e6f8a1b",
  "recordId": "rec_6d066763131ebe8c77ea",
  "searchId": "srch_9f2c1a7b",
  "subjectId": "resident-48213",
  "clientId": "facility-07",
  "reviewer": "admissions-desk",
  "note": "Photo and registry address do not match the resident.",
  "createdAt": "2026-10-18T14:02:11+00:00",
  "revokedAt": null,
  "supersedes": null
}

4. Search again — the cleared person is gone, and accounted for

The next search for the same subjectId and clientId runs in full, then removes the cleared person. counts.records counts what you received; counts.clearedSuppressed says how many were removed, and cleared[] names each one with the clearance that applied, so an interface can say “1 previously cleared person hidden” and link to the decision.

{
  "searchId": "srch_c41e8d20",
  "status": "complete",
  "counts": { "records": 0, "recordsReturned": 0, "sourcesQueried": 58,
              "sourcesComplete": 58, "sourcesIncomplete": 0, "sourcesSkippedByScope": 0,
              "clearedSuppressed": 1 },
  "cleared": [
    { "personRef": "prs_3c9e1f0a7b2d4e6f8a1b",
      "clearanceId": "clr_7d2f41c0a9b3e8f6",
      "verdict": "not_this_person",
      "clearedAt": "2026-10-18T14:02:11+00:00",
      "recordId": "rec_6d066763131ebe8c77ea" }
  ],
  "records": []
}

Send clearanceMode: "annotate" to keep cleared people in records[] with a clearance object attached (for an interface that greys them out), or "ignore" to answer as if no clearances existed. A this_person verdict never removes a record; it is kept and annotated in every mode. The same three fields work per row on POST /v1/batch.

What brings a cleared person back

A clearance is a verdict about the person as they were reviewed. When something about them changes, or the match becomes stronger than the one that was cleared, the person returns to records[] with clearance.stale: true and a staleReason — in every mode, and it cannot be turned off. Review the record again and record a new verdict; until you do, the person stays in the results.

{
  "recordId": "rec_6d066763131ebe8c77ea",
  "personRef": "prs_3c9e1f0a7b2d4e6f8a1b",
  "name": { "first": "Jordan", "last": "Rivera", "full": "Jordan Rivera" },
  "dob": "1988-04-12", "matchState": "dob_match",
  "clearance": {
    "clearanceId": "clr_7d2f41c0a9b3e8f6",
    "verdict": "not_this_person",
    "clearedAt": "2026-10-18T14:02:11+00:00",
    "stale": true,
    "staleReason": "offenses_changed"
  }
}

Clearance rules: personRef only, per client, until revoked

• personRef only. A clearance names one personRef and suppresses only records that carry it. Never a name, never a date of birth. A record whose personRef cannot be resolved is never suppressed.
• Per subject, per client. A verdict is scoped to the subjectId it was recorded for, and to the clientId when one was sent. Nothing one client clears affects another client’s results, even for the same person.
• Stored as hashes. subjectId and clientId are kept only as per-account hashes, never as the ids you sent. They are echoed on the request that carried them and are null on GET /v1/clearances/{clearanceId}.
• Proof of review. The searchId must be in your 14-day search history and that search must have returned the personRef — otherwise 404 search_not_found or 409 person_not_in_search.
• No expiry. A clearance applies until you revoke it. Re-surfacing is how a changed person comes back; nothing comes back on a timer.
• Revoke, don’t delete. DELETE sets revokedAt; the next search for that subject shows the person again, and the clearance stays readable with includeRevoked=true.
• Scoped to the account. Clearances survive API key rotation and are shared by every key and dashboard user on the account.
• Included in your search price, no extra charge. Nothing on /v1/clearances is metered, and a search with a subjectId is billed exactly like one without.
• Additive. A request without subjectId returns exactly what it did before clearances existed — no cleared key, no clearedSuppressed, no clearance on any record.

curl -X DELETE https://api.offendersearch.app/v1/clearances/clr_7d2f41c0a9b3e8f6 \
  -H "X-API-Key: $OFFENDERSEARCH_KEY"

{ "id": "clr_7d2f41c0a9b3e8f6", "revokedAt": "2026-11-02T09:15:40+00:00" }

Clearance endpoints

Every route authenticates with the X-API-Key header or a dashboard session. Each is documented in full below.

Search-side fields — subjectId, clientId and clearanceMode on the request; cleared[], counts.clearedSuppressed and the record’s clearance on the response — are documented on Search and Batch, and the objects they carry are defined below.

The Clearance object — every field on a recorded verdict

One verdict: the person behind a personRef is, or is not, the subject being screened. Returned by every /v1/clearances route. subjectId and clientId are echoed only on the request that carried them (create and list); on GET /v1/clearances/{clearanceId} they are null, because only a per-account hash of them is stored.

Returned or accepted by POST /v1/clearances, GET /v1/clearances, GET /v1/clearances/{clearanceId}.

The ClearedEntry object — one person a clearance hid from this response

One record a not_this_person clearance removed from records[] for the subjectId sent. cleared[] carries one of these per suppressed record, so an interface can say how many previously cleared people are hidden and link each to its clearance.

Returned or accepted by POST /v1/search, GET /v1/searches/{searchId}, POST /v1/batch.

The RecordClearance object — the clearance attached to a kept record

The clearance that names a record's person, attached as clearance when the request carried subjectId and the record was kept: in clearanceMode: "annotate", on a this_person verdict, or because a cleared person has re-surfaced (staleReason set). A record no clearance names carries no clearance key.

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