Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.karmacheck.com/llms.txt

Use this file to discover all available pages before exploring further.

This tutorial will help you get started with the KarmaCheck API by walking you through a typical workflow for a background check. With this workflow, a background check on a candidate begins running after you order the background check. By the end of this tutorial, you’ll know how to:
  1. Authenticate with KarmaCheck.
  2. Order a background check report by providing a candidate’s personally identifiable information (PII).
  3. Get updates about the ordered background check (also known as a case).

​
Before you begin

  • Ensure that you have the following sandbox credentials to gain access to the KarmaCheck API:
    • An API key
    • A client access token
    The method for obtaining these credentials varies depending on whether you’re a customer or a partner.
  • Email notifications to candidates get sent to the KarmaCheck sandbox account instead of the email address that you enter for a candidate. If you want to receive these emails, contact KarmaCheck to set up email forwarding.

​
Step 1: Authenticate with KarmaCheck

Call the authentication endpoint to retrieve an authentication token. Replace API_KEY and CLIENT_ACCESS_TOKEN with your credentials: 
curl --request POST \
  --url https://api-stage.karmacheck.io/auth/api \
  --header 'Content-Type: application/json' \
  --data '{
    "apiKey": "API_KEY",
    "clientAccessToken": "CLIENT_ACCESS_TOKEN"
  }'
The response body displays your authentication token in the token field.

​
Step 2: Order a report

With an authentication token, you can now make API calls to order a background check for a specific group.

​
Step 2a: Get available packages

Call the GET /package/min/list endpoint to get a list of packages available for background checks: 
curl --request GET \
  --url https://api-stage.karmacheck.io/package/min/list \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer AUTHENTICATION_TOKEN'
The response body displays a list of packages with the unique ID of each package in an id field. Find the package with the name Advanced Test Package and note its ID.

​
Step 2b: Get services in the package

Call the GET /package/id/{packageId}/services endpoint to retrieve the list of services included in the Advanced Test Package: 
curl --request GET \
  --url https://api-stage.karmacheck.io/package/id/PACKAGE_ID/services \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer AUTHENTICATION_TOKEN'
A successful request returns a list of services with the unique ID of each service in a serviceId field. Note the IDs of the services named Federal Criminal Search and Employment Verification — you’ll need these when ordering the background check.

​
Step 2c: Find jurisdictions

The Advanced Test Package includes the Federal Criminal Search (District) service, so you need to find the correct federal district jurisdictions. Call the POST /jurisdiction/find/all endpoint: 
curl --request POST \
  --url https://api-stage.karmacheck.io/jurisdiction/find/all \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer AUTHENTICATION_TOKEN' \
  --data '{
    "counties": [
      { "city": "Brooklyn", "county": "Kings", "state": "NY" },
      { "city": "Manhattan", "county": "New York", "state": "NY" }
    ]
  }'
A successful request returns a list of jurisdictions. Note the names of jurisdictions with federal-district as the jurisdiction type — you’ll need these when ordering the background check.

​
Step 2d: Create a case

Call the POST /case/create endpoint to order a background check. The request below includes the minimally required data plus jurisdiction and employment order data for the Advanced Test Package:
The postbackUrl property is for testing purposes only and supports only case status change events. To configure webhooks for your production environment, or to test all available webhook events, you must contact KarmaCheck to subscribe to webhook events.
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",
    "givenName": "GIVEN_NAME",
    "familyName": "FAMILY_NAME",
    "postbackUrl": "POSTBACK_URL",
    "autoProcess": true,
    "candidateConsentProvided": true,
    "orderData": [
      {
        "caseOrderDataTypeId": "codt-govt-id",
        "metadata": { "govtId": "111-22-3333" }
      },
      {
        "caseOrderDataTypeId": "codt-dob",
        "metadata": { "dob": "1985-05-15" }
      },
      {
        "caseOrderDataTypeId": "codt-current-candidate-address",
        "metadata": {
          "address1": "1 Main Street",
          "address2": "Unit 179",
          "city": "Brooklyn",
          "state": "NY",
          "postalCode": "11201",
          "country": "US"
        }
      },
      {
        "caseOrderDataTypeId": "codt-address",
        "metadata": { "city": "Brooklyn", "county": "Kings", "state": "NY", "autoProcessJurisdictions": false }
      },
      {
        "caseOrderDataTypeId": "codt-address",
        "metadata": { "city": "Manhattan", "county": "New York", "state": "NY", "autoProcessJurisdictions": false }
      },
      {
        "caseOrderDataTypeId": "codt-jurisdiction-fed-district",
        "serviceId": "FEDERAL_CRIMINAL_SEARCH_ID",
        "metadata": { "district": "New York Eastern District Court" }
      },
      {
        "caseOrderDataTypeId": "codt-jurisdiction-fed-district",
        "serviceId": "FEDERAL_CRIMINAL_SEARCH_ID",
        "metadata": { "district": "New York Southern District Court" }
      },
      {
        "caseOrderDataTypeId": "codt-employment",
        "serviceId": "EMPLOYMENT_VERIFICATION_ID",
        "metadata": {
          "employer": "Example Organization",
          "position": "Nurse",
          "city": "Brooklyn",
          "state": "NY",
          "country": "US",
          "monthBegin": "November",
          "yearBegin": "2004",
          "current": false,
          "monthEnd": "November",
          "yearEnd": "2018",
          "contact": { "website": "www.example.com", "email": "hr@example.com", "phone": "800-555-0167" },
          "okToContact": true
        }
      },
      {
        "caseOrderDataTypeId": "codt-employment",
        "serviceId": "EMPLOYMENT_VERIFICATION_ID",
        "metadata": {
          "employer": "Example Organization 2",
          "position": "Nurse",
          "city": "Manhattan",
          "state": "NY",
          "country": "US",
          "monthBegin": "November",
          "yearBegin": "2018",
          "current": true,
          "contact": { "website": "www.example.com", "email": "admin@example.com", "phone": "800-555-0172" },
          "okToContact": true
        }
      }
    ]
  }'
Replace FEDERAL_CRIMINAL_SEARCH_ID and EMPLOYMENT_VERIFICATION_ID with the service IDs retrieved in Step 2b. A successful request returns the ID of the ordered background check in the caseId field. Congratulations! You’ve initiated a background check using the KarmaCheck API. For a full explanation of the orderData array and all supported types, see Provide order data.

​
Step 3: (Optional) Receive status updates

If you provided a webhook URL to receive case status updates, a POST request is sent to the webhook endpoint any time the status of the case changes. The following is an example of a webhook payload: 
{
  "messageId": "e123e0d8-22dd-d45b-abc1-dddd5cd2a028",
  "event": "case.statuschange",
  "apiTrackingCode": null,
  "apiTrackingUser": null,
  "username": null,
  "password": null,
  "eventObject": {
    "id": "12345678-2e75-4ba7-abcde-06741f65df3e",
    "crStamp": "2024-06-20T23:16:14.000Z",
    "caseStatus": "Pending",
    "secondaryCaseStatusId": null,
    "secondaryStatus": null,
    "resultType": "Open",
    "candidateEmail": "john.smith@example.com",
    "candidateGivenName": "John",
    "candidateFamilyName": "Smith",
    "packageName": "Advanced Test Package",
    "groupName": "Default",
    "orderedStamp": "2024-06-20T23:16:14.000Z",
    "completedOnboardingStamp": "2024-06-20T23:16:15.000Z",
    "beginProcessingStamp": "2024-06-20T23:16:16.000Z"
  }
}
Your webhook endpoint should respond with an HTTP status code of 2xx to indicate that the call was processed successfully. If a response status other than a 2xx is received, KarmaCheck will attempt to resend the webhook after a delay. See the webhooks overview for more details on webhooks and how to handle events. If you don’t have your webhook set up, send a GET request to the GET /case/id/{caseId} endpoint to retrieve the details of your case.