1 of 1

Advanced API Implementations

This page provides several code examples demonstrating how to use the platform for common scenarios. While you don't need to follow or implement every example, they can serve as useful starting points

Getting Started

Before exploring the examples, make sure to log in to the platform. More information on this can be found in the API Beginner Guide.

After authentication, you will receive a token, which remains valid for a certain period of time.

For more information on advanced features, parameters, and additional examples, be sure to check out our Swagger documentation by going to https://<hostname>.emg.illumina.com/api/apidoc/swagger#/

Use cases

Automating Case Management: Creation and Status Check
Assigning Participants
Retrieving Case Info, Tags, Variants, and Changing Status

Automating Case Management: Creation and Status Check

This example demonstrates how to automate case management, including case creation, checking if the case status is "finalized," and generating a report.

Step 1: Create the Payload

First, construct a JSON payload with all the necessary case data.

Refer to the API documentation for more details on required fields, or go to https://<hostname>.emg.illumina.com/api/apidoc/swagger#/Cases/post__api_cases_v2_cases

Step 2: Send a POST Request

To create a case, send a POST request using the payload. Remember to replace any values enclosed in < > with your specific data.

Step 3: Retrieve Case Status and Name

After creating the case, you can retrieve the status and name from the API response.

Assigning Participants

Step 1: Retrieve Participant IDs by Email

Before assigning participants to cases, you can retrieve their IDs by searching for their email addresses.

Step 2: Assign Participants to the Case

Finally, assign participants to the case using their IDs.

Retrieving Case Info, Tags, Variants, and Changing Status

This example demonstrates how to retrieve tagged variants and the associated variant information from a case, and change the case status.

Step 1: Obtain the Case Name

If you don't have the case name yet, follow the steps outlined in Steps 1 and 2 of to create a case and retrieve the case name.

Step 2: Retrieve case info

Use this API route to get some basic information on a case: creation time, creator, last updated time, case name, case status.

Step 3: Send a GET Request to Retrieve Case Tags

To pull the case data, including tagged variants, send a GET request.

For more information, check out the Swagger documentation at https://<hostname>.emg.illumina.com/api/apidoc/swagger#/Candidates/get__api_candidates_%7Bcase_name%7D

Step 4: Update Case Status to a Custom Status

After retrieving the case, update the status to "custom_status_1".

Managing Finalized Cases and Generating Reports

Step 1: Retrieve Cases Finalized in the Last 24 Hours

Retrieve cases that were finalized within the last 24 hours.

Another option for retrieving a finalized case is to use . This option allows to receive notifications on case status change instead of checking via API.

Step 2: Generate a Report

Reports can only be generated for finalized cases. To generate a report, send the following GET request:

For more information, check out the Swagger documentation at https://<hostname>.emg.illumina.com/api/apidoc/swagger#/Reports/get__api_test_v2_%7Bcase_name%7D_reports_%7Breport_type%7D_%7Breport_id%7D

Creating a Custom Preset Group with Additional Gene Panels

This example demonstrates how to create a custom preset group by combining an existing preset group (created with a case) and adding additional gene lists, HPO terms, inheritance modes, or other data on top of it.

Step 1: Create a Case with an Existing Preset Group

Before creating a custom preset group, ensure that a case has already been created using an existing preset group. For details on how to create a case, refer to .

Step 2: Create a Custom Preset Group

Once the case is created, use the API to add custom gene lists on top of the existing preset group associated with the case. Here's the Python code to achieve this:

For more information, check out the Swagger documentation at https://<hostname>.emg.illumina.com/api/apidoc/swagger#/Cases/post__api_test_%7Bcase_name%7D_preset_group

Advanced API Implementations

Getting Started

Before exploring the examples, make sure to log in to the platform. More information on this can be found in the API Beginner Guide.

After authentication, you will receive a token, which remains valid for a certain period of time.

For more information on advanced features, parameters, and additional examples, be sure to check out our Swagger documentation by going to https://<hostname>.emg.illumina.com/api/apidoc/swagger#/

Use cases

Automating Case Management: Creation and Status Check
Assigning Participants
Retrieving Case Info, Tags, Variants, and Changing Status

Automating Case Management: Creation and Status Check

This example demonstrates how to automate case management, including case creation, checking if the case status is "finalized," and generating a report.

Step 1: Create the Payload

First, construct a JSON payload with all the necessary case data.

Refer to the API documentation for more details on required fields, or go to https://<hostname>.emg.illumina.com/api/apidoc/swagger#/Cases/post__api_cases_v2_cases

Step 2: Send a POST Request

To create a case, send a POST request using the payload. Remember to replace any values enclosed in < > with your specific data.

Step 3: Retrieve Case Status and Name

After creating the case, you can retrieve the status and name from the API response.

Assigning Participants

Step 1: Retrieve Participant IDs by Email

Before assigning participants to cases, you can retrieve their IDs by searching for their email addresses.

Step 2: Assign Participants to the Case

Finally, assign participants to the case using their IDs.

Retrieving Case Info, Tags, Variants, and Changing Status

This example demonstrates how to retrieve tagged variants and the associated variant information from a case, and change the case status.

Step 1: Obtain the Case Name

If you don't have the case name yet, follow the steps outlined in Steps 1 and 2 of to create a case and retrieve the case name.

Step 2: Retrieve case info

Use this API route to get some basic information on a case: creation time, creator, last updated time, case name, case status.

Step 3: Send a GET Request to Retrieve Case Tags

To pull the case data, including tagged variants, send a GET request.

For more information, check out the Swagger documentation at https://<hostname>.emg.illumina.com/api/apidoc/swagger#/Candidates/get__api_candidates_%7Bcase_name%7D

Step 4: Update Case Status to a Custom Status

After retrieving the case, update the status to "custom_status_1".

Managing Finalized Cases and Generating Reports

Step 1: Retrieve Cases Finalized in the Last 24 Hours

Retrieve cases that were finalized within the last 24 hours.

Another option for retrieving a finalized case is to use . This option allows to receive notifications on case status change instead of checking via API.

Step 2: Generate a Report

Reports can only be generated for finalized cases. To generate a report, send the following GET request:

Creating a Custom Preset Group with Additional Gene Panels

Step 1: Create a Case with an Existing Preset Group

Before creating a custom preset group, ensure that a case has already been created using an existing preset group. For details on how to create a case, refer to .

Step 2: Create a Custom Preset Group

Once the case is created, use the API to add custom gene lists on top of the existing preset group associated with the case. Here's the Python code to achieve this:

For more information, check out the Swagger documentation at https://<hostname>.emg.illumina.com/api/apidoc/swagger#/Cases/post__api_test_%7Bcase_name%7D_preset_group

import requests

route_case_creation_url = 'https://<hostname>.emg.illumina.com/api/cases/v2/cases/'
payload = {
    "sharing_level": 0,
    "should_upload": False,
    "test_data": {
        "analysis_type": None,
        "boostGenes": False,
        "consanguinity": False,
        "disease_penetrance": 100,
        "disease_severity": "",
        "diseases": [],
        "gene_list": {
            "id": 1,
            "type": "all",
            "visible": False
        },
        "incidental_findings": None,
        "inheritance_modes": [],
        "labels": [],
        "notes": "",
        "patients": {
            "other": [],
            "proband": {
                "dead": False,
                "detailed_ethnicity": {
                    "maternal": [],
                    "paternal": []
                },
                "fastq_sample": "<proband sample name>",
                "gender": "<proband gender>",
                "healthy": False,
                "id": "proband",
                "ignore": False,
                "notes": "",
                "phenotypes": [
                    {
                        "id": "phenotypes/<EMG_PHENOTYPE_0011856>",
                        "name": "Pica"
                    },
                    {
                        "id": "phenotypes/<EMG_PHENOTYPE_0000969>",
                        "name": "Edema"
                    }
                ],
                "quality": "",
                "relationship": "Test Subject",
                "zygosity": ""
            }
        },
        "sample_type": "<fastq or vcf>",
        "samples": [
            {
                "directoryPath": "",
                "fastq": "<proband sample name>",
                "sampleFiles": [
                    {
                        "filename": "<proband file 1>.fastq.gz",
                        "path": "<full path/proband file 1>.fastq.gz",
                        "size": <file size>,
                        "status": "uploaded",
                        "storage_id": <storage provider id>
                    },
                    {
                        "filename": "<proband file 2>.fastq.gz",
                        "path": "<full path/proband file 2>.fastq.gz",
                        "size": <file size>,
                        "status": "uploaded",
                        "storage_id": <storage provider id>
                    }
                ],
                "sampleType": "<fastq or vcf>",
                "status": "uploaded",
                "storage_id": <storage provider id>
            }
        ],
        "selected_preset_set": None,
        "sequence_info": {
            "intersect_bed_id": None,
            "kit": "<kit name>",
            "kit_id": <kit id>
        },
        "type": "<case type>"
    }
}

headers = {'Authorization': 'Bearer <your-auth-token>'}
response = requests.post(route_case_creation_url, json=payload, headers=headers)

import requests

route_case_creation_url = 'https://<hostname>.emg.illumina.com/api/cases/v2/cases/'
payload = {
    "sharing_level": 0,
    "should_upload": False,
    "test_data": {
        "analysis_type": None,
        "boostGenes": False,
        "consanguinity": False,
        "disease_penetrance": 100,
        "disease_severity": "",
        "diseases": [],
        "gene_list": {
            "id": 1,
            "type": "all",
            "visible": False
        },
        "incidental_findings": None,
        "inheritance_modes": [],
        "labels": [],
        "notes": "",
        "patients": {
            "other": [],
            "proband": {
                "dead": False,
                "detailed_ethnicity": {
                    "maternal": [],
                    "paternal": []
                },
                "fastq_sample": "<proband sample name>",
                "gender": "<proband gender>",
                "healthy": False,
                "id": "proband",
                "ignore": False,
                "notes": "",
                "phenotypes": [
                    {
                        "id": "phenotypes/<EMG_PHENOTYPE_0011856>",
                        "name": "Pica"
                    },
                    {
                        "id": "phenotypes/<EMG_PHENOTYPE_0000969>",
                        "name": "Edema"
                    }
                ],
                "quality": "",
                "relationship": "Test Subject",
                "zygosity": ""
            }
        },
        "sample_type": "<fastq or vcf>",
        "samples": [
            {
                "directoryPath": "",
                "fastq": "<proband sample name>",
                "sampleFiles": [
                    {
                        "filename": "<proband file 1>.fastq.gz",
                        "path": "<full path/proband file 1>.fastq.gz",
                        "size": <file size>,
                        "status": "uploaded",
                        "storage_id": <storage provider id>
                    },
                    {
                        "filename": "<proband file 2>.fastq.gz",
                        "path": "<full path/proband file 2>.fastq.gz",
                        "size": <file size>,
                        "status": "uploaded",
                        "storage_id": <storage provider id>
                    }
                ],
                "sampleType": "<fastq or vcf>",
                "status": "uploaded",
                "storage_id": <storage provider id>
            }
        ],
        "selected_preset_set": None,
        "sequence_info": {
            "intersect_bed_id": None,
            "kit": "<kit name>",
            "kit_id": <kit id>
        },
        "type": "<case type>"
    }
}

headers = {'Authorization': 'Bearer <your-auth-token>'}
response = requests.post(route_case_creation_url, json=payload, headers=headers)

Advanced API Implementations

hashtagGetting Started

hashtagUse cases

hashtagAutomating Case Management: Creation and Status Check

hashtagStep 1: Create the Payload

hashtagStep 2: Send a POST Request

hashtagStep 3: Retrieve Case Status and Name

hashtagAssigning Participants

hashtagStep 1: Retrieve Participant IDs by Email

hashtagStep 2: Assign Participants to the Case

hashtagRetrieving Case Info, Tags, Variants, and Changing Status

hashtagStep 1: Obtain the Case Name

hashtagStep 2: Retrieve case info

hashtagStep 3: Send a GET Request to Retrieve Case Tags

hashtagStep 4: Update Case Status to a Custom Status

hashtagManaging Finalized Cases and Generating Reports

hashtagStep 1: Retrieve Cases Finalized in the Last 24 Hours

hashtagStep 2: Generate a Report

hashtagCreating a Custom Preset Group with Additional Gene Panels

hashtagStep 1: Create a Case with an Existing Preset Group

hashtagStep 2: Create a Custom Preset Group

Advanced API Implementations

hashtagGetting Started

hashtagUse cases

hashtagAutomating Case Management: Creation and Status Check

hashtagStep 1: Create the Payload

hashtagStep 2: Send a POST Request

hashtagStep 3: Retrieve Case Status and Name

hashtagAssigning Participants

hashtagStep 1: Retrieve Participant IDs by Email

hashtagStep 2: Assign Participants to the Case

hashtagRetrieving Case Info, Tags, Variants, and Changing Status

hashtagStep 1: Obtain the Case Name

hashtagStep 2: Retrieve case info

hashtagStep 3: Send a GET Request to Retrieve Case Tags

hashtagStep 4: Update Case Status to a Custom Status

hashtagManaging Finalized Cases and Generating Reports

hashtagStep 1: Retrieve Cases Finalized in the Last 24 Hours

hashtagStep 2: Generate a Report

hashtagCreating a Custom Preset Group with Additional Gene Panels

hashtagStep 1: Create a Case with an Existing Preset Group

hashtagStep 2: Create a Custom Preset Group

Getting Started

Use cases

Automating Case Management: Creation and Status Check

Step 1: Create the Payload

Step 2: Send a POST Request

Step 3: Retrieve Case Status and Name

Assigning Participants

Step 1: Retrieve Participant IDs by Email

Step 2: Assign Participants to the Case

Retrieving Case Info, Tags, Variants, and Changing Status

Step 1: Obtain the Case Name

Step 2: Retrieve case info

Step 3: Send a GET Request to Retrieve Case Tags

Step 4: Update Case Status to a Custom Status

Managing Finalized Cases and Generating Reports

Step 1: Retrieve Cases Finalized in the Last 24 Hours

Step 2: Generate a Report

Creating a Custom Preset Group with Additional Gene Panels

Step 1: Create a Case with an Existing Preset Group

Step 2: Create a Custom Preset Group

Getting Started

Use cases

Automating Case Management: Creation and Status Check

Step 1: Create the Payload

Step 2: Send a POST Request

Step 3: Retrieve Case Status and Name

Assigning Participants

Step 1: Retrieve Participant IDs by Email

Step 2: Assign Participants to the Case

Retrieving Case Info, Tags, Variants, and Changing Status

Step 1: Obtain the Case Name

Step 2: Retrieve case info

Step 3: Send a GET Request to Retrieve Case Tags

Step 4: Update Case Status to a Custom Status

Managing Finalized Cases and Generating Reports

Step 1: Retrieve Cases Finalized in the Last 24 Hours

Step 2: Generate a Report

Creating a Custom Preset Group with Additional Gene Panels

Step 1: Create a Case with an Existing Preset Group

Step 2: Create a Custom Preset Group