Test accounts are a crucial part of the Checkr Trust API integration process. They allow you to validate your integration without making calls to production data sources. This guide explains how test accounts work and provides details about the available test data.

Test accounts are designated with the stage "test" and are designed to:

• Validate your integration code works correctly
• Understand the API response formats
• Test error handling scenarios
• Familiarize yourself with the product workflow

Please contact your account representative or support@checkrtrust.com for additional questions.

Test accounts currently support:

• Instant Criminal Record Checks
• Targeted Instant Criminal Checks
• Criminal Checks
• Sex Offender Registry Checks
• Regulated Instant Criminal Checks
• Regulated Criminal Reports
• Regulated Eviction Checks
• County Checks
• Identity Verifications (PII Validation)
• Identity Verifications (Document Verification)
• Identity Verifications (Personal Identity Records)
• Identity Verifications (Reverse Phone Lookup)
• Driver Checks (asynchronous; results delivered via webhook simulation) Other products are not available in test mode and attempting to enable them for a test account will not be allowed.

1. Using Test Data

   • When making requests with PII that matches our test profiles, you'll receive predefined mock responses
   • When making requests with PII that doesn't match test profiles, you'll receive a successful response (HTTP 200) with empty results
   • This allows you to test both your success and "no results found" handling
   • Important: For most test-mode mocks, only the first and last name are used to match test profiles. Other PII fields (DOB, SSN, etc.) are ignored for mock selection.
     • Exception: Driver Checks (driver_license_status, motor_vehicle_report) use deterministic mock selection based on check_type and driver_license_number (and still enforce normal input validation, e.g. required fields and state-specific requirements).
     • Exception: Reverse Phone Lookup (reverse_phone) uses deterministic mock selection based on country_code and phone (US numbers are matched on the 10-digit national number).

2. Product Authorization

   • Each test account must have products explicitly enabled via product configurations
   • Attempting to use a product that isn't enabled will result in a 401 Unauthorized response

The test environment provides a set of mock profiles that return predefined results. Each mock profile is designed to demonstrate specific scenarios you might encounter in production.

Here are the test profiles available for instant criminal and sex offender registry checks:

1. Marcus Williams

   • Results: Multiple traffic violations and a domestic violence charge with match confidence level

2. Sarah Martinez

   • Results: Multiple traffic violations across different states

3. David Thompson

   • Results: Multiple sexual offense records and failure to register as sex offender

4. Lisa Chen

   • Results: DUI and traffic violations

5. Dolores Abernathy

   • Results: Multiple speeding violations

6. Oliver Smith

   • Results: Sexual offense registry record

7. Rebecca Foster

   • Results: Theft and traffic violations

8. Miguel Santos

   • Results: Sex offender registry record

9. Kimberly Park

   • Results: Sex offender registry record and related court / department of corrections

10. Tyler Brooks

    • Results: Sex offender registry record and traffic violation

11. Ava Jones

• Results: Sexual offense records and failure to register as sex offender

1. James Wilson

• Results: Two records. One recent GUILTY conviction (survives FCRA filtering). One old non-conviction with adjudication withheld from 2016 (removed by FCRA 7-year lookback rule for non-convictions).

2. Emma Davis

• Results: Two records. Both are non-convictions (dismissed / withheld) from 2014–2015, older than the FCRA 7-year lookback window. All records are removed by FCRA.

Any other name returns an empty result set (no records found).

Request (James Wilson):

{
  "first_name": "James",
  "last_name": "Wilson",
  "dob": "19850420",
  "permissible_purpose": "Employment",
  "filter_context": {
    "candidate_jurisdiction": {
      "state": "FL"
    }
  }
}

Response (201) — one record returned, one removed by FCRA 7-year rule:

{
  "id": "<uuid>",
  "check_type": "instant_criminal_regulated",
  "profile_id": "<uuid>",
  "results": [
    {
      "category": "Criminal/traffic",
      "record_id": "<record-id>",
      "person": {
        "first_name": "JAMES",
        "last_name": "WILSON",
        "dob": "19850420"
      },
      "cases": [
        {
          "court_name": "FL Orange Courts",
          "charges": [
            {
              "description": "BATTERY",
              "offense_date": "20220601",
              "record_date": "20220601",
              "dispositions": [
                { "disposition_type": "conviction", "disposition": "ADJUDICATED GUILTY" }
              ],
              "checks": []
            }
          ],
          "checks": []
        }
      ],
      "source": {
        "id": "FL_Orange_View",
        "category": "court",
        "state": "FL"
      },
      "checks": []
    }
  ]
}

Request (Emma Davis):

{
  "first_name": "Emma",
  "last_name": "Davis",
  "dob": "19900712",
  "permissible_purpose": "Employment",
  "filter_context": {
    "candidate_jurisdiction": {
      "state": "FL"
    }
  }
}

Response (201) — all records removed by FCRA, results is empty:

{
  "id": "<uuid>",
  "check_type": "instant_criminal_regulated",
  "profile_id": "<uuid>",
  "results": []
}

1. James Wilson

• Results: Two records. One recent GUILTY conviction (survives FCRA filtering). One old non-conviction with adjudication withheld from 2016 (removed by FCRA 7-year lookback rule for non-convictions).

2. Emma Davis

• Results: Two records. Both are non-convictions (dismissed / withheld) from 2014–2015, older than the FCRA 7-year lookback window. All records are removed by FCRA.

Any other name returns an empty result set (no records found).

Request (James Wilson):

{
  "first_name": "James",
  "last_name": "Wilson",
  "dob": "19850420",
  "permissible_purpose": "Employment",
  "filter_context": {
    "candidate_jurisdiction": {
      "state": "FL"
    }
  }
}

Response (201) — one record returned, one removed by FCRA 7-year rule:

{
  "id": "<uuid>",
  "check_type": "instant_criminal_regulated",
  "profile_id": "<uuid>",
  "results": [
    {
      "category": "Criminal/traffic",
      "record_id": "<record-id>",
      "person": {
        "first_name": "JAMES",
        "last_name": "WILSON",
        "dob": "19850420"
      },
      "cases": [
        {
          "court_name": "FL Orange Courts",
          "charges": [
            {
              "description": "BATTERY",
              "offense_date": "20220601",
              "record_date": "20220601",
              "dispositions": [
                { "disposition_type": "conviction", "disposition": "ADJUDICATED GUILTY" }
              ],
              "checks": []
            }
          ],
          "checks": []
        }
      ],
      "source": {
        "id": "FL_Orange_View",
        "category": "court",
        "state": "FL"
      },
      "checks": []
    }
  ]
}

Request (Emma Davis):

{
  "first_name": "Emma",
  "last_name": "Davis",
  "dob": "19900712",
  "permissible_purpose": "Employment",
  "filter_context": {
    "candidate_jurisdiction": {
      "state": "FL"
    }
  }
}

Response (201) — all records removed by FCRA, results is empty:

{
  "id": "<uuid>",
  "check_type": "instant_criminal_regulated",
  "profile_id": "<uuid>",
  "results": []
}

PII Validation uses name-based mock selection. Use exact first and last names below (case-insensitive). If the name is not in this list, the API returns a successful response with very low match scores and a result context indicating the name cannot be resolved.

1. Marcus Williams

   • Behavior: Full match.

2. Sarah Martinez

   • Behavior: No match. All attributes have very low correlation.

3. David Thompson

   • Behavior: Strong match on name, email, SSN, and ZIP; weak on DOB/address/phone.

Personal Identity Records (personal_identity_records) uses deterministic Tessera location-search mock data selected by first_name + last_name (case-insensitive).

1. Marcus Williams

   • Behavior: Returns one matched person with IL address history.

2. Sarah Martinez

   • Behavior: Returns one matched person with CA address history.

3. David Thompson

   • Behavior: Returns one matched person with GA address history.

Any other name returns a successful response with an empty people array.

targeted_instant_criminal and criminal_check are available in test mode:

• targeted_instant_criminal uses test-mode location search + natcrim mock selection by name.
• criminal_check completes asynchronously via simulation and sends criminal_check.completed.

Use names such as Marcus Williams, Sarah Martinez, and David Thompson for deterministic mock responses. Unknown names complete successfully with empty results.

regulated_criminal_report is supported in test mode and returns deterministic mock final results by name.

• Marcus Williams: complete report with one conviction record
• Sarah Martinez: complete report with one dismissed record
• David Thompson: complete report with one conviction record

Any other name returns a complete report with an empty results array.

regulated_eviction_check uses name-based mock selection (first_name + last_name, case-insensitive).

1. Patricia Holloway
   • Address: 482 Birch Lane, Springfield, IL 62704
   • Results: One eviction record — Forcible Entry and Detainer filed in Sangamon County Circuit Court.

Any other name returns a successful response with an empty results array.

Request:

{
  "first_name": "Patricia",
  "last_name": "Holloway",
  "dob": "19850314",
  "ssn": "123-45-6789",
  "addresses": [
    {
      "street": "482 Birch Lane",
      "city": "Springfield",
      "state": "IL",
      "zip_code": "62704"
    }
  ]
}

Response (201):

{
  "id": "<uuid>",
  "check_type": "regulated_eviction_check",
  "profile_id": "<uuid>",
  "created_at": "<datetime>",
  "completed_at": "<datetime>",
  "results": [
    {
      "first_name": "Patricia",
      "last_name": "Holloway",
      "middle_name": "Ann",
      "address": "482 Birch Lane",
      "city": "Springfield",
      "state": "IL",
      "zip_code": "62704",
      "zone": "Springfield Metro",
      "subject": {
        "full_name": "Patricia Ann Holloway",
        "dob": null,
        "address": "482 Birch Lane, Springfield, IL 62704",
        "aliases": null,
        "state": "IL",
        "jurisdiction": null,
        "source": null,
        "case_number": "2023-EV-004471",
        "category": "Eviction",
        "status": null,
        "comments": null
      },
      "case": {
        "court": "Sangamon County Circuit Court",
        "case_number": "2023-EV-004471",
        "filing_date": "2023-06-12",
        "notice_type": "Forcible Entry and Detainer",
        "agency_state": null,
        "agency_county": null,
        "dismissal_date": null,
        "default_judgement": false,
        "restored_premises": false,
        "plaintiff": {
          "name": "Riverstone Property Management LLC",
          "phone": "217-555-0182",
          "attorney": "Gregory L. Marsh",
          "attorney_phone": "217-555-0199"
        },
        "judgement": {
          "date": "2023-07-05",
          "amount_cents": 347500,
          "type": "Judgment for Plaintiff",
          "for": "Plaintiff",
          "satisfaction_amount_cents": null,
          "release_date": null
        }
      }
    }
  ],
  "run_notes": []
}

Request:

{
  "first_name": "John",
  "last_name": "Smith",
  "ssn": "123-45-6789",
  "addresses": [
    {
      "street": "123 Main St",
      "city": "Springfield",
      "state": "IL",
      "zip_code": "62701"
    }
  ]
}

Response (201):

{
  "id": "<uuid>",
  "check_type": "regulated_eviction_check",
  "profile_id": "<uuid>",
  "created_at": "<datetime>",
  "completed_at": "<datetime>",
  "results": [],
  "run_notes": []
}

Reverse phone (idv_type: reverse_phone) is synchronous. Submit POST /v1/identity_verifications with country_code and phone. Mock selection uses the normalized US 10-digit number (or country code + national digits for international numbers).

Example request (found):

{
  "idv_type": "reverse_phone",
  "country_code": "1",
  "phone": "202-555-0100"
}

Document Verification uses name-based mock selection (case-insensitive). For test accounts, the API returns a shared cached collection_link and completes results asynchronously via a delayed job; the Socure collection session is not used to determine the final results.

1. Marcus Williams

   • Behavior: Accept.

2. Sarah Martinez

   • Behavior: Reject.

3. David Thompson

   • Behavior: Failed (mock provider error).

1. Use the exact names provided above

• first and last name are the only criteria that determine which mock profile is used. Providing other details such as dob, middle name, phone, email, etc do not effect the results returned.

2. Names are case-insensitive
3. For Checks endpoints, PII combinations not listed above will return empty results with a 200 OK status; for PII Validation, non-matching names return a successful response with all attribute scores 0 and an CT-0523 result context.
4. Test accounts cannot access production data

• Synchronous results: pii_validation returns results immediately in the response.
• Matching rules: Only first_name and last_name determine which mock response is returned.
• Unknown names: Returns a successful response with minimal attribute_match_scores and a result_context entry for CT-0523 ("Name cannot be resolved to the individual").
• Result fields: Results include attribute_match_scores per attribute (0 or 100), an overall_match_score (0, 50, or 100), and a result_context array of objects derived from provider reason codes (each item includes code, title, and category).

Request:

{
  "first_name": "Marcus",
  "last_name": "Williams",
  "idv_type": "pii_validation",
  "email": "test@example.com"
}

Response (201):

{
  "id": "<uuid>",
  "idv_type": "pii_validation",
  "results": {
    "attribute_match_scores": {
      "first_name": 100,
      "last_name": 100,
      "dob": 100,
      "phone": 100,
      "email": 100,
      "address": 100,
      "city": 100,
      "state": 100,
      "zip_code": 100,
      "ssn": 100
    },
    "overall_match_score": 100,
    "result_context": [
      {
        "code": "<CT-code>",
        "title": "<human-readable title>",
        "category": "informational"
      }
    ]
  }
}

Request:

{
  "first_name": "Unknown",
  "last_name": "User",
  "idv_type": "pii_validation"
}

Response (201):

{
  "id": "<uuid>",
  "idv_type": "pii_validation",
  "results": {
    "attribute_match_scores": {
      "first_name": 0,
      "last_name": 0,
      "dob": 0,
      "phone": 0,
      "email": 0,
      "address": 0,
      "city": 0,
      "state": 0,
      "zip_code": 0,
      "ssn": 0
    },
    "overall_match_score": 0,
    "result_context": [
      {
        "code": "CT-0523",
        "title": "Name cannot be resolved to the individual",
        "category": "rejection"
      }
    ]
  }
}

When integrating with the API, it's important to test how your application handles various error conditions. Here are key scenarios you should test:

Test these scenarios to ensure your application handles validation errors gracefully:

• Invalid Date Format

  {
    "first_name": "Marcus",
    "last_name": "Williams",
    "dob": "01-15-1988" // Invalid format, should be YYYYMMDD
  }

• Missing Required Fields

  {
    "first_name": "Marcus"
    // Missing required last_name field
  }

• Invalid Field Format

  {
    "first_name": "Marcus",
    "last_name": "Williams",
    "ssn": "123456789" // Invalid format, should be XXX-XX-XXXX
  }

• Attempting to use products not enabled for your account
• Using expired or invalid access tokens
• Using incorrect client credentials

It's important to understand the difference between error responses and valid empty results:

• Empty Results (200 OK)

  • Using valid PII that doesn't match any test profiles
  • The response will be successful with an empty results array
  {
    "results": []
  }

• Error Response (400 Bad Request)

  • Using invalid PII formats or missing required fields
  • The response will include specific error details
  {
    "errors": [
      {
        "code": "validation_error",
        "title": "Invalid date format",
        "source": {
          "pointer": "/dob"
        }
      }
    ]
  }

For each supported product (instant_criminal, sex_offender_registry, instant_criminal_regulated, and pii_validation):

1. Success Path

   • Use test profile names to get known results
   • Verify all response fields are correctly parsed

2. Empty Results Path

   • Use valid but non-matching names
   • Verify your application handles empty results appropriately

3. Error Path

   • Attempt to use unsupported products
   • Verify error handling for invalid input formats

1. Implement Proper Error Handling

   The API follows the JSON:API error format. All errors will be returned in this standardized format:

   {
     "errors": [
       {
         "code": "validation_error",
         "title": "Invalid date format",
         "source": {
           "pointer": "/dob"
         }
       }
     ]
   }

   Common error scenarios you might encounter:

   // Invalid SSN Format
   {
     "errors": [
       {
         "code": "validation_error",
         "title": "Invalid SSN format",
         "source": {
           "pointer": "/ssn"
         }
       }
     ]
   }
   
   // Missing Required Field
   {
     "errors": [
       {
         "code": "validation_error",
         "title": "Last name is required",
         "source": {
           "pointer": "/last_name"
         }
       }
     ]
   }
   
   // Unauthorized Product Access
   {
     "errors": [
       {
         "code": "validation_error",
         "title": "The product requested is not enabled for this account",
         "source": {
           "pointer": "/check_type"
         }
       }
     ]
   }

   Your error handling should:

   • Parse the errors array to handle multiple errors
   • Use the code field for programmatic error handling
   • Display the title field for user-friendly error messages
   • Use the source.pointer to highlight specific form fields that need correction

2. Validate All Response Fields

   • Check both successful and error responses
   • Verify your application correctly processes all fields

3. Test Edge Cases

   • Very long names
   • test names with suffixes, prefixes, multiple parts of names
   • Special characters in names
   • Different date formats
   • Missing optional fields

Remember that test accounts are designed to help you validate your integration thoroughly before moving to production. Take advantage of these error scenarios to ensure your application handles all cases gracefully.

1. Test Error Handling:

   • Try requests with invalid PII to ensure your application handles empty results appropriately
   • Test unauthorized product access to ensure your error handling works
   • Validate your response parsing for both successful and empty results

2. Validate Response Parsing:

   • Use different test profiles to ensure your code properly handles various response formats
   • Test both criminal records and sex offender registry responses

3. Test All Workflows:

   • Exercise both successful and unsuccessful paths in your integration
   • Verify your handling of empty results (200 OK with no records)
   • Validate your error handling for unauthorized products (401)

County checks are asynchronous. For test accounts, provider completion is simulated via a delayed job. Create a county check as normal; results are populated after a short delay and webhook notifications are delivered using your configured webhook destination.

• Result simulation runs about 60 seconds after check creation
• Mock selection is based on first_name + last_name (case-insensitive)
• Required request fields are still validated in test mode (state, county_fips_code as either 5-digit FIPS or statewide, and profile requirements)
• Unknown names return a completed result with an empty records array

Use the following names to trigger deterministic county-check responses:

1. Michael Doe

   • Scenario: Single misdemeanor conviction
   • Data: Cook County, IL (17031), DUI, disposition FINDING OF GUILTY, fines and probation

2. Jennifer Walsh

   • Scenario: Felony conviction with prison sentence
   • Data: Maricopa County, AZ (04013), aggravated assault, disposition GUILTY, prison time

3. Robert Garcia

   • Scenario: Dismissed charge
   • Data: Harris County, TX (48201), theft of property, disposition DISMISSED

4. Amanda Foster

   • Scenario: Multiple records with mixed outcomes
   • Data: Miami-Dade County, FL (12086), one misdemeanor conviction and one felony pending case

5. Thomas Reed

   • Scenario: Clear result
   • Data: Completed response with no records

6. Nina Patel

   • Scenario: Petty offense (infraction / traffic) with conviction
   • Data: King County, WA (53033), speeding infraction, classification INFRACTION (maps to charge type petty_offense), disposition FINDING OF GUILTY

7. David Okonkwo

   • Scenario: Transferred disposition
   • Data: Fulton County, GA (13121), felony, disposition CASE FORWARDED TO DISTRICT COURT (maps to Transferred)

8. Laura Kim

   • Scenario: Unclassified disposition string
   • Data: Kings County, NY (36047), violation-level trespass, disposition NOLLE PROSEQUI (maps to Unclassified)

9. Elena Ruiz

   • Scenario: Active warrant
   • Data: Bernalillo County, NM (35001), misdemeanor, disposition BENCH WARRANT ISSUED (maps to Warrant)

10. James Cho

• Scenario: Merged / consolidated case
• Data: Multnomah County, OR (41051), consolidated disposition (maps to Merged)

11. Priya Singh

• Scenario: Invalid / vacated judgment
• Data: Franklin County, OH (39049), misdemeanor, disposition with vacated language (maps to Invalid)

12. Marcus Bennett

• Scenario: Cancelled check
• Behavior: About 60 seconds after creation, the check terminates with status: cancelled (visible via GET) instead of completing. Both products deliver a cancellation webhook to your configured destination; the event type differs by product, as described below. Use this profile to test how your integration handles cancelled / not-available results.
• Regulated county checks (/v1/regulated/county_checks): a county_check.not_available webhook is delivered.
• Non-regulated county checks (/v1/county_checks): a county_criminal.not_available webhook is delivered.

When you're ready to move to production:

1. Work with your account representative to determine the appropriate account stage (pilot or live)
2. Update your integration to use production credentials
3. Begin testing with real PII data

• Test accounts are free to use and do not incur charges
• Test data is static and does not change
• Test accounts cannot access production data
• Some test profiles may be updated or added over time
• Contact support if you need additional test scenarios

Driver checks are asynchronous. For test accounts, the provider webhook is simulated via a delayed job. Create a driver check as normal; results are delivered later via webhook and reflected on GET /v1/driver_checks/{id}.

Use the following driver license numbers to trigger specific MVR scenarios:

• DL0001: Clean record
  • License: VALID, no events
• DL0002: Events present
  • License: VALID, includes a speeding violation
• DL0003: Suspended
  • License: SUSPENDED, includes a suspension action

Notes:

• The orderDetails.requestedAs.clientReferenceId is set to your driver check id for correlation.
• For license numbers not listed above, the mock provider returns a NOT_FOUND result (no licenses or events).

Driver License Status Checks (DLSC) are also asynchronous. For test accounts, we simulate Tessera completion via webhook and you will receive a signed event of type:

• driver_license_status.completed

Even though the mock result selection is deterministic, the API still enforces the same request validation rules as live driver checks (e.g. required fields and certain state-specific requirements). At minimum you must send:

• check_type: "driver_license_status"
• first_name, last_name, dob (YYYYMMDD)
• driver_license_number, driver_license_state

Some states require additional fields:

• requester_code is required for CA, PA, UT
• zip_code is required for RI
• ssn is required for WV and TX (if you do not provide it, the system will attempt to derive it; if it cannot, you’ll receive a validation error)

Use these driver_license_number values (with check_type: "driver_license_status") to exercise specific outcomes:

• A1234567: Passenger validity = VALID (non-expired)
• 1234567: Passenger validity = INVALID (suspended)
• 22038374: Passenger validity = INVALID (expired)
• Any other license number: Passenger validity = NOT FOUND

Notes:

• For DLSC, the high-level result is represented in the results.passenger.validity field (see the driver_check_driver_license_status_result schema).
• Mock selection for DLSC is based on check_type + driver_license_number; other PII fields do not change which mock scenario you receive (but may be required for validation depending on driver_license_state).