> ## 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.

# Screening Level Document Retrieval

This guide provides information to enable an API integration to retrieve documents that are associated with a specific screening in a case.

> About this guide
>
> The endpoint described here is live and fully supported, but it is not yet published in our public API reference.

### WHAT STAYS THE SAME

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

### WHAT YOU NEED TO KNOW FIRST

> **caseDataId is not the same as caseId**
>
> This is the most common point of confusion, so it is worth stating plainly. \
> \- caseId identifies the overall order for a candidate. \
> \- caseDataId identifies one individual screening or service inside that order.\
> \
> An order containing three health screenings has one caseId and three separate caseDataId values. \
> Documents are attached at the screening level, so you will make one call per caseDataId, not one call per order.

### HOW TO RETRIEVE THE DOCUMENTS

1. Capture the caseDataId for each screening. The caseDataId is returned on the individual service object inside the [casedata.statuschange](https://developer.karmacheck.com/background-check-api/reference/webhooks/events/case-data-status-change) webhook payload (id field) you already receive, either from from the webhook as well as from the [Get Case data by case id API](https://developer.karmacheck.com/api-reference/cases/get-case-data-by-case-id). If you currently store only order level fields, begin persisting caseDataId for each service so document retrieval can run later without re-fetching the case.

2. Request the document list for that screening. Make a GET request to the endpoint below, substituting the caseDataId you captured in step 1. Add the query parameter "returnExcludedDocumentTypes=false", which limits the response to document types eligible for client viewing. Only change this value if we have specifically configured expanded access for your account.\
   `HTTP GET `\
   `https://api-stage.karmacheck.io/document/secure/list/caseData/id/{CASE_DATA_ID}?returnExcludedDocumentTypes=false`\
   `Authorization: Bearer <your_token>`\
   \
   The response returns only the secure documents tied to that one screening.

3. Identify the document you want. Use the fields described in the next section to find the document type you need.

4. Retrieve the file using the Secure Document APIs: [Get secure document download URL](https://developer.karmacheck.com/api-reference/secure-documents/get-secure-document-download-url)

### IDENTIFYING THE RIGHT DOCUMENT

Each item in the returned list includes the following fields, among others:

| Field | What it is | How to use it |
| :- | :- | :- |
| documentTypeId | Stable identifier for the type of document | Use this to determine what a document is |
| fileName | Human readable file name | Use for display to your users |
| fileFormat | Format of the file | Use to handle the file correctly on download |

#### Important Notes

* Do not match on file name
* File names vary by laboratory and by collection site, so name based matching will break 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 the [Get Secure Document Type List](https://developer.karmacheck.com/api-reference/secure-documents/get-secure-document-type-list) endpoint once and cache the result. You do not need to call it on every request.

### RECOMMENDED IMPLEMENTATION PATTERN

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 above once per caseDataId.

4. Filter the returned list down to the documentTypeId values 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.

6. Once this is in place, the documents your team is currently pulling manually will land in your system automatically as orders complete.

### RELATED DOCUMENTATION

Get Secure Document List\
[https://developer.karmacheck.com/api-reference/secure-documents/get-secure-document-list](https://developer.karmacheck.com/api-reference/secure-documents/get-secure-document-list)

Get Secure Document Type List\
[https://developer.karmacheck.com/api-reference/secure-documents/get-secure-document-type-list](https://developer.karmacheck.com/api-reference/secure-documents/get-secure-document-type-list)

Get Secure Document\
[Get secure document download URL](https://developer.karmacheck.com/api-reference/secure-documents/get-secure-document-download-url)