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

• Managing Finalized Cases and Generating Reports

• Creating a Custom Preset Group with Additional Gene Panels

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.

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)

Step 3: Retrieve Case Status and Name

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

# Check response status:
status = response.json().get("Status")

# Get the case name:
case_name = response.json().get("name")

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.

import requests

# Define the email addresses you want to search for
emails_to_search = ["[email protected]", "[email protected]"]

participant_ids = []
user_url = 'https://<hostname>.emg.illumina.com/api/user/org_users/'
response = requests.get(user_url, headers=headers)
if response.status_code == 200:
    users = response.json().get("hits", [])
    for user in users:
        if user.get("email") in emails_to_search:
            participant_ids.append(user.get("id"))

Step 2: Assign Participants to the Case

Finally, assign participants to the case using their IDs.

assign_url = f'https://<hostname>.emg.illumina.com/api/participant/{case_name}'

payload = {"action": "assign", "ids": participant_ids}

response = requests.post(url=assign_url, json=payload, headers=headers)

if response.status_code == 200:
    print(f"Participants {participant_ids} assigned to case {case_name}.")
else:
    print(f"Failed to assign participants to case {case_name}. Response: {response.json()}")

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 Automating Case Management: Creation 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.

import requests

url = 'https://<hostname>.emg.illumina.com/api/test/{case_name}/info'
headers = {
    'Authorization': 'Bearer <your-auth-token>'
}

response = requests.get(url=url, headers=headers)

# Output the case information
print(response.json())

Step 3: Send a GET Request to Retrieve Case Tags

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

import requests

url = 'https://<hostname>.emg.illumina.com/api/candidates/{case_name}'
headers = {
    'Authorization': 'Bearer <your-auth-token>'
}

response = requests.get(url=url, headers=headers)

# Output the variants with tags and their information
print(response.json())

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

case_name = case.get("name")
update_url = f'https://<hostname>.emg.illumina.com/api/test/{case_name}'

payload = {"status": "custom_status_1"}

response = requests.put(url=update_url, json=payload, headers=headers)

if response.status_code == 200:
    print(f"Case {case_name} updated to 'custom_status_1'.")
else:
    print(f"Failed to update case {case_name}. Response: {response.json()}")

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.

from datetime import datetime, timedelta

# Calculate the date 24 hours ago
from_status_change_date = (datetime.now() - timedelta(days=1)).isoformat()

url = f'https://<hostname>.emg.illumina.com/api/test?from_status_change_date={from_status_change_date}&status=finalized'

response = requests.get(url=url, headers=headers)

finalized_cases = response.json()

Another option for retrieving a finalized case is to use webhooks. 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:

url = 'https://<hostname>.emg.illumina.com/api/test/{case_name}/reports/English/null/?candidates=true&full_export=true&incidental=true'
headers = {
    'Authorization': 'Bearer <your-auth-token>'
}
response = requests.get(url=url, headers=headers)
print(response.json())

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 Automating Case Management: Creation.

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:

import requests

case_name = "EMG123456789"
url = f'https://<hostname>.emg.illumina.com/api/test/<case_name>/preset_group'

headers = {'Authorization': 'Bearer <your-api-key>'}

# Define the gene lists to be added on top of the existing preset group
first_gene_list_name = "my gene list"
first_gene_list_id = 1
second_gene_list_name = "my gene list 2"
second_gene_list_id = 2

data = {
    "name": "<name-of-new-custom-preset-group>",
    "filter": {
        "search": [
            {
                "id": first_gene_list_id,
                "name": first_gene_list_name,
                "type": "gene list",
                "value": first_gene_list_name
            },
            {
                "id": second_gene_list_id,
                "name": second_gene_list_name,
                "type": "gene list",
                "value": second_gene_list_name
            }
        ]
    }
}

response = requests.post(url, json=data, headers=headers)

if response.status_code == 201:
    print("Custom preset group created successfully.")
else:
    print(f"Failed to create custom preset group. Status code: {response.status_code}")

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