CIP-API Documentation¶
Welcome to the Genomics England Clinical Interpretation API (CIP-API). Genomics England processes Whole Genome Sequencing (WGS) data of families and cancer participants as part of the 100,000 genomes project as well as for the NHS Genomics Medicine Service (GMS), more about us here. This documentation is intended to support development of automated communication between the CIP-API, the Decision Support Systems (DDSs) and Third Party Integrators (TPIs), as well as bioinformaticians in the GLHs.
Base URLs¶
For end users, there is a suite of environments of the CIP-API available, find out more here.
The base API URLs are located at:
Warning
The SIT and UAT environments can be easily confused as they both contain BETA in their HSCN URLs!
Please refer here for further information about each environment and their intended use.
Authentication¶
The authentication method is based on a Bearer Token present in the header of each request. We recommend using the AD Client Credentials Flow to obtain the token, but you can also use the get-token endpoint in the CIP-API. Find more information on getting access and authentication.
This method requires a client_id and a client_secret which will be specific for the specific tenant, as seen below:
POST Token from AD¶
Example Request
curl --location --request POST 'https://login.microsoftonline.com/{tenantid}/oauth2/token' \
--header 'Authorization: Basic ({appID}:{Secret} in Base64 encoding)' \
--header 'content-type: multipart/form-data' \
--form 'grant_type="client_credentials"' \
--form 'client_id=""' \
--form 'client_secret=""'
Alternatively, you can use the get-token endpoint in the CIP-API to obtain an authentication token. Only use this method if you are planning to only use ad hoc scripts on your local machine.
POST Get Token Endpoint¶
To send requests to the CIP-API, you will have to send the obtained token in the authorisation header. Remember, that you can only access the production CIP-API while on the NHS N3 (HSCN) network.
Useful Endpoints¶
Below, you can find a summary of the most commonly used endpoints in the CIP-API (SIT environment for these examples). Not all the endpoints will be covered in this documentation but a full list with a Swagger user interface can be found on the api/2/docs endpoint of any of the CIP-API instances. For example, the SIT CIP-API swagger user interface is found here:
https://cipapi-beta.genomicsengland.co.uk/api/2/docs
Note
The swagger user interface for api/1 endpoints is no longer available.
GET Overview of all Clinical Reports¶
Example Request
POST Token from AD¶
https://cipapi-beta.genomicsengland.co.uk/api/2/clinical-report/{IR_id}/{IR_version}/{clinical_report_version}?reports_v6=true&as=json
Example Request
GET Overview of all Exit Questionnaires¶
Example Request
PUT Create an Exit Questionnaire for a case¶
{
"eventDate": "2020-04-20",
"reporter": "jbloggs",
"familyLevelQuestions": {
"caseSolvedFamily": "no",
"segregationQuestion": "no",
"additionalComments": "No tier 1 or 2 variants detected"
},
"variantGroupLevelQuestions": []
}
Example Request
curl --location --request PUT 'https://cipapi-beta.genomicsengland.co.uk/api/2/exit-questionnaire/2535/1/1/' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: JWT ' \
--data-raw '{
"eventDate": "2020-04-20",
"reporter": "jbloggs",
"familyLevelQuestions": {
"caseSolvedFamily": "no",
"segregationQuestion": "no",
"additionalComments": "No tier 1 or 2 variants detected"
},
"variantGroupLevelQuestions": []
}'
GET Retrieve an Exit Questionnaire¶
https://cipapi-beta.genomicsengland.co.uk/api/2/exit-questionnaire/{IR_id}/{IR_version}/{clinical_report_version}/
Example Request
POST Create a Clinical Report for a case¶
https://cipapi-beta.genomicsengland.co.uk/api/2/clinical-report/genomics_england_tiering/raredisease/{IR_id}-{IR_version}/?reports_v6=true
{
"interpretationRequestId": "2535",
"interpretationRequestVersion": 1,
"reportingDate": "2020-04-20",
"user": "jbloggs",
"variants": [],
"structuralVariants": [],
"chromosomalRearrangements": null,
"shortTandemRepeats": [],
"uniparentalDisomies": null,
"karyotypes": null,
"genomicInterpretation": "No tier 1 or 2 variants detected",
"additionalAnalysisPanels": null,
"references": [],
"referenceDatabasesVersions": {
"genomeAssembly": "GRCh37"
},
"softwareVersions": {
"PhyloP": "phyloP46way (1990-09-08)",
"MutationTaster": "dbNSFP v2.9",
"VVP": "v1.1",
"PolyPhen-2": "v2.2.2",
"SIFT": "dbNSFP v2.9",
"Omicia Score": "v2.0",
"pipeline_version": "1.1.1"
}
}
Example Request
curl --location --request POST 'https://cipapi-beta.genomicsengland.co.uk/api/2/clinical-report/genomics_england_tiering/raredisease/2535-1/?reports_v6=true' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: JWT ' \
--data-raw '{
"interpretationRequestId": "2535",
"interpretationRequestVersion": 1,
"reportingDate": "2020-04-20",
"user": "jbloggs",
"variants": [],
"structuralVariants": [],
"chromosomalRearrangements": null,
"shortTandemRepeats": [],
"uniparentalDisomies": null,
"karyotypes": null,
"genomicInterpretation": "No tier 1 or 2 variants detected",
"additionalAnalysisPanels": null,
"references": [],
"referenceDatabasesVersions": {
"genomeAssembly": "GRCh37"
},
"softwareVersions": {
"PhyloP": "phyloP46way (1990-09-08)",
"MutationTaster": "dbNSFP v2.9",
"VVP": "v1.1",
"PolyPhen-2": "v2.2.2",
"SIFT": "dbNSFP v2.9",
"Omicia Score": "v2.0",
"pipeline_version": "1.1.1"
}
}'
GET Overview of all the cases¶
Example Request
GET Retrieve a case¶
Example Request
GET Overview of all Exit Questionnaires¶
Example Request
GET Retrieve workflow status history for a case¶
https://cipapi-beta.genomicsengland.co.uk/api/2/interpretation-request/{IR_id}/{IR_version}/workflow_status?page=1
Example Request
Target Audience¶
Genomic Laboratory Hub (GLH) staff handling the interpretation of Rare Disease and Cancer whole genome sequencing (WGS) data using the Genomics England Interpretation Platform.
Other Third Party Audience
The external audience for this document may include medical device regulators and associated agencies in the pursuit of medical device regulatory and standards certification including:
UK Competent Authority: (CAs) the Medicines and Healthcare Products Regulatory Agency (MHRA); Notified Bodies (NBs) such as BSI Group; NHS Digital; the NHS IT regulator in England and Wales. This document may also be requested by existing and prospective Genomics England customers as part of their procurement process. All external distribution of the must be approved by a member of the Quality Improvements and Regulatory Affairs team prior to circulation.
Additional Resources¶
Here are some additional resources that you might find useful:
:link: Documentation for all the Interpretation Platform Applications
:link: Rare Disease Genome Analysis Guide
:link: Cancer Genome Analysis Guide
This link will take you to an NHS Futures workspace. If you require support registering for access to this space, please contact england.genomics@nhs.net. Users with NHS email addresses will have immediate access on registration.
:link: 100K Rare Disease Documentation
:link: 100K Cancer Documentation
Feedback¶
If you have any feedback on the Interpretation Portal please contact the Genomics England Service Desk at ge-servicedesk@genomicsengland.co.uk.