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 guide 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 the candidate provides their personally identifiable information (PII) and authorizes the background check. By the end of this guide, you’ll know how to:
  1. Authenticate with KarmaCheck.
  2. Order a background check report by sending an onboarding invitation to a candidate.
  3. Get updates about the ordered background check (also known as a case).
  4. Generate a PDF report of the background check.

​
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 invites to candidates get sent to the KarmaCheck sandbox account instead of the email address that you enter for a candidate. If you want to run through the entire workflow in this guide, you’ll need the email invite to enter PII as a candidate. 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 Basic Test Package and note its ID. This package consists of services that support simulated results, enabling you to test the full workflow from start to finish. To learn more about screenings that support simulated results, see Simulated services.

​
Step 2b: Create a case

Call the POST /case/create endpoint to order a background check on a candidate. Replace all placeholder values:
  • AUTHENTICATION_TOKEN: Your authentication token
  • PACKAGE_ID: The ID of the package retrieved in the previous step
  • POSTBACK_URL: The URL for receiving webhook event notifications when the status of the case changes. Remove the postbackUrl field if you don’t want to test webhooks.
  • EMAIL: The candidate’s email address
  • GIVEN_NAME: The candidate’s first name
  • FAMILY_NAME: The candidate’s last name
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",
    "postbackUrl": "POSTBACK_URL",
    "email": "EMAIL",
    "givenName": "GIVEN_NAME",
    "familyName": "FAMILY_NAME"
  }'
Note the ID of the ordered background check in the caseId field returned by the endpoint. You’ll need this value in subsequent API calls.

​
Step 3: Complete candidate onboarding

To begin processing the background check, you need to complete the following steps as a candidate:
  1. Access the email invitation forwarded to you, and click Get Started Now to begin the KarmaCheck candidate onboarding process.
  2. Follow the prompts to provide candidate data and authorize the background check. Enter 111-22-3333 as the candidate’s Social Security number.

​
Step 4: (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": "e123e0d6-12fc-d45b-abc1-dddd5cd2a028",
  "event": "case.statuschange",
  "apiTrackingCode": null,
  "apiTrackingUser": null,
  "username": null,
  "password": null,
  "eventObject": {
    "id": "d1234567-1234-1d23-b12b-5582d748c7c6",
    "crStamp": "2024-06-20T23:07:16.000Z",
    "crUserId": "abc29350-12f3-4d85-9df1-9a73f14d9d17",
    "caseTypeId": "cde61186-4f22-45f4-9e19-429061365bce",
    "caseType": "Background Check",
    "caseStatusId": "d894b8a0-937e-46b1-8799-15bad611844f",
    "caseStatus": "Pending",
    "secondaryCaseStatusId": "8e0c9756-a42f-4a7d-b8e2-412a0f6b9dea",
    "secondaryStatus": "Waiting for Authorization",
    "resultType": "Open",
    "modStamp": "2024-06-20T23:07:16.000Z",
    "candidateId": null,
    "candidateEmail": null,
    "candidateGivenName": null,
    "candidateFamilyName": null,
    "packageId": "d04dece1-1ea5-43fc-2832-231a5d23a08b",
    "packageName": "Basic Test Package",
    "packageCompanyName": null,
    "billingReferenceId": "d04dece1-1ea5-43fc-2832-231a5d23a08b",
    "groupProfileId": "fd0546e4-ac27-4c96-bb22-06ae7e372fd2",
    "resultTypeId": "8c94f0d9-57c9-4c7b-be95-5ec309cff330",
    "caseInvitationId": "d1234a8a-dd12-1e3d-98e6-5ff7eb9f7f0a",
    "invitationStatusId": "3f5e6898-6641-4685-8ee0-1363b7e10c98",
    "invitationStatusName": "pending",
    "invitationGivenName": "Kim",
    "invitationFamilyName": "Smith",
    "companyId": "dde1eafd-232b-39e8-dff4-f1be061eba2c",
    "companyName": "Example Company",
    "companyCommonName": null,
    "companyLogo": null,
    "archived": 0,
    "serviceGroupId": "b3582ef5-72b7-4e48-9973-858464f01141",
    "invitationEmail": "kim.smith@example.com",
    "isMinorCandidate": 0,
    "hasParentalConsent": 0,
    "groupName": "Default",
    "adverseActionId": null,
    "adverseActionStatusName": null,
    "adverseActionStatusId": null,
    "orderedStamp": "2024-06-20T23:07:16.000Z",
    "beginOnboardingStamp": null,
    "completedOnboardingStamp": null,
    "beginProcessingStamp": null,
    "completedInitialProcessingStamp": null,
    "completedLatestProcessingStamp": null
  }
}
Your webhook endpoint should respond with an HTTP status code of 2_xx_ to indicate that the call was processed successfully. If a response status other than a 2_xx_ 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.

​
Step 5: Get report results

After the case is complete, call the GET /case/id/{caseId}/report/pdf/download/url endpoint to get a PDF of the report. Replace CASE_ID with the ID from Step 2b and AUTHENTICATION_TOKEN with your token: 
curl --request GET \
  --url https://api-stage.karmacheck.io/case/id/CASE_ID/report/pdf/download/url \
  --header 'Accept: text/html' \
  --header 'Authorization: Bearer AUTHENTICATION_TOKEN'
A successful request returns the URL at which you can view and download the report. Congratulations! You’ve now run an end-to-end workflow using the KarmaCheck API.