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 walks you through a typical workflow for a document processing order. With this workflow, document processing begins running after you upload documents to the KarmaCheck system and create the order. By the end of this guide, you’ll know how to:
  1. Authenticate with KarmaCheck.
  2. Upload documents and create a secure document record for each one.
  3. Order document processing by providing the candidate’s PII and order data with the secure document record IDs.
  4. Retrieve document processing results and receive status updates.

​
Before you begin

Ensure that you have the following sandbox credentials:
  • An API key
  • A client access token
How you obtain these credentials depends on whether you’re a customer or a partner.

​
Step 1: Authenticate with KarmaCheck

Call POST /auth/api to retrieve an authentication token. Replace API_KEY and CLIENT_ACCESS_TOKEN with your credentials: 
curl -X POST https://api-stage.karmacheck.io/auth/api \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "API_KEY",
    "clientAccessToken": "CLIENT_ACCESS_TOKEN"
  }'
The response body contains your authentication token in the token field. Use this as Bearer AUTHENTICATION_TOKEN in all subsequent requests.

​
Step 2: Order document processing

​
Step 2a: Upload your documents to KarmaCheck

This step references the full Upload documents guide. The key flow is:
  1. Request upload URLs — Call POST /document/secure/upload to generate a secure, time-limited upload URL and fileKey for each document.
  2. Upload documents — Upload each file directly to the returned URL using an HTTP PUT request with the correct Content-Type.
  3. Create secure document records — Call POST /document/secure/create with the fileKey, documentTypeId, and originalFileName.
At this point you will not yet have a caseId. When no order exists yet, omit the accessGrants object from the request.
  1. Note the secureDocumentId returned for each document — you’ll pass these when creating the order.
For request examples, supported MIME types, and error handling, see Upload documents.

​
Step 2b: Get available packages

Call GET /package/min/list to get a list of available packages: 
curl https://api-stage.karmacheck.io/package/min/list \
  -H "Authorization: Bearer AUTHENTICATION_TOKEN"
Find the package named Intelligent Document Processing and note its id.

​
Step 2c: Get services in the package

Call GET /package/id/{packageId}/services to retrieve the services included in the package: 
curl https://api-stage.karmacheck.io/package/id/PACKAGE_ID/services \
  -H "Authorization: Bearer AUTHENTICATION_TOKEN"
Note the serviceId of the Document Processing service (service-intelligent-document-process). You’ll need this when providing order data.

​
Step 2d: Create a document processing order

Call POST /case/create to order document processing. The orderData array must include the minimally required candidate PII types plus one codt-idp entry per document: 
curl -X POST https://api-stage.karmacheck.io/case/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer AUTHENTICATION_TOKEN" \
  -d '{
    "packageId": "PACKAGE_ID",
    "email": "candidate@example.com",
    "givenName": "Jane",
    "familyName": "Smith",
    "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-idp",
        "serviceId": "service-intelligent-document-process",
        "metadata": {
          "documentTypeId": "unclassified",
          "fileName": "testfile1.pdf",
          "secureDocumentId": "SECURE_DOCUMENT_ID_1"
        }
      },
      {
        "caseOrderDataTypeId": "codt-idp",
        "serviceId": "service-intelligent-document-process",
        "metadata": {
          "documentTypeId": "unclassified",
          "fileName": "testfile2.pdf",
          "secureDocumentId": "SECURE_DOCUMENT_ID_2"
        }
      }
    ]
  }'
orderData fields:
FieldDescription
codt-govt-id / govtIdCandidate’s SSN in xxx-xx-xxxx format. Use 111-22-3333 for sandbox testing.
codt-dob / dobCandidate’s date of birth in yyyy-mm-dd format.
codt-current-candidate-addressCandidate’s current address (address1, city, state, postalCode, country).
codt-idp / documentTypeIdDocument type. Always use unclassified for Document Processing.
codt-idp / fileNameThe file name as provided when uploading the document.
codt-idp / secureDocumentIdThe ID returned after creating the secure document record.
postbackUrl is for testing purposes only and supports only case.statuschange events. To configure webhooks for production, contact KarmaCheck to subscribe to webhook events.
A successful response returns the caseId of the order. Note this value — you’ll use it to retrieve results.

​
Step 3: Retrieve document processing results

Call GET /case/id/{caseId}/data/{serviceTypeId} using service-type-document-processing as the serviceTypeId: 
curl https://api-stage.karmacheck.io/case/id/CASE_ID/data/service-type-document-processing \
  -H "Authorization: Bearer AUTHENTICATION_TOKEN"
The response returns a list of case data objects — one per document ordered. Key response fields:
FieldDescription
status / statusDisplayNameCurrent processing status (e.g. complete).
detailsObject.classificationDataDocument classification results including type and confidence score.
detailsObject.valueExtracted data keyed by field name (e.g. issueDate, dateOfBirth).
detailsObject.metadataOCR confidence scores and citation polygons for each extracted field.
Example response: 
{
  "data": [
    {
      "id": "1777e943-7feb-42a9-aa35-2b73f781e4a8",
      "caseId": "8558c68f-5d39-4867-af25-57abeb047c5c",
      "serviceId": "service-intelligent-document-process",
      "serviceName": "Document Processing",
      "statusId": "case-data-status-complete",
      "status": "complete",
      "statusDisplayName": "Complete",
      "detailsObject": {
        "fileName": "US_PASSPORT-example.pdf",
        "documentTypeId": "us-passport",
        "secureDocumentId": "d17e3813-94e1-4717-8d92-df5e935af005",
        "documentExpirationDate": "2032-08-24 00:00:00",
        "classificationData": {
          "id": "classification_usC",
          "type": "us-passport",
          "confidence": 1
        },
        "value": {
          "issueDate": "2022-08-27",
          "dateOfBirth": "1990-09-25",
          "candidateName": "Avery Ellis",
          "expirationDate": "2032-08-24"
        }
      }
    }
  ]
}

​
Step 4: Receive status updates (optional)

If you provided a postbackUrl when creating the order, KarmaCheck sends a POST request to that URL whenever the order status changes. Example 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",
    "caseStatus": "Pending",
    "secondaryStatus": null,
    "resultType": "Open",
    "candidateEmail": "jane.smith@example.com",
    "candidateGivenName": "Jane",
    "candidateFamilyName": "Smith",
    "packageName": "Intelligent Document Processing"
  }
}
Respond with an HTTP 2xx status to confirm receipt. If KarmaCheck does not receive a 2xx response, it will retry the delivery after a delay. See the webhooks overview for more details. If you don’t have a webhook set up, poll GET /case/id/{caseId} to retrieve the current status of the order.