Developer docs · v1.0.0

Schools, camps and youth-serving organisations

Coaches, counsellors, chaperones and the parent at the gate on game day: a registry check that answers in under a second, a criminal-records check a safety director can read, and a record of who was screened, when, and by whom.

How screening works in youth-serving organisations today

Youth-serving organisations screen on a season or a year, not on a hire. A volunteer coordinator, athletic director, camp director or safety officer collects an application and a consent form, orders a check through a screening provider or a state program, reviews anything that comes back, and records an approval before the person is placed with children. The rule-makers are the organisations themselves and the states, and the cadences are explicit. Little League requires a national criminal background check that includes a sex offender registry component on every volunteer and hired worker with repetitive access to children, every year, because appointments last one year; a registry hit must be referred to the national office before any appointment. The American Camp Association's accreditation standards call for a criminal background check on seasonal staff annually and on year-round staff at least every five years, plus an annual registry check and a voluntary disclosure statement. National governing bodies under the U.S. Center for SafeSport and the U.S. Olympic & Paralympic Committee generally require adults in positions of authority over athletes to pass a background screen every two years, with SafeSport training on its own cycle. Pennsylvania's Child Protective Services Law (Act 153 of 2014 as amended by Act 15 of 2015) requires volunteers with direct contact with children to hold three clearances — the state police criminal history, the child-abuse history clearance and, unless the volunteer has been a continuous Pennsylvania resident for ten years, an FBI fingerprint check — renewed every 60 months. The federal National Child Protection Act of 1993, as amended, is the framework through which qualified youth-serving entities obtain fingerprint-based national criminal history checks via their state.

Event day is a different rhythm. A school may verify whether a campus visitor is a registered sex offender against the state database or any other database it can access, and its board must adopt a policy for what happens when one is identified (Texas Education Code § 38.022 is the model many districts follow); several states make it an offence for a registrant to be on school property without permission or without reporting to the office (Louisiana R.S. 14:91.1 requires a registrant to notify the principal's office on arrival and departure). The organisation's need is a check that fits in the sign-in line: name and date of birth from an ID, an answer in a second, a review path that does not accuse a parent on a name coincidence.

Whether the FCRA applies to a volunteer check is a question for counsel. The statute governs consumer reports used for employment purposes; FTC staff have treated reports on volunteers as within that purpose in informal opinion letters, and many organisations run volunteer checks under the full FCRA process for that reason. Paid staff and coaches are employees, and their checks are consumer reports under the FCRA when a consumer reporting agency furnishes them. The records that matter are the registry match first — the strongest, most specific signal, verified by a full date of birth — and then convictions for offences against children, violence and, for drivers, serious traffic offences; an arrest or a dismissed charge is not a conviction and most organisational policies say so.

What the API does and does not decide. The API returns candidates with the evidence for each match. A person reviews them and the organisation's policy decides. The standard API is not a consumer report and must not be the sole basis for an employment decision about paid staff; that path is the FCRA Partner API. Counsel decides whether a given volunteer program must run the same way.

Where the API fits

Workflow stepEndpointFields that matter
Screen one volunteer or coach at applicationPOST /v1/search and POST /v1/criminal/searchquery.firstName, query.lastName, query.dob from the application; subjectId = your volunteer id, clientId = the league, camp, school or chapter; registry: matchState, matchDetail; criminal: cases[].charges[].disposition, matchState, recordCategory
Re-screen the whole roster each seasonPOST /v1/batch (registry) and POST /v1/criminal/batchUp to 1,000 rows; subjectId per row, clientId once; rows carry counts.sourcesIncomplete and warnings[] but no searchId
Check a visitor at the gate or the front officePOST /v1/search with deadlineMsA bounded wait; status: "partial" is Incomplete, never Clear; show the state to staff only
A coordinator confirms a name match is someone elsePOST /v1/clearancesproduct: "sex_offender", subjectId, clientId, personRef, recordId, searchId, verdict: "not_this_person", reviewer
Know about changes between seasonsPOST /v1/monitors (type: "person")One monitor per dataset; label with the role; email to the safety officer; cancel when the person leaves
Paid staff and coaches (employment decisions)POST /v1/fcra/ordersThrough an approved partner: permissiblePurpose: "employment", consent, subject, useLocation
A document for the volunteer filePOST /v1/report, POST /v1/criminal/reportsearchId of the search (within 7 days); PDF with a citation per record and the use-restriction notice

Reference integration

One module, three jobs. screen_volunteer runs the registry and criminal checks for one applicant; rescreen_roster sweeps the active roster through batch at the start of a season; gate_check is the event-day call with a bounded wait. The outcome rule for the registry: clear is complete with no records; incomplete is no records with unfinished registries; match is matchState: "dob_match" on an exact legal surname; otherwise review. For criminal records every hit is review — the module counts convictions by reading each charge's disposition and counts DOB-verified records, and the safety director reads the rest. Run it against the sandbox with the test names.

"""Volunteer and coach screening — OffenderSearch, Python 3.11+, requests.

Three jobs in one module: screen one volunteer (registry + criminal records), re-screen the whole
roster each season (batch), and check a visitor at the gate on event day (registry, sub-second).

  OFFENDERSEARCH_API_KEY=os_test_...  OFFENDERSEARCH_BASE=https://sandbox.offendersearch.app  python volunteers.py
"""
from __future__ import annotations

import os
import time
from dataclasses import dataclass, field

import requests

API_KEY = os.environ["OFFENDERSEARCH_API_KEY"]
BASE = os.environ.get("OFFENDERSEARCH_BASE", "https://sandbox.offendersearch.app")
HEADERS = {"X-API-Key": API_KEY, "Content-Type": "application/json"}
ORG = "org-riverside-youth-soccer"           # your clientId: the league, camp, school or chapter


@dataclass
class Check:
    product: str                      # "registry" | "criminal"

What the safety director sees for review: the registry candidate's photo (images[]), name and aliases, dob or age, registrationState and addressStates, offenses[] with tier and dates, and matchDetail saying how the name matched (nickname, prefix, fuzzy, an alias). For a criminal record: recordType (a court_case, jail_booking, doc_inmate, warrant), each case's charges[] with statute, description, severity, disposition and dispositionDate, the record's matchState and unverified flag, and recordCategory for a closed vocabulary. The criminal guides explain how to read a booking against a conviction. A confirmed false positive goes back as a clearance so the same parent-coach is not flagged again next season.

Send the date of birth. Every organisational standard above screens on a full date of birth. Without query.dob, a common name returns possible matches with matchState: null and every hit is Review; with it, a record whose published birth date contradicts the applicant's is excluded and a confirmed one is labelled dob_match. Searching by date of birth.

Ongoing monitoring

Annual and biennial cycles leave long gaps. A person monitor on each active volunteer closes them: product: "sex-offender", type: "person", the name and date of birth from the approved application, minConfidence left unset (which means year_match when a dob is sent), and the safety officer's address in channels.email. A new alert is a reason to re-run the check and review, not a decision. Create a second monitor with product: "criminal" for the records side. Cancel both when the volunteer leaves the roster; evaluation stops at once and nothing is charged on an invoice prepared after the cancel.

Watch one coach between seasons
curl -X POST https://sandbox.offendersearch.app/v1/monitors \
  -H "X-API-Key: $OFFENDERSEARCH_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "product": "sex-offender",
    "type": "person",
    "person": { "firstName": "Jordan", "lastName": "Rivera", "dob": "1988-04-12" },
    "label": "org-riverside-youth-soccer / vol-2088 (U12 coach)",
    "channels": { "email": "safety@riverside-youth.example" }
  }'

For a campus or camp property, a location monitor (type: "location", a radius around the site) tells the office when a registrant is newly listed nearby, which many districts fold into their § 38.022-style visitor policy. Person monitoring, Location monitoring.

When this is FCRA

A paid coach, counsellor, bus driver or teacher is an employee; a report used to decide whether to hire or keep them is a consumer report, and the path is the FCRA Partner API through an approved partner: an end user for the organisation with permissiblePurposes: ["employment"], one order per candidate with a consent attestation and useLocation, results by signed webhook, a report with a verifiable receipt, and a dispute path for the candidate. The organisation still owes the standalone disclosure and written authorization before the order and the pre-adverse and adverse-action notices after it (15 U.S.C. § 1681b(b), § 1681m). For unpaid volunteers, whether the same process is required is for counsel; organisations that choose it run volunteers through the same orders with the same purpose. The standard Sex Offender and Criminal Records APIs used in the module above are not consumer reports and must not be the sole basis for an employment decision; they serve the organisation's own safety screening and its event-day checks.

Evidence and audit

Accreditors, insurers and parents ask the same question: who was screened, when, against what, and who decided. Record this per person per season:

A volunteer screening record your system keeps
{
  "volunteerId": "vol-2088",
  "season": "2026-27",
  "screenedAt": "2026-10-25T14:02:11Z",
  "registry":  { "searchId": "srch_9f2c1a7b", "status": "complete", "sourcesComplete": 58, "sourcesQueried": 58, "state": "clear" },
  "criminal":  { "searchId": "crs_7f2a1c9e0b4d6a8f1e23", "status": "complete", "state": "review",
                 "recordsReviewed": 1, "reviewer": "safety-director", "decision": "approved", "decidedAt": "2026-10-26T09:15:00Z" },
  "clearances": ["clr_7d2f41c0a9b3e8f6"],
  "monitorId": "mon_b8f40d7afb9dc0d8",
  "reportPdf": "rpt_9f2c1a7b3e4d"
}
  • searchId and status for each product, with counts.sourcesComplete against counts.sourcesQueried so a partial sweep is visible later.
  • The reviewer, the decision and its time for anything that was review or match; the clearance ids for confirmed false positives (GET /v1/clearances?subjectId=…&clientId=…&includeRevoked=true reproduces them).
  • The report id from POST /v1/report or POST /v1/criminal/report (the X-Report-Id header) when policy wants a PDF in the file; both must be requested within 7 days of the search.
  • Stored results remain readable at GET /v1/searches/{searchId}/results for 14 days (410 afterwards); your record outlives them, so keep the fields above rather than the raw envelope.
  • The monitor id, so a later alert can be tied to the person and the season it concerned.
  • For event-day checks, the searchId, the desk state and the staff member who handled a review or match; never the ID image or document number — a hash of it as subjectId is enough to recognise a return visit.

Rollout plan

  1. Write the policy first. Which roles are screened, how often, which outcomes block placement, who reviews, and what the event-day procedure is for Review and Match. Map it to the standards that bind you (your league or NGB, your accreditor, your state).
  2. Sandbox. With an os_test_ key, run the module above through a clear volunteer, a DOB-verified registry match, a name-only review, a criminal conviction and a booking without disposition; record a clearance and re-run.
  3. Application form. Collect legal name, prior names, full date of birth and states lived in; send prior names as a second search and merge by personRef.
  4. Reviewer screen. Photo, offenses, registry state, matchDetail; criminal charges with dispositions; a one-click not_this_person that posts the clearance.
  5. Season sweep and monitors. Schedule the batch re-screen on your season boundary; create person monitors on approval and cancel on departure.
  6. Paid staff. Route employee checks through your FCRA partner; keep volunteer and employee flows visibly separate in the UI.
  7. Go live. Switch host and key; confirm the first searchId opens on GET /v1/searches/{searchId}/results and the first report renders. Go-live checklist.