> For the complete documentation index, see [llms.txt](https://help.bioinsight.illumina.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.bioinsight.illumina.com/connected-insights/resources-and-references/a-introduction/a-case-apis.md).

# Case APIs

Use APIs to perform the following tasks in Connected Insights:

* Get the case ID
* Add or update the disease for a case
* Search cases
* Delete cases
* Upload Case Metadata files

> ❗Do not use the Update Case Information or Patch Case APIs. These APIs can significantly alter case data and are only used by Illumina TechnicalSupport.

## Get Case ID

1. On the API page, navigate to the Cases section.
2. Select **GET /crs/api/v2/cases/{caseId}**.
3. In the Parameters table, update the description for the following required parameters:
   * **caseId** — The ID for the case. To retrieve this ID, select the applicable case in Connected Insights and copy the ID from the URL (for example, `https://{domain}.connectedinsights.illumina.com/interpretation/{caseId}/reports/{reportId}/overview`).
   * **directIdentifiers** — This parameter includes or ignores direct identifiers. Select true or false from the drop-down list. The default value is false.
   * **includeQcOverviewMetrics** — This parameter includes or ignores the QC metrics for the case. Select true or false from the drop-down list. The default value is false.
   * **Accept-Language** — The applicable language for the data.
4. Select **Execute**.

## Add or Update the Disease for a Case

1. On the API page, navigate to the Cases section.
2. Select **PUT /crs/api/v1/cases/{caseId}/diseases**.

   > ❗ This API puts the case in a processing state. Then, it moves to the Ready for Interpretation state. Navigate to the Case List page to check the status of the case.
3. In the Parameters table, update the description for the following parameters:
   * **caseId** — The ID for the case. To retrieve this ID, select the applicable case in Connected Insights and copy the ID from the URL (for example, `https://{domain}.connectedinsights.illumina.com/interpretation/{caseId}/reports/{reportId}/overview`).
4. For the Request body, enter the disease name you want to add or update. Refer to the following example:

```json
{
  "externalid": "255032005",
  "ontologytype": "SNOMEDCT",
  "name": "Medullary thyroid carcinoma"
}
```

5. Select **Execute**.

## Delete Cases

Use an API to delete cases as follows.

1. On the API page, navigate to the Cases section.
2. Select **DELETE /crs/api/v1/cases/{id}**
3. In the Parameters table, enter the applicable case ID.
4. \[Optional] Enter the applicable language in the Description field.
5. Select **Execute**.

## Search Case

Use an API to search for cases based on one or multiple parameters. If you are using multiple parameters, the search is completed with the AND condition for each parameter.

1. On the API page, navigate to the Cases section.
2. Select **GET /crs/api/v1/cases/search**.
3. In the Parameters table, update the description for the following applicable parameters:
   * **status** — The case status. Enter the applicable status in the field. The available statuses are listed in the Description column.
   * **isExactMatch** — This parameter is used with displayId and determines if the result is an exact match. Select true or false from the drop-down list. The default value is false.
   * **displayId** — The displayed case ID ( for example, ILM-ABC-234 ). This parameter is an exact search when isExactMatch is set to true.
   * **id** — The caseId ( for example, dc25cd92-78e0-11e8-adc0-fa7ae01bbebc ). This parameter is also used to search for a partial ID.For example, if you search for 11e8, then dc25cd92-78e0-11e8-adc0-fa7ae01bbebc displays in the results.
   * **externalSampleId** — The external sample ID for a case ( for example, ILM-ABC-234 ). This parameter is also used to search for a partial ID. For example, if you search ABC or 234, then ILM-ABC-234 displays in the results.
   * **analysisId** — The specific or custom analysisId.
   * **tags** — The tags associated with the case. Select Add string item to add a tag. This parameter is also used to search for partial tags. For example, if you search for onc, then both oncogenic and oncology display in the results.
   * **diseaseName** — The disease name associated with the case.
   * **creationDateBefore** — The date before the data is created. This date is in the yyyy-MM-dd'T'HH:flag\_mm:ss'Z' format ( for example,2021-01-30T08:30:00Z ).
   * **creationDateAfter** — The date after the data is created. This date is in the yyyy-MM-dd'T'HH:flag\_mm:ss'Z' format ( for example, 2021-01-30T08:30:00Z ).
   * **pageNumber** — The specific page number of the API response.
   * **pageSize** — The size of each page in the API response.
   * **orderBy** — This parameter is used by id, displayId, and status to sort results. Results are sorted in ascending or descending order.Enter ASC to sort in ascending order, and enter DESC for descending order.
   * **Accept-Language** — The applicable language for the data.
4. Select **Execute**.

## Upload Metadata files via an API

Use an API to upload a Case Metadata file as follows.

1. On the API page, navigate to the Cases section.
2. Select **POST /crs/api/v2/custom-case-data/files**
3. In the Parameters table, select **Add string item**, then **Choose File** to select the Case Metadata file from local storage.
4. \[Optional] To upload multiple files, select **Add strong item** and **Choose File** again. Upload up to 5 files. Accepted file types: CSV. Each file should not exceed 10MB in size, with a combined files limit of 50MB.
5. \[Optional] Enter the applicable language in the Description field.
6. Select **Execute**.

   > ❗ For more details about Case Metadata files including error messages, downloading, editing, uploading, and tracking upload progress, see [Custom Case Data Upload](/connected-insights/configure/configuration/du-introduction/du-custom-case-dataupload.md).

## Add Biomarkers

Use an API to add a biomarker as follows:

1. On the API page, navigate to **Biomarkers** section
2. Select **POST /crs/api/v1/cases/{caseId}/biomarkers**
3. In the parameters section, add **caseId**. To retrieve this ID, select the applicable case in Connected Insights and copy the ID from the URL: `https://{domain}.connectedinsights.illumina.com/interpretation/{caseId}/reports/{reportId}/overview`
4. In the Request body, delete `additionalProp1`, `additionalProp2`, and `additionalProp3`. Set `type` and `category` to `gene`, `name` to the gene symbol, and `data.status` to the result. To record which assay produced the result, set `data.source`. Refer to the following example:

```json
{
  "biomarkerData": [
    {
      "type": "gene",
      "details": {
        "category": "gene",
        "name": "ERBB2",
        "data": {
          "status": "Positive",
          "source": "IHC"
        }
      }
    }
  ]
}
```

Accepted status values are `Positive`, `Negative`, `Equivocal`, and `Cannot be determined`. 5. Select **Execute**.

> Multiple results for the same gene can be added when each result has a different source. For example, an ERBB2 result from IHC and an ERBB2 result from FISH are both kept. A result is identified by the gene symbol, status, and source. Sending the same gene, status, and source twice is rejected.

## Add a tag to a case

Use an API to add a tag to a case as follows:

1. On the API page, navigate to **Cases** section
2. Select **POST /crs/api/v1/cases/{caseId}/tags**
3. In the parameters section, add **caseId**. To retrieve this ID, select the applicable case in Connected Insights and copy the ID from the URL: `https://{domain}.connectedinsights.illumina.com/interpretation/{caseId}/reports/{reportId}/overview`
4. In the request body, add the tag you want to add to the case. For example:\\

```angular2html
{
  "tags": [
    "MyNewTag"
  ]
}
```

5. Select **Execute**

## Search Tags

Use an API to search for tags as follows:

1. On the API page, navigate to **Tags** section
2. Select **GET /crs/api/v1/tags/search**
3. In the parameters section, add the following applicable parameters:
   * **tag** — The tag associated with the case. This parameter is also used to search for partial tags. For example, if you search onc, then both oncogenic and oncology display in the results.
4. Select **Execute**

## Add Participant to a Case

Use an API to add a participant to a case as follows:

1. On the API page, navigate to **Cases** section
2. Select **POST /crs/api/v1/cases/{caseId}/participants**
3. In the parameters section, add **caseId**. To retrieve this ID, select the applicable case in Connected Insights and copy the ID from the URL: `https://{domain}.connectedinsights.illumina.com/interpretation/{caseId}/reports/{reportId}/overview`
4. In the request body, add the participant information you want to add to the case. For example:\\

```angular2html
{
  "participantIds": [
    "aa9c9064-0fb5-39ab-b508-1234abcd5678"
  ]
}
```

5. Select **Execute**


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.bioinsight.illumina.com/connected-insights/resources-and-references/a-introduction/a-case-apis.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.