Create case
Orders a background check report and opens a case for tracking. The new case includes references to the package. Depending on the values entered in the request, the case goes through one of two flows:
- Candidate onboarding flow: The new case will have an initial status of Pending and a secondary status of Waiting for Authorization. An invitation is emailed to the candidate, who is required to provide their personally identifiable information (PII) via the invitation email.
- Customer-provided PII flow: All PII for the candidate is provided in the request body. Setting
autoProcessto true initiates a case for the candidate and immediately begins processing.
Restrictions
The following restrictions exist when creating a case. Be sure to adhere to these restrictions when selecting a package or excluding services from the order (via excludeServices).
Criminal and identity screening restrictions
- SSN Trace is required when a County, State, or Federal Criminal Search is being ordered.
- Cannot order Identity Verification and Identity And Liveliness Verification at the same time.
- International Identity Verification cannot be ordered without other international screenings.
- Must choose between US criminal screenings or international criminal screenings.
- Must include International Identity Verification if Canadian Criminal Record Check or International Criminal Record Check is included.
OHS and drug screening restrictions
- Cannot order more than one type of TB test.
- Cannot order DOT and non-DOT drug screenings in the same order.
- Cannot order more than one non-DOT drug screening.
- Only one urine drug screening can be selected for any order.
- Cannot order both vaccine and titer for the same immunization type. This applies for each of the following immunization types: Varicella, Hepatitis A, Hepatitis B, and MMR.
- OSHA Respirator/Fit to Wear Questionnaire is required when Respirator/Mask Fit Testing - Qualitative or Respirator/Mask Fit Testing - Quantitative is being ordered.
- OHS and drug screenings are US-only and cannot be ordered with Canadian or international screenings.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
The ID of the package to order for the case. See Get package list [blocked] to retrieve the list of available packages.
The candidate's email address.
The candidate's first name. Only letters, numbers, hyphens (-), apostrophes ('), commas (,), periods (.), and underscores (_) are allowed.
The candidate's last name. Only letters, numbers, hyphens (-), apostrophes ('), commas (,), periods (.), and underscores (_) are allowed.
If true, the customer is providing all of the information needed to run the check up front; other fields in the payload will be required. If false, the candidate will receive an onboarding invitation to provide the remaining data needed for the check.
The API currently supports only one type of case, which is a background check.
cde61186-4f22-45f4-9e19-429061365bce The candidate's middle name. Only letters, numbers, hyphens (-), apostrophes ('), commas (,), periods (.), and underscores (_) are allowed.
If autoProcess is true and OHS services exist in the package, a phone number in the format +[country_code][phone_number] is required (whether or not any OHS services are being ordered). If autoProcess is false, this field is optional.
"+18005550145"
An external identifier that you can use to help track this case in your own system.
KarmaCheck does not do anything with this field other than include it in webhooks and other API calls, so despite its name, you can put any value.
A common use case is for the value to be the email address of the user in your system who ordered the case.
An external identifier that you can use to help track this case in your own system.
KarmaCheck does not do anything with this field other than include it in webhooks and other API calls, so despite its name, you can put any value.
A common use case is for the value to be the identifier of the case in your system.
A parameter to control how KarmaCheck sends email notifications about the case. By default, KarmaCheck sends an email notifying the candidate when a background check is initiated. Email notifications are standard, as further communication with the candidate might be necessary. To prevent certain emails from being sent, use the following values to disable emails to the candidate or customer:
- 1: Prevents sending invite to the candidate
- 2: Prevents sending updates to the candidate
- 4: Prevents sending notifications to the customer
- 7: Disables all email notifications described above
If the order should not run one or more services that are defined in the package, then list the IDs of each service. Not all services support exclusion; for example, legal authorizations and SSN Trace are needed for other services being ordered.
Indicates how to handle an active case that exists for the same candidate email:
- Use
addto create a new case anyway. - Use
replaceto archive the existing case and create a new case. Without this field, calling the API returns an error if a case already exists.
add, replace, null The ID of the existing case to replace. Required if orderOverride is replace.
If true, acknowledges collection of the candidate's signed disclosures and authorizations. This must be set to true if autoProcess is true.
A list of IDs for each secure document [blocked] to associate with the case.
The candidate's PII and other required data based on the services being ordered. Required if autoProcess is true. Each service has different metadata properties based on the specified caseOrderDataTypeId. See Provide order data [blocked] for additional details.
Options that describe how to run certain screenings for a case. See Order configuration [blocked] for details on all configuration options.
All properties are optional, but a configuration will be set for all applicable screenings on the package regardless of whether those screenings are ordered. Therefore, aside from the contacts object, the default configuration will be used if one is not set.