Skip to main content
This guide shows you how to retrieve documents that are associated with a specific screening in a case. By the end of this guide, you’ll know how to:
  1. Capture the caseDataId for each screening on a case.
  2. Request the list of documents for a screening.
  3. Identify the document that you want.
  4. Download the file.
The endpoint described in this guide is live and fully supported, but it isn’t yet published in the public API reference.

​
What stays the same

  • Your existing authentication. You use the same bearer token and header, with no new credentials or scopes.
  • The response format, which matches the case-level secure document list endpoint.
  • The secure document retrieval process that you already use to download files.

​
Before you begin

Ensure that you have an authentication token for the KarmaCheck API.
caseDataId is not the same as caseId. This is the most common point of confusion.
  • caseId identifies the overall order for a candidate.
  • caseDataId identifies one individual screening, or service, inside that order.
An order that contains three health screenings has one caseId and three separate caseDataId values. Documents are attached at the screening level, so you make one call per caseDataId, not one call per order.

​
Step 1: Capture the caseDataId for each screening

The caseDataId is returned in the id field of the individual service object in the following places: If you currently store only order-level fields, begin persisting the caseDataId for each service. This lets you run document retrieval later without re-fetching the case.

​
Step 2: Request the document list for a screening

Make a GET request to the following endpoint. Replace AUTHENTICATION_TOKEN with your token and CASE_DATA_ID with the value that you captured in Step 1:
  • AUTHENTICATION_TOKEN: Your authentication token
  • CASE_DATA_ID: The caseDataId of the screening whose documents you want
  • returnExcludedDocumentTypes: Set to false to limit the response to document types that are eligible for client viewing. Change this value only if KarmaCheck has configured expanded access for your account.
The response contains only the secure documents that are tied to that one screening.

​
Step 3: Identify the document

Each item in the returned list includes the following fields, among others:
Don’t match on file name. File names vary by laboratory and by collection site, so name-based matching breaks unpredictably as you take on volume from different providers. Match on documentTypeId, which is consistent across all providers.
To translate documentTypeId values into readable labels, such as chain of custody, call Get secure document type list once and cache the result. You don’t need to call it on every request.

​
Step 4: Download the file

Retrieve the file using the secure document APIs. See Get secure document download URL. To automate document retrieval, do the following:
  1. Trigger on your existing order completion webhook or polling schedule.
  2. Iterate the services on the completed case and capture each caseDataId.
  3. Call the endpoint in Step 2 once per caseDataId.
  4. Filter the returned list down to the documentTypeId values that your users need to see.
  5. Retrieve each file through the existing secure document process, and store it against the candidate record in your system.
After you implement this pattern, the documents that your team currently pulls manually land in your system automatically as orders complete.

​
Next steps