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.
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 = ["user1@example.com", "user2@example.com"]
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:
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 using the v35 functionality.
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
