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

# Retrieve screening-level documents

> How to retrieve the secure documents that are associated with a specific screening in a case.

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.

> [!NOTE]
>
> 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](/background-check-api/overview/api/authentication.md) for the KarmaCheck API.

> [!NOTE]
>
> **`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:

* The payload of the [`casedata.statuschange`](/background-check-api/reference/webhooks/events/case-data-status-change) webhook event that you already receive.
* The response of [Get case data by case ID](/api-reference/cases/get-case-data-by-case-id.md).

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:

```bash theme={null}
curl --request GET \
  --url 'https://api-stage.karmacheck.io/document/secure/list/caseData/id/CASE_DATA_ID?returnExcludedDocumentTypes=false' \
  --header 'Authorization: Bearer AUTHENTICATION_TOKEN'
```

* **`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:

| Field | Description | 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. |

> [!WARNING]
>
> **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](/api-reference/secure-documents/get-secure-document-type-list.md) 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](/api-reference/secure-documents/get-secure-document-download-url.md).

## Recommended implementation pattern

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

* [Get secure document list](/api-reference/secure-documents/get-secure-document-list.md)
* [Get secure document type list](/api-reference/secure-documents/get-secure-document-type-list.md)
* [Get secure document download URL](/api-reference/secure-documents/get-secure-document-download-url.md)