Test OHS and drug screenings in the sandbox

The KarmaCheck sandbox simulator gives you two ways to exercise occupational health screening (OHS) and drug screening orders: simulated results and simulated authorization packets. Each case follows the path that you select with a single order data value, so you decide which part of your integration you want to test. This page explains how the two paths work, how to select each one, and how to test both with the same package.

Choose a testing path

Testing path	`ohsAutoScheduling` value	What the sandbox does	Use it to test
Simulated results	`false`	Skips authorization packet processing and simulates results for the screenings on the case.	How your integration handles completed screenings, result statuses, and webhooks.
Simulated authorization packets	`true`	Generates and sends an authorization packet, and then waits for the candidate to visit the lab.	How your integration handles the authorization packet events for a case.

You select the path with the codt-ohs-auto-scheduling order data type when you call POST /case/create.

These paths describe how the sandbox simulator behaves in the staging environment. Each case follows one path, so use separate cases to test each one.

How the default path is selected

When smart scheduling is enabled for your account, ohsAutoScheduling defaults to true for any case where your create case request doesn’t include a value. KarmaCheck enables smart scheduling when you want to test authorization packet generation and delivery. Because of this default, every OHS or drug order that omits the value follows the authorization packet path. To simulate results instead, include codt-ohs-auto-scheduling with a value of false on the order.

Include codt-ohs-auto-scheduling explicitly on every OHS and drug order that you create in the sandbox. This way, each test case follows the path that you intend, no matter how your account is configured.

Simulate results

To simulate results, set ohsAutoScheduling to false in the order data:

{
  "caseOrderDataTypeId": "codt-ohs-auto-scheduling",
  "metadata": {
    "ohsAutoScheduling": false
  }
}

The sandbox skips authorization packet processing and simulates results for the screenings on the case. The result depends on the candidate’s government ID:

111-22-3333: Returns a favorable result. For example, drug screenings return clear.
333-22-1111: Returns a result that requires review (consider).

See Simulated services for the complete list of services and the test data that each one supports.

Simulate authorization packets

To simulate authorization packets, set ohsAutoScheduling to true in the order data:

{
  "caseOrderDataTypeId": "codt-ohs-auto-scheduling",
  "metadata": {
    "ohsAutoScheduling": true
  }
}

The sandbox generates and sends an authorization packet, and then waits for the candidate to visit the lab. As the case progresses, the OHS services on the case move through the pending-status-clinic-auth-created and pending-status-clinic-auth-sent pending statuses. See Case data statuses for details. Results aren’t simulated for a case that follows this path, so use the simulated results path when you want to test completed screenings.

Create a case for either path

The following request orders a package that contains OHS and drug screenings using the customer-provided PII flow. To switch between the two paths, change the value of ohsAutoScheduling.

Every service that is configured on the package is ordered unless you exclude it. Although excludeServices is optional, you need it to order only the services that you want to test. For example, if your package includes five drug screenings and you want to order one of them, list the IDs of the other four in excludeServices.

Replace the placeholder values:

AUTHENTICATION_TOKEN: Your authentication token
PACKAGE_ID: The ID of a package that contains OHS or drug screenings
EMAIL: The candidate’s email address. See Test each path for tips on choosing addresses.
PHONE: The candidate’s phone number in the format shown, for example +15555550100
GIVEN_NAME: The candidate’s first name
FAMILY_NAME: The candidate’s last name

curl --request POST \
  --url https://api-stage.karmacheck.io/case/create \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer AUTHENTICATION_TOKEN' \
  --data '{
    "packageId": "PACKAGE_ID",
    "email": "EMAIL",
    "phone": "PHONE",
    "givenName": "GIVEN_NAME",
    "familyName": "FAMILY_NAME",
    "autoProcess": true,
    "allowPartialOrderData": false,
    "candidateConsentProvided": true,
    "orderData": [
      {
        "caseOrderDataTypeId": "codt-ohs-auto-scheduling",
        "metadata": { "ohsAutoScheduling": false }
      },
      {
        "caseOrderDataTypeId": "codt-current-candidate-address",
        "metadata": {
          "address1": "100 Main St",
          "address2": "Unit 2",
          "city": "New York",
          "state": "NY",
          "postalCode": "10016",
          "country": "US"
        }
      },
      {
        "caseOrderDataTypeId": "codt-ohs-scheduling-address",
        "metadata": {
          "address1": "100 Main St",
          "address2": "Unit 2",
          "city": "New York",
          "state": "NY",
          "postalCode": "10016",
          "country": "US"
        }
      },
      {
        "caseOrderDataTypeId": "codt-drug-reason-for-test",
        "metadata": { "reasonForTest": "pre-employment" }
      },
      {
        "caseOrderDataTypeId": "codt-dob",
        "metadata": { "dob": "2000-01-01" }
      },
      {
        "caseOrderDataTypeId": "codt-govt-id",
        "metadata": { "govtId": "111-22-3333" }
      }
    ],
    "excludeServices": [
      "service-ohs-tb-skintest",
      "service-titer-mmr",
      "service-vacc-influenza",
      "service-ohs-vision-ishihara"
    ]
  }'

Note the following about the order data in this request:

codt-ohs-auto-scheduling selects the testing path. This example simulates results. Change false to true to simulate authorization packets.
codt-ohs-scheduling-address is the address used to find nearby clinics. It’s required for OHS and drug screenings. See Health screening scheduling address for details.
codt-drug-reason-for-test is optional. See Drug reason for test.
excludeServices lists the ID of each service that you want to skip. Use it to skip services that the package would normally run automatically. The services in this example are only samples, so replace them with the IDs of the services in your own package. Excluding the services that you aren’t testing keeps the case focused on the screenings that you care about.
- Find service IDs in the Services reference. The IDs also appear as serviceId in the response of GET /package/id/{packageId}/services.
- Not every service can be excluded. Legal authorizations and SSN Trace are required by other services in the order. For example, SSN Trace is required when you order a County, State, or Federal Criminal Search. Check the restrictions in the Create case description before you exclude anything.
Your package may require additional order data for the services that it contains. See Provide order data for all supported types.

Test each path

Create one case for each path so that you can compare the two side by side:

Create a case with ohsAutoScheduling set to false, and use SSN 111-22-3333 to simulate favorable results.
Create a second case with ohsAutoScheduling set to true to simulate authorization packet generation and delivery.
Use a different candidate email address for each case. If an email address already belongs to a case in your group, the request returns a 409 Conflict response unless you include orderOverride. See Status codes and errors for details.

If your email provider supports plus aliases, you can use addresses such as qa+results@company.com and qa+authpacket@company.com for the two cases. Verifying qa@company.com also permits its plus aliases. See Verify sandbox email addresses for details.

Next steps

Review Testing considerations for test SSNs and the full list of simulated services.
See Provide order data for every order data type that you can send when you create a case.
Learn how services progress through their statuses in Service lifecycle.

Overview

Sandbox Testing

Guides

API Overview

API Reference

Webhooks

Enumerations

Test OHS and drug screenings in the sandbox

Choose a testing path

How the default path is selected

Simulate results

Simulate authorization packets

Create a case for either path

Test each path

Next steps

​Choose a testing path

​How the default path is selected

​Simulate results

​Simulate authorization packets

​Create a case for either path

​Test each path

​Next steps

Choose a testing path

How the default path is selected

Simulate results

Simulate authorization packets

Create a case for either path

Test each path

Next steps