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.

The KarmaCheck API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, a 2xx status code indicates success, a 4xx status code indicates an error based on the information provided, and a 5xx status code indicates an error with KarmaCheck servers.

​
HTTP status codes

CodeTitleDescription
200OKThe request was successful.
400Bad RequestThe request couldn’t be processed. This might be due to issues in the request body.
403ForbiddenThe user doesn’t have permissions to access the requested resource.
404Not FoundThe resource path doesn’t exist. This might be due to an invalid resource ID that was provided.
409ConflictThe request conflicts with the resource’s current state.
422Unprocessable EntityThe request contains data that fails validation rules or business rules.
500Internal Server ErrorA problem occurred on KarmaCheck’s end.

​
Errors

Errors are returned as JSON-based messages. Most 4xx responses include an error message that briefly explains the error, which can be handled programmatically. The following sections provide examples of different types of error responses.

​
400 Bad Request

Your request body has one of the following issues:
  • A required field is missing.
  • A field contains the wrong format or data type.
For example, you want to find relevant jurisdictions for a county, but didn’t provide the state: 
{
  "message": [
    "counties.0.state must be a string"
  ],
  "error": "Bad Request",
  "statusCode": 400
}

​
403 Forbidden

You don’t have permission to access a specific resource: 
{
  "message": "You do not have access to documents for case e074241e-36e8-444b-bf55-bb4dad6d3f3d",
  "error": "Forbidden",
  "statusCode": 403
}

​
404 Not Found

The resource (for example, a case) associated with the ID provided in the path parameter doesn’t exist: 
Invalid case

​
409 Conflict

A request to create a case includes an email address associated with a candidate who is already the subject of an existing case within the same group: 
{
  "httpStatus": "CONFLICT",
  "cases": [
    {
      "existingCaseId": "afe52932-7c0d-4233-93f9-ce6ee3d0bede",
      "existingCaseCrStamp": "2024-05-30T00:02:12.000+00:00",
      "existingCasePackageId": "d04defe1-1ea5-43fc-1832-231a5d23a08b",
      "existingCasePackageName": "Basic Check",
      "existingCaseStatusId": "d894b8a0-937e-46b1-8799-15bad611844f",
      "existingCaseStatus": "Pending",
      "modStamp": "2024-05-31T00:02:17.000+00:00"
    }
  ]
}
To create a new case associated with the same candidate, resend the request with orderOverride in the request body. Depending on the value provided (add or replace), a successful request results in one of the following:
  • The new case is created in addition to the existing case.
  • The existing case is archived, and the new case is created.

​
422 Unprocessable Entity

The request contains data that fails validation. For example, a request to create a case using the PII entry flow is missing required candidate information: 
Requested package requires candidate phone number
The request doesn’t align with business logic. For example, you can’t resend the invitation associated with a case if a candidate has already begun the onboarding process: 
{
  "message": "Case has already started",
  "error": "Unprocessable Entity",
  "statusCode": 422
}