Search scope

How the scope is built

Every order carries a search plan: the counties, states and national tier it searches, why each is there, and the sources behind each. The plan is computed from the subject’s address history and the order’s use location before anything runs, stored on the order, shown in the report, and it decides which sources the live discovery checks.

1. Each address inside the lookback window is placed in a county — by the county you name, else by the ZIP, else by the city (a city that straddles a county line lists every county it touches).
2. The counties around each residence county come in: those whose internal point lies within radiusMiles, nearest first, up to maxNeighborCounties. County lines and state lines do not stop it.
3. The use location’s county and state come in; the states of every in-scope county come in; the national tier is always in.
4. Each jurisdiction is matched to the sources we hold for it — county, city and regional criminal sources by county, statewide sources by state, the federal tier, and the sex offender registry of each state. A source added to the catalog with its geography appears in every later plan with no change on your side.
5. A county with no county-level source is reported as a gap, with the statewide sources that still cover it. The result is unchanged unless the policy sets requireCountyCoverage.

Preview before you order

POST /v1/fcra/search-plans returns the plan for an address history, a use location and the searches you would order, without placing an order: nothing is stored, nothing is metered, no evidence row is written. Use it to show a reviewer where a search will go, or to decide whether to widen it.

curl -X POST "https://api.offendersearch.app/v1/fcra/search-plans" \
  -H "X-API-Key: $OFFENDERSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endUserId": "eu_0b44acbeefeaa7d7",
    "addresses": [
      { "state": "OH", "city": "Columbus", "postalCode": "43215", "from": "2019-01" },
      { "state": "TX", "postalCode": "76102", "from": "2012-01", "to": "2017-06" }
    ],
    "useLocation": { "state": "OH", "city": "Dublin" },
    "searches": [{ "type": "sex_offender" }, { "type": "criminal" }],
    "scopePolicy": { "maxNeighborCounties": 3 }
  }'

The SearchPlan object — where an order searches and why

The plan: every address as it was read, every jurisdiction in scope with its reasons and sources, the gaps, and the totals.

Returned or accepted by POST /v1/fcra/search-plans, GET /v1/fcra/orders/{order_id}/scope.

The ScopeAddress object — one address as the plan read it

One address from the request, with how it was placed in a county and whether it fell inside the lookback window.

Returned or accepted by POST /v1/fcra/search-plans, GET /v1/fcra/orders/{order_id}/scope.

The ScopeJurisdiction object — one county, state or the national tier

One jurisdiction in the plan with why it is there and the sources behind it.

Returned or accepted by GET /v1/fcra/orders/{order_id}/report, POST /v1/fcra/search-plans, GET /v1/fcra/orders/{order_id}/scope.

The ScopeReason object — why a jurisdiction is in scope

One reason a county or state is in the plan. Only the keys that apply to the reason are present.

Returned or accepted by GET /v1/fcra/orders/{order_id}/report, POST /v1/fcra/search-plans, GET /v1/fcra/orders/{order_id}/scope.

The ScopeSource object — a source behind a jurisdiction

One source the plan will search for a jurisdiction: a criminal source from the source registry, or a sex offender registry.

Returned or accepted by GET /v1/fcra/orders/{order_id}/report, POST /v1/fcra/search-plans, GET /v1/fcra/orders/{order_id}/scope.

The ScopeGap object — a county with no county-level source

A county in scope for which we hold no county-level source, and what still covers it.

Returned or accepted by GET /v1/fcra/orders/{order_id}/report, POST /v1/fcra/search-plans, GET /v1/fcra/orders/{order_id}/scope.

The scope policy

A scope policy says how far beyond the subject’s own counties an order searches. Set it once on an end user (scopePolicy on POST /v1/fcra/end-users or PATCH); every order for that end user uses it, and an order may override any field with its own scopePolicy. Every field is optional.

The ScopePolicy object — where an order searches

Where an order searches beyond the subject's own counties. Set it once on an end user; override any field on an order. Every field is optional and the defaults are in each description.

Returned or accepted by POST /v1/fcra/end-users, GET /v1/fcra/end-users, GET /v1/fcra/end-users/{end_user_id}, PATCH /v1/fcra/end-users/{end_user_id}, POST /v1/fcra/orders, GET /v1/fcra/orders/{order_id}/report, POST /v1/fcra/search-plans, GET /v1/fcra/orders/{order_id}/scope.

The ScopeTarget object — a county or state to add or remove

A county (by name) or a whole state, named in a scope policy's extraJurisdictions or excludeJurisdictions.

Returned or accepted by POST /v1/fcra/end-users, GET /v1/fcra/end-users, GET /v1/fcra/end-users/{end_user_id}, PATCH /v1/fcra/end-users/{end_user_id}, POST /v1/fcra/orders, GET /v1/fcra/orders/{order_id}/report, POST /v1/fcra/search-plans, GET /v1/fcra/orders/{order_id}/scope.

The scope on an order and in the report

The order object carries scope: the totals and one line per jurisdiction. GET /v1/fcra/orders/{id}/scope returns the full plan, addresses included. The report carries the same plan without the addresses, so whoever reads a clear can see exactly which counties, states and sources it rests on.

The ScopeSummary object — an order's scope in brief

The scope on an order: the totals and one line per jurisdiction. The full plan is GET /v1/fcra/orders/{order_id}/scope.

Returned or accepted by POST /v1/fcra/orders, GET /v1/fcra/orders, GET /v1/fcra/orders/{order_id}, POST /v1/fcra/orders/{order_id}/cancel, POST /v1/fcra/orders/{order_id}/adjudication.

The ReportScope object — the scope as stated in a report

The plan the report ran under, without the addresses: jurisdictions, sources, gaps and totals. A reader holds a clear against exactly this.

Returned or accepted by GET /v1/fcra/orders/{order_id}/report.

Gaps

A gap is a county in scope for which we hold no county-level source. It is listed with the live statewide sources that still cover the county (a state court index, a department of corrections roster, the exclusion lists) and any county-level source mapped for it and coming soon. A gap does not change the result; set requireCountyCoverage on the policy if your program needs it to.

The healthcare search in the plan

A healthcare search is not tied to the consumer’s counties: an exclusion in any state bars the person from that state’s program, so every healthcare source is searched for every consumer. The plan shows them in its own healthcare block — never mixed into jurisdictions, so asking for a healthcare search never widens where the criminal search looks.

A source we add to the healthcare package appears in the next plan, the next healthcare search and its coverage with no change on your side.

The live scope inside the search plan

The plan decides which sources an order covers; liveScope decides which of them are asked live. With relevant and all, the plan’s sources in the relevant states are searched live and the rest in our data. With matches, every source in the plan is searched in our stored copy first; a source in the plan that we hold no copy of is searched live (copyStatus: "none", liveReason: "no_copy" on its coverage row), and a possible record found anywhere in the plan is confirmed with the agency that keeps it before it can be reported. The plan is the same whichever live scope the order runs.

The identity layer

Every order carries identity. Identity verification (a government ID and selfie check) and address-history trace are coming soon; until a provider is live, both report not_available and the note says what the order was matched on: the name, the full date of birth and the addresses provided. An address source other than declared is refused until then.

The Identity object — verification and trace status

The identity layer of an order. Identity verification and address-history trace are coming soon; until a provider is live both report not_available and orders are matched on the name, full date of birth and the addresses provided.

Returned or accepted by POST /v1/fcra/orders, GET /v1/fcra/orders, GET /v1/fcra/orders/{order_id}, POST /v1/fcra/orders/{order_id}/cancel, GET /v1/fcra/orders/{order_id}/report, POST /v1/fcra/orders/{order_id}/adjudication.

Test FCRA orders on the sandbox server

With a test key (os_test_…) every account is a sandbox FCRA partner on the sandbox server, with the same last-name rules. Register an end user, then place orders against it; nothing is billed. An order finishes right after the 202: read it once with GET /v1/fcra/orders/{orderId}.

Base URL

https://sandbox.offendersearch.app Not https://api.offendersearch.app, which takes live keys only.

Test key

In the dashboard, Developers → API keys → Create test key. Test keys begin os_test_; send yours in the X-API-Key header.

curl -X POST "https://sandbox.offendersearch.app/v1/fcra/end-users" \
  -H "X-API-Key: $OFFENDERSEARCH_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "Sample Staffing LLC",
      "permissiblePurposes": [
        "employment"
      ],
      "certification": {
        "text": "End user certifies it will use reports only for employment purposes.",
        "version": "v1",
        "certifiedAt": "2026-10-01T12:00:00Z"
      }
    }'

curl -X POST "https://sandbox.offendersearch.app/v1/fcra/orders" \
  -H "X-API-Key: $OFFENDERSEARCH_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "endUserId": "{endUserId}",
      "permissiblePurpose": "employment",
      "consent": {
        "obtainedAt": "2026-10-01T12:00:00Z",
        "method": "esign"
      },
      "subject": {
        "firstName": "Pat",
        "lastName": "Records",
        "dob": "1980-01-01"
      },
      "searches": [
        {
          "type": "sex_offender"
        },
        {
          "type": "criminal"
        }
      ]
    }'

Try it here

Pick a scenario, edit the request, and run it against the sandbox from this page. The explorer accepts os_test_ keys only and never reaches the live host, so nothing here is billed; the “production” code it copies is for your own backend with a live key.

curl -X POST https://sandbox.offendersearch.app/v1/fcra/end-users \
  -H "X-API-Key: $OFFENDERSEARCH_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Sample Staffing LLC", "permissiblePurposes": [ "employment" ], "certification": { "text": "End user certifies it will use reports only for employment purposes.", "version": "v1", "certifiedAt": "2026-10-01T12:00:00Z" } }'

Every test name: FCRA API sandbox orders·Postman collection·FCRA API sandbox