Authentication

Before accessing your data you first need to obtain an authentication "token". Once you have authenticated and obtained a token you can query the API for your data

• URL V2: /api/2/get-token/
• Method: POST
• Content Type: application/json
• Content: {“username”: “user”, “password”: “password”}

Case Identifiers

The cases will be identified using an interpretation Id and a version. Two cases with same interpretation Id will refer to same family/test/participant, in this case they will have different versions, and potentially the data associated will be different.

In the past Genomics England chose to use a prefix (three letters) to define the full identifier of the cases based on the CIP it was assigned to,this will disappear and we will use only the Id + version to create the case identifier.

Nomenclature and Examples

• Interpretation Id (aka ir_id, interpretationRequestId). i.e, 12346
• Version (aka ir_version). i.e, 2
• Case Id (aka case_id). i.e, 12346-2 or XXX-12346-2

(CIP-API) Actions and web services definitions

• Submit a Clinical Report
• Update WorkFlow Status
• Update case interpretation log

Submit a Clinical Report

This action should be triggered each time a user with the right permissions creates a clinical report

• URL V2: /api/2/clinical-report/{partner_id}/{analysis_type}/{case_id}/
• Parameters:
  • partner_id: company/server name (provided by Genomics England)
  • analysis_type: analysis type <raredisease or cancer>
  • report_id: report id, as indicated in the Interpretation Data payload ([XXX-]000-1)
• Method: POST
• Content Type: application/json
• Content: JSON following the Clinical Report Model

Update WorkFlow Status

This end point should be used each time any relevant changes happen in the decision support system. The end goal of this is keep both systems (CIP-API and DSS) synchronised so Genomics England is aware of the progress of each case.

• URL V2: /api/2/interpretation-request/{ir_id}/{ir_version}/workflow_status or /api/2/interpretation-request/{case_id}/workflow_status
• Parameters:
  • ir_id: Interpretation request id (usually a number)
  • ir_version: Interpretation request version (a number)
  • case_id: case_id as defined in the Interpretation Data payload ([XXX-]000-1)
• Method: PATCH
• Content Type: application/json
• Content:

{
"status": "(Enumeration)New Status",
"service": "(string)The Decision support system name",
"message": "(string)Verbose message for the status change",
"url": "(string)URL to the Live service where this change of status happened"
}

Update case variant interpretation log

This end point should be used each time the decision support system needs to update Genomics England with information collected by the users at the variant level. When it is triggered depends on the DSS implementation. It is the decision of the DSS provider whether to push a bulk of variant interpretation logs at specific points in its pipeline or doing atomic updates as they happen.

• URL V2: /api/2/interpretation-request/{case_id}/variant-interpretation-log
• Parameters:
  • ir_id: Interpretation request id (usually a number)
  • ir_version: Interpretation request version (a number)
• Method: PATCH
• Content Type: application/json
• Content: JSON following the Variant Interpretation Log Model

(DSS) web services definitions

Create a case

This end point will be used by Genomics England to send a new case (or a revision of an existing one).

• URL V2: /api/{version}/interpretation-request/
• Method: POST
• Content Type: application/json
• Content: JSON following the Interpretation data Model for Rare disease | Interpretation data Model for Cancer
• Response Content Type: application/json
• Response Content:

 {
  "caseId": "(string) DSS Internal Id for this case",
  "status": "Processing Request",
  "statusMessage": "Verbose status message",
  "createdDate": "2017-10-09"
}

Archive a case

This end point will be used by Genomics England to order an archiving of a case

• URL V2: /api/{version}/interpretation-request/{case_id}/archive/
• Method: PATCH
• Content Type: application/json
• Content: No payload required
• Response Content Type: application/json
• Response Content:

 {
  "caseId": "(string) DSS Internal Id for this case",
  "status": "Processing Request",
  "statusMessage": "Verbose status message",
  "createdDate": "2017-10-09"
}

Delete a case

This end point will be used by Genomics England to order a full deletion of a case

• URL V2: /api/{version}/interpretation-request/{case_id}/
• Method: DELETE
• Content Type: application/json
• Content: No payload required
• Response Content Type: application/json
• Response Content:

 {
  "caseId": "(string) DSS Internal Id for this case",
  "status": "Processing Request",
  "statusMessage": "Verbose status message",
  "createdDate": "2017-10-09"
}