# Cases API Reference

> Source: https://centric-api-docs.certn.co/#cases

A **Case** is a collection of Checks that are performed on an individual applicant.

These endpoints allow you to order Cases and retrieve their details and results.


## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/public/cases/` |  |
| `GET` | `/api/public/cases/{id}/` |  |
| `POST` | `/api/public/cases/{id}/cancel/` |  |
| `POST` | `/api/public/cases/{id}/generate-report/` |  |
| `GET` | `/api/public/cases/{id}/supplementary-files/` |  |
| `GET` | `/api/public/cases/{id}/supplementary-information/` |  |
| `POST` | `/api/public/cases/order/` |  |
| `POST` | `/api/public/cases/order-package/` |  |
| `GET` | `/api/public/cases/report-files/{id}/` |  |

### GET /api/public/cases/

Returns a list of all your Cases.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `check_type` | query | array | No |  |
| `email_address` | query | string | No |  |
| `group` | query | array | No |  |
| `order_timeframe_after` | query | string | No |  |
| `order_timeframe_before` | query | string | No |  |
| `ordered_by` | query | array | No |  |
| `overall_status` | query | array | No | The overall status of the case. Before the applicant submits the case's application, the case status is the applicant status. After the applicant submits, the case status is derived from its check(s) — status descriptions are listed in order of precedence, and the first status whose conditions are met determines the case status.

- `DRAFT`: Case has been created but not yet ordered. The applicant has not been invited
- `CASE_ORDERED`: Case successfully created
- `INVITE_UNDELIVERABLE`: Invite email not delivered, received bounceback
- `APPLICANT_EXPIRED`: Applicant did not submit the case within the expiry period set by the client
- `APPLICANT_INVITED`: Applicant received the invite email
- `APPLICANT_OPENED`: Applicant opened the invite link, but has not yet started the application
- `APPLICANT_STARTED`: Applicant opened the pending application
- `APPLICANT_SUBMITTED`: Applicant submitted the case's application. Checks should now be in progress
- `IN_DISPUTE`: At least one check for the case has been disputed
- `IN_PROGRESS`: At least one check is in a non-"closed" state (i.e. not `COMPLETE`, `CANCELLED`, or `SUPERSEDED`); requires both applicant and client action; or at least one check has been superseded with none being `COMPLETE`
- `APPLICANT_ACTION_REQUIRED`: At least one check for the case is marked with status `APPLICANT_ACTION_REQUIRED`
- `CLIENT_ACTION_REQUIRED`: At least one check for the case is marked with status `CLIENT_ACTION_REQUIRED`
- `CANCELLED`: All checks for the case have been cancelled by either applicant, client, or Certn
- `COMPLETE`: All checks for the case are in a "closed" (i.e. `COMPLETE`, `CANCELLED`, `SUPERSEDED`) state, with at least one being `COMPLETE`

⚠️ DEPRECATED CASE STATUSES:
The following statuses are applicant and check statuses that will no longer be used as case statuses for new cases, but may still appear on existing cases.
- `APPLICANT_DECLINED`: Applicant declined
- `AWAITING_APPLICANT_SUBMISSION`: Awaiting applicant submission
- `PENDING_FULFILLMENT`: Pending fulfillment
- `SUBMITTED_TO_SOURCE`: Submitted to Source
- `MANUAL_REVIEW_SOURCE`: Manual Review with Source
- `PENDING_QUALITY_REVIEW`: Pending quality review
- `IN_QUALITY_REVIEW`: In quality review
- `SUPERSEDED`: Superseded |
| `page` | query | integer | No | A page number within the paginated result set. |
| `page_size` | query | integer | No | Number of results to return per page. Defaults to 10, maximum 100. |
| `tag` | query | array | No |  |

#### Example Request

```bash
curl -X GET "https://api.sandbox.certn.co/api/public/cases/" \
  -H "Authorization: Api-Key YOUR_API_KEY"
```

### GET /api/public/cases/{id}/

Retrieve the details of an individual Case.

Includes a list of all the Checks associated with the Case, along with their statuses and results.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes |  |

#### Example Request

```bash
curl -X GET "https://api.sandbox.certn.co/api/public/cases/{id}/" \
  -H "Authorization: Api-Key YOUR_API_KEY"
```

### POST /api/public/cases/{id}/cancel/

Cancel a single Case.

This action is only permitted if **all** active checks within the specified case
are in one of the following statuses:
- `AWAITING_APPLICANT_SUBMISSION`
- `PENDING_FULFILLMENT`

If a case contains checks that are further in progress (e.g., `IN_PROGRESS` or `COMPLETE`),
the cancellation request will be rejected.

To cancel multiple cases, make separate requests for each case.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes |  |

#### Example Request

```bash
curl -X POST "https://api.sandbox.certn.co/api/public/cases/{id}/cancel/" \
  -H "Authorization: Api-Key YOUR_API_KEY"
```

### POST /api/public/cases/{id}/generate-report/

Generate a PDF report for a case.

Returns a case report file ID that can be used to retrieve a signed URL to download the report.

The PDF is generated asynchronously, so may not be available immediately. A webhook will be
sent with "event_type": "CASE_REPORT_READY". This indicates the report is ready at the
`/api/public/cases/report-files/{id}/` endpoint.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes |  |

#### Example Request

```bash
curl -X POST "https://api.sandbox.certn.co/api/public/cases/{id}/generate-report/" \
  -H "Authorization: Api-Key YOUR_API_KEY"
```

### GET /api/public/cases/{id}/supplementary-files/

Retrieve the Supplementary Files of an individual Case.

Includes a list of all the Checks associated with the Case, along with their statuses and presigned URL to download supplementary files.
Supplementary Files for a Check are only considered complete when the check is in a closed status (one of: `COMPLETE`, `CANCELLED`, or `SUPERSEDED`).
Please note that the URLs will expire in 3 hours.

Documentation for the Supplementary Information of available checks can be found in the Client Portal under `Settings > Integrations > Documentation > Checks`.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes |  |

#### Example Request

```bash
curl -X GET "https://api.sandbox.certn.co/api/public/cases/{id}/supplementary-files/" \
  -H "Authorization: Api-Key YOUR_API_KEY"
```

### GET /api/public/cases/{id}/supplementary-information/

Retrieve the Supplementary Information of an individual Case.

Includes a list of all the Checks associated with the Case, along with their statuses and supplementary information.
Supplementary Information for a Check is only considered complete when the check is in a closed status (one of: `COMPLETE`, `CANCELLED`, or `SUPERSEDED`).
Supplementary Files can be accessed using the `cases_supplementary_files_retrieve` endpoint.

Documentation for the Supplementary Information of available checks can be found in the Client Portal under `Settings > Integrations > Documentation > Checks`.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes |  |

#### Example Request

```bash
curl -X GET "https://api.sandbox.certn.co/api/public/cases/{id}/supplementary-information/" \
  -H "Authorization: Api-Key YOUR_API_KEY"
```

### POST /api/public/cases/order/

This endpoint allows you to order a new Case. A Case is a collection of checks to be performed on a single Applicant.

Ensure you have familiarized yourself with the concepts under `Settings > Integrations > Documentation > Introduction`.

When ordering a Case, the simplest approach is to _not_ provide any input claims. The applicant will be sent
an email invite to join the Certn platform, and will be asked to provide all of the input data themselves.

Optionally, if you already hold some information about the applicant, you may choose to provide some input
claims at case ordering time. Any claims you provide are used as "prefill" data: the applicant will still
receive an invite, but the input data you provide will be pre-filled into the form for them, saving them time.

Alternatively, you can set `return_invite_link` to `True` to receive the invitation URL in the response,
allowing you to deliver the invite to the applicant yourself. When combined with `send_invite_email=False`,
the Certn-sent email is suppressed but the order is still treated as an invite (not quickscreen).

Finally, you may choose to provide _all_ required input claims about the applicant when ordering the Case. If you do this,
and set both `send_invite_email` to `False` and `return_invite_link` to `False` (or omit it), the case will be ordered
_without_ sending an email or generating an invite link. This is useful if you have already collected all the necessary
input data and required consent from the applicant through some other means and do not wish them to interact with the
Certn platform. This non-invite flow is known as "Quickscreen".

Documentation for the available checks, their required input claims, and their optional check arguments, can be found in the Client Portal under
`Settings > Integrations > Documentation > Checks`.

#### Example Request

```bash
curl -X POST "https://api.sandbox.certn.co/api/public/cases/order/" \
  -H "Authorization: Api-Key YOUR_API_KEY"
```

### POST /api/public/cases/order-package/

This endpoint allows you to order a new Case from a previously configured Package.  You can only order Active packages.
if a package has been deactivated you will receive an error during ordering.

Ensure you have familiarized yourself with the concepts under `Settings > Integrations > Documentation > Introduction`.

When ordering a Case, the simplest approach is to _not_ provide any input claims. The applicant will be sent
an email invite to join the Certn platform, and will be asked to provide all of the input data themselves.

Optionally, if you already hold some information about the applicant, you may choose to provide some input
claims at case ordering time. Any claims you provide are used as "prefill" data: the applicant will still
receive an invite, but the input data you provide will be pre-filled into the form for them, saving them time.

Documentation for the available checks, their required input claims, and their optional check arguments, can be found in the Client Portal under
`Settings > Integrations > Documentation > Checks`.

#### Example Request

```bash
curl -X POST "https://api.sandbox.certn.co/api/public/cases/order-package/" \
  -H "Authorization: Api-Key YOUR_API_KEY"
```

### GET /api/public/cases/report-files/{id}/

Returns a presigned URL to download the report. The report generation process should be initiated using
the `cases_generate_report_post` endpoint. The URL will only be available when the status is `COMPLETE`.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes |  |

#### Example Request

```bash
curl -X GET "https://api.sandbox.certn.co/api/public/cases/report-files/{id}/" \
  -H "Authorization: Api-Key YOUR_API_KEY"
```

---

*See the [interactive documentation](https://centric-api-docs.certn.co/#cases) for more details.*