Skip to content

Test Scenarios

The deterministic mock scenarios a test account can exercise, with the exact inputs that trigger each one. This is the source of truth for scenario inputs; the Test Accounts guide covers the surrounding behavior but does not enumerate scenarios. Accounts outside the Test environment receive an empty list.

Operations

List test scenarios

Request

Lists the deterministic mock scenarios your account can exercise, with the exact inputs that trigger each one and a description of what the resulting response represents.

This endpoint is the source of truth for which inputs produce which mock response. The Test Accounts guide covers the surrounding behavior — matching rules, async simulation, error handling, worked examples — but deliberately does not enumerate scenarios, so fetch them here rather than copying values out of a docs page.

Send every field in inputs, not just the fields in match_keys. Some are required for request validation, and some are compared against the fixture during identity matching, even though they are not what selects the scenario. match_keys lists the fields that choose which scenario you get.

A scenario is listed only when both of the following are true:

  1. your account's environment is one where that product's mock path runs, and
  2. the scenario's product is enabled on your account.

Because of the first rule, accounts outside the Test environment receive an empty array. Pilot and Live requests are served by real data sources, so there is no mock data to advertise. This is a successful empty response, not an error. See Accounts for the environment model.

Results are not paginated: the catalog is a small, fixed set that changes only when we publish new scenarios.

Security
get-bearer-token-using-oauth2
Query
productstring

Restrict results to a single product, for example instant_criminal, county_criminal or motor_vehicle_report. Returns an empty array if the product is not enabled on your account.

Example:product=county_criminal
GET
/test_scenarios
curl -i -X GET \
  'https://api.checkrtrust.com/v1/test_scenarios?product=county_criminal' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
Array [
slugstring

Stable identifier for the scenario. Safe to hard-code in your own test suite — slugs do not change once published.

Example:"county_michael_doe"
productsArray of strings

The products this scenario applies to, restricted to the ones enabled on your account. Some scenarios back several products at once, but this only ever lists products you can actually call — so every value here is safe to use. When the request includes a product filter, this contains only that product.

Example:
[
  "county_criminal",
  "county_criminal_regulated"
]
titlestring

Short label identifying the scenario.

Example:"Single misdemeanor conviction"
descriptionstring

What the response represents — the scenario a customer would encounter in real results.

Example:"One misdemeanor DUI record in Cook County, Illinois with a FINDING OF GUILTY disposition, fines and probation."
result_kindstring

Coarse classification of the outcome, for grouping and filtering. Deliberately broad: products are not homogeneous (document verification returns accept/reject, driver license status returns valid/invalid, PII validation returns a score), so anything more specific would not apply across products. Read description for the detail.

Note this describes the shape of the mock response, not an adjudication of the subject.

  • no_records — completes successfully with an empty result set
  • records_found — completes successfully with one or more records
  • not_found — the subject or identity could not be resolved
  • error — terminates in an error state
  • cancelled — terminates as cancelled, firing a not-available webhook
  • pending — remains pending for an extended period
Enum:"no_records""records_found""not_found""error""cancelled""pending"
tagsArray of strings

Optional labels describing what the scenario is useful for exercising, for example async_webhook, fcra_filtering, identity_matching or failure.

Example:
[
  "identity_matching"
]
inputsobject

The request fields to send in order to trigger this scenario. Field names match the request body of the relevant product endpoint. Send every field listed here: some are required for validation, or are compared against the fixture during identity matching, even when they do not select the scenario (see match_keys).

Example:
{
  "first_name": "Michael",
  "last_name": "Doe",
  "dob": "19850505",
  "state": "IL",
  "county_fips_code": "17031"
}
match_keysArray of strings

The subset of inputs that actually selects this scenario. Any input not listed here is still required by the endpoint but does not change which scenario you get.

This distinction matters most for county checks: the fixture is chosen by name, but the dob you send is then compared against the date of birth on each fixture record. Send a different dob and the check still completes — with an empty result set.

Example:
[
  "first_name",
  "last_name"
]
notesstring

Additional guidance for using this scenario, when there is any.

Example:"Send `score_threshold: 0` to see both profiles."
]
Response
[
  {
    "slug": "county_michael_doe",
    "products": [ … ],
    "title": "Single misdemeanor conviction",
    "description": "One misdemeanor DUI record in Cook County, Illinois with a FINDING OF GUILTY disposition, fines and probation.",
    "result_kind": "no_records",
    "tags": [ … ],
    "inputs": { … },
    "match_keys": [ … ],
    "notes": "Send `score_threshold: 0` to see both profiles."
  }
]