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.

KarmaCheck supports the ability for providing candidate disclosure and authorization document records by way of a secure file upload. These uploaded files can be associated with a case, either an existing case or a case that you’re going to create. This guide assumes that you already obtained API access to a group in KarmaCheck. The steps to securely upload, store, and make appropriate associations with a case are as follows:
  1. Request a secure URL for each document to store.
  2. Upload the files to KarmaCheck using the returned URLs from step 1.
  3. Create the proper association for the successfully uploaded files in step 2.

​
Step 1: Request document upload URLs

To upload any documents and associate them with a case, you need to first generate a URL for each document. Replace AUTHENTICATION_TOKEN with your token and adjust the body values:
  • mimeType: The MIME type of the document you will upload. If you’re uploading a non-PDF file, replace application/pdf with the correct MIME type. To retrieve a list of supported MIME types, send a GET request to GET /document/secure/mimetypes.
  • documentTypeId: The type of document you will upload. Candidate disclosures and authorizations are the only supported document type to associate with a case.
If uploading more than one document, add an additional object containing mimeType and documentTypeId to the files array for each additional document. 
curl --request POST \
  --url https://api-stage.karmacheck.io/document/secure/upload \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer AUTHENTICATION_TOKEN' \
  --data '{
    "files": [
      {
        "mimeType": "application/pdf",
        "documentTypeId": "candidate-disclosures-and-authorizations"
      }
    ]
  }'
A successful request returns the following:
  • url: A URL for each document that you’ll upload in the next step. Note that each returned URL expires after 1 hour.
  • fileKey: A unique key for referencing your document in KarmaCheck. You’ll need this key in Step 3.

​
Step 2: Upload documents

You can now upload your documents directly to KarmaCheck using the URLs provided in the response from Step 1: 
curl --request PUT 'UPLOAD_URL' \
--header 'Content-Type: MIME_TYPE' \
--data 'PATH_TO_DOCUMENT'
Replace the following in your request:
  • UPLOAD_URL: The URL returned in step 1
  • MIME_TYPE: The MIME type of the document you’re uploading. This should match the MIME type you entered in Step 1.
  • PATH_TO_DOCUMENT: The path to the document you’re uploading
Note the following:
  • If you’re uploading more than one document, make sure to keep track of which URL you’re uploading each document to.
  • If you attempt to use an expired URL, the server responds with a 403 HTTP status code. If you have additional issues with uploading your documents, see Troubleshooting in the Amazon S3 documentation.

​
Step 3: Create secure document records

Finally, create a secure document record for each document you just uploaded. If you don’t complete this step, the documents uploaded in Step 2 are unavailable for use in KarmaCheck, as they are not associated with any case. Replace AUTHENTICATION_TOKEN with your token and adjust the body values:
  • fileKey: The key returned in Step 1. If uploading more than one document, enter the key that corresponds with the URL to which you uploaded the document.
  • documentTypeId: The type of document uploaded — candidate-disclosures-and-authorizations
  • originalFileName: The file name for the uploaded document, including the file extension.
  • caseId: The ID of an existing case to associate the document with. If the case hasn’t been created yet, remove the accessGrants object from the request body.
curl --request POST \
  --url https://api-stage.karmacheck.io/document/secure/create \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer AUTHENTICATION_TOKEN' \
  --data '{
    "list": [
      {
        "fileKey": "1daa3c43-ea4e-4d66-9330-0cbd197feee6",
        "documentTypeId": "candidate-disclosures-and-authorizations",
        "originalFileName": "example_document.pdf"
      }
    ],
    "accessGrants": {
      "caseId": "22e88848-17d1-4946-bbac-18d44f381ca7"
    }
  }'
A successful request returns a secureDocumentId for each document. If the documents are to be associated with a new case, you can send the newly created secure document IDs from this API call to the call for creating a case. Doing this will associate these documents with the case and the candidate.