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