API response descriptions
Interpretation Request List: /api/2/interpretation-request/¶
This endpoint returns a "list" of referrals in the CIP-API that the user is authorised to access.
Please refer to the Swagger documentation for a full list of parameters that can used with this endpoint
| Field Name | Type | Description |
|---|---|---|
| interpretation_request_id | string | case identifier |
| cip | string | Name of the company acting as interpretation partner (Decision Support System). Possible values in GMS are: 'congenica', 'illumina', 'genomics_england' |
| cohort_id | string | In GMS, the referral ID and an integer representing the version of the clinical data. |
| sample_type | string | it can take 2 values: cancer or raredisease |
| sites | array | This is 100K specific and should not be used for GMS. Specific sites (GLHs and Labs) associated with GMS referrals should be obtained from relevant fields in the referral object |
| last_status | string | The last status this case has entered |
| proband | string | Proband ID e.g. p123456789 |
| clinical_reports | array | List of Dictionaries linking to Clinical Reports associated with the case |
| interpreted_genomes | array | List containing one element per Interpreted Genome associated to the case. Only version of the interpreted genome and creation date are present in each element. For example: { "create_at |
| number_of_samples | integer | The number of sequenced samples associated with a referral |
| last_update | string | The time the status of this case changed ISO 8601 timestamp in format "YYYY-MM- DDThh:mm:ss.sZ"Example: 2020-08-10T12:38:55.606612Z. Note this is different from the last_modified field |
| files | array | This field contains a list of files associated with the case. "url", "file_name" and "file_type" are the expected fields in each item. Any type of file will be allowed, but generally, only HTMLs and CSV are present in this list. Although is possible to associate files to rare disease cases. This list is expected to be populated only for cancer cases |
| case_priority | string | 'low', 'medium', 'high' or 'urgent'. For GMS cases, the interpretation request case_priority maps to the referral_test priority as follows: ‘medium’ -> ‘routine’ ‘urgent’ -> ‘urgent’ |
| tags | array | Tags associated with the case. These tags are manually created when a label is necessary in one case. These tags are a tool for the internal users at GEL, they are not expected to be used by external users. |
| assembly | string | Can either be GRCh38 or GRCh37 |
| workflow_status | string | The latest workflow status of the case in the associated Decision Support System |
| case_id | string | Case identifier: is compound by a prefix (associated to the DSS partner that will ingest this case), the interpretation_request_id and the version |
| last_modified | string | The time the case was last modified ISO 8601 timestamp in the format "YYYY-MM-DDThh:mm:ss.sZ" Example: 2020-08-10T12:38:55.606612Z Note this is different from the last_update field |
| program | string | 'raredisease' or 'cancer' |
| family_id | string | Only present for rare disease cases, in GMS this is the Referral ID |
| referral | object | Only present if using extra_params=show_referral Referral Information (see Referral Table) added when test is ordered in the Test Order Management System (TOMS). Referral information includes details of the requesting organisation (the GLH; lab ordering the test) and the interpreting organisation (the GLH; lab responsible for the interpretation of the case) |
| interpretation_flags | object | Only present if using extra_params=show_interpretation_flags. Flags applied to the case during processing through the WGS pipeline |
| dss_arrival_date | string | only present if using extra_params=dss_arrival_date. The time the referral first arrived in the Decision Support System. ISO 8601 timestamp in the format "YYYY-MM- DDThh:mm:ss.sZ". Example: "2021-08-09T11:00:17.473774Z". This date should match the earliest date the referral was first “sent_to_gmcs” and will be “null” if the referral has not got this status. |
{
"interpretation_request_id": "1-1",
"cip": "congenica",
"cohort_id": "participant_HG00111_1",
"sample_type": "raredisease",
"sites": [
"RJ7"
],
"last_status": "report_sent",
"proband": "participant_HG00111",
"clinical_reports": [
{
"url": "https://cipapi-beta.genomicsengland.co.uk/api/2/clinical-report/1/1/1"
}
],
"interpreted_genomes": [
{
"cip_version": 1,
"create_at": "2019-03-26T09:45:22.837810Z"
}
],
"number_of_samples": 1,
"last_update": "2019-04-26 16:13:31",
"files": [],
"case_priority": "low",
"tags": [],
"assembly": "GRCh38",
"workflow_status": "Pending Review",
"case_id": "GEL-1-1",
"last_modified": "2019-04-26T16:13:31.171957Z",
"program": "rare_disease",
"family_id": "participant_HG00111",
"interpretation_flags": null,
"dss_arrival_date": null
},
Interpretation Request Endpoint: /api/2/interpretation-request/{id}/{version}¶
This endpoint returns complete set of details about a referral, including pedigree information, interpretation service results e.g. tiering results as well as clinical reports and exit questionnaires
| Field Name | Type | Description |
|---|---|---|
| status | array[object] | This is an array of all statuses this case has been. Each element in the array contains the following items: status: for a full detailed list of all possible status see here created_at: date time at which this case entered in this status. user: The user that triggered the action that made the case enter in this status |
| interpretation_request_id | string | Case identifier |
| version | integer | The version of this referral |
| created_at | datetime | Datetime of the creation of the case |
| last_modified | datetime | The time the case was last modified ISO 8601 timestamp in format "YYYY-MM-DDThh:mm:ss.sZ"Example: 2020-08-10T12:38:55.606612Z |
| cip | string | Name of the company acting as interpretation partner (Decision Support System). Possible values in GMS are: 'congenica', 'illumina', 'genomics_england' |
| sample_type | string | It can take 2 values: cancer and raredisease |
| interpretation_request_data | Object | This is a dictionary of one single item json_request which contains the interpreation_request_data. Depending on the program it will be either: Rare Disease Interpretation Request Data, or Cancer Interpretation Request Data |
| gel_tiering_qc_outcome | list | Not used in GMS. Always an empty list |
| cohort_id | string | In GMS, the referral ID and an integer representing the version of the clinical data. |
| interpreted_genome | array[InterpretedGenome] | List of all interpreted genomes associated to this case. In GMS for rare disease cases exomiser and genomics_england_tiering interpreted genomes, for cancer only genomics_england_tiering is expected |
| clinical_report | array[ClinicalReport] | List of clinical reports associated to this case. For rare disease the clinical report is generated by Interpretation Portal or Congenica. For cancer referrals, clinical reports are generated by the bioinformatics pipeline (containing a subset of the Cancer genomics England tiering interpreted genome) |
| proband | string | Proband ID e.g. p123456789 |
| number_of_samples | integer | number of sequenced samples in this analysis |
| files | array[File] | This field contains a list of files associated with the case. "url", "file_name" and "file_type" are the expected fields in each item. Any type of file will be allowed, but generally, only HTMLs and CSV are present in this list. Although it is possible to associate files to rare disease cases, this list is expected to be populated only for cancer cases |
| last_status | string | Last status this case has entered |
| labkey_links | array | Not used in GMS. Always an empty list |
| case_priority | string | 'low', 'medium', 'high' or 'urgent'. For GMS cases, the interpretation request case_priority maps to the referral_test priority as follows: ‘medium’ -> ‘routine’ ‘urgent’ -> ‘urgent’ |
| tags | array | Tags associated to the case. These tags are manually created when a label is necessary in one case. These tags are a tool for the internal users at GEL, they are not expected to be used by external users. |
| family_id | string | Only present for rare disease cases, in GMS this is the Referral Id |
| assembly | string | Fixed value: GRCh38 |
| case_id | string | Case identifier: is compound by a prefix (associated to the DSS partner that will ingest this case), the interpretation_request_id and the version |
| program | Program | it can take 2 values: cancer and raredisease |
| cancer_participant | string | Only present for cancer cases, in GMS this is the Referral Id |
| referral | [Referral] | Referral information associated to this case. Please note that this field is conditional to the query parameter: ?extra_params=show_referral |
{
status: [...],
interpretation_request_id: 2533,
version: "1",
created_at: "2020-01-02T15:19:13.832526Z",
last_modified: "2020-01-02T15:19:14.409335Z",
cip: "genomics_england",
sample_type: "raredisease",
interpretation_request_data: {},
gel_tiering_qc_outcome: [...],
cohort_id: "9UILCQZCTX6H",
interpreted_genome: [...],
clinical_report: [...],
proband: "participant_NA19314",
number_of_samples: 1,
files: [...],
last_status: "interpretation_generated",
labkey_links: [...],
case_priority: "medium",
tags: [...],
family_id: "9UILCQZCTX6H",
assembly: "GRCh37",
case_id: "GEL-2533-1",
program: "rare_disease",
referral: {...}
}
Clinical Report Endpoint: /api/2/clinical-report¶
This endpoint returns a list of Clinical Reports
| Field Name | Type | Description |
|---|---|---|
| clinical_report_data | ClinicalReport | For Cancer referrals, Clinical Reports are created by the Bioinformatics Pipeline. For Rare disease referrals, Clinical Reports can be created in either the Interpretation Portal or DSS. For further info: Clinical Reports can be generated either in : Cancer clinical report, Congenica clinical report, Interpretation Portal clinical report. |
| created_at | datetime | Creation date-time of this clinical report |
| exit_questionnaire | ExitQuestionnaire | For extra documentation about the Exit Questionnaire look at the data model described in:https://gelreportmodels.genomicsengland.co.uk/html_schemas/org.gel.models.report.avro/6.0.1/ExitQuestionnaire.html#/schema/org.gel.models.report.avro.CancerExitQuestionnaireandhttps://gelreportmodels.genomicsengland.co.uk/html_schemas/org.gel.models.report.avro/6.0.1/ExitQuestionnaire.html#/schema/org.gel.models.report.avro.RareDiseaseExitQuestionnaire |
| clinical_report_version | Integer | This is the version of the clinical report. |
| valid | boolean | This value is used for internal checks, is expected to be always True |
| timestamp | Integer | The timestamp of the creation time |
Interpreted Genome Endpoint: /api/2/interpreted-genome¶
Returns a list of all the Interpreted Genomes (results of interpretation services)
| Field Name | Type | Description |
|---|---|---|
| cip_version | integer | Ordinal number of this interpreted genome (for this case) |
| created_at | datetime | Creation date-time of this interpreted genome |
| interpreted_genome_data | InterpretedGenome | The result of the interpretation service, for GMS it can be: Exomiser, Tiering Rare Disease and Tiering Cancer |
| gel_qc_outcome | array | Not used for GMS. Empty array expected |
| status | string | Not used for GMS. Empty array expected |
Referral Endpoint: /api/2/referral/¶
Returns a list of GMS referrals
| Field Name | Type | Description |
|---|---|---|
| referral_id | string | Referral human readable identifier |
| referral_uid | string | Referral internal unique identifier |
| ordering_date | Date | Ordering date of this referral |
| analysis_scope | string | it can take 2 values: cancer and raredisease |
| referral_data | Referral Object | This is the raw information for the referral data |
| last_modified | Datetime | Datetime of the last modification of the referral data |
| create_at | Datetime | Datetime of the registration of the referral data in the CIP-API |
| referral_test | ReferralTest | Referral Test data |
| requester_organisation_id | string | Requester Organisation id e.g. 2c429932-edd6-6b43-92b2-211ea05b4604 |
| requester_organisation_code | string | Requester organisation code e.g. RP4 |
| requester_organisation_name | string | Requester organisation name e.g. Great Ormond Street Hospital for Children NHS Foundation Trust |
| requester_organisation_national_grouping_id | string | Requester GLH code e.g. 69A70 |
| requester_organisation_national_grouping_name | string | Requester GLH name e.g. London North |
| econsent | string | Summary of the patient consent data. Contains 2 fields: participant_consent: Array with the consent information for all patients in this case. And, overall_econsent: It can take 3 values: green (all patients in the case have consented for primary findings), amber (at least one patient is missing the consent record, or the record is not completed), **red ** (at least one of the patients has not consented for primary findings) |
| clinical_indication_code | string | Clinical indication code |
| clinical_indication_full_name | string | Clinical indication name |
{
referral_id: "3AT3LJKANCJG",
referral_uid: "NNBVTANU-S84F-E6M4-AK5K-DO69RABOCMNU",
ordering_date: "2019-06-30",
analysis_scope: "raredisease",
referral_data: {},
last_modified: "2020-01-02T15:21:24.239129Z",
create_at: "2020-01-02T15:21:24.239102Z",
referral_test: [],
requester_organisation_id: "26217e14-c3ae-0745-a83b-c488272c58d7",
requester_organisation_code: "RFS",
requester_organisation_name: "Chesterfield Royal Hospital NHS Foundation Trust",
requester_organisation_national_grouping_id: "699M0",
requester_organisation_national_grouping_name: "East Mids and East of England",
econsent: {},
clinical_indication_code: "R29",
clinical_indication_full_name: "Intellectual disability"
},
Consent Endpoint: /api/2/referral/e-consent/{referral_id}/¶
Returns a list of patients in a referral and their consent status
| Field Name | Type | Description |
|---|---|---|
| participant_id | string | Patient internal id e.g. bd731d96-cf96-4aba-8405-26c7b23275dc |
| referral_id | string | Referral internal id e.g. c89b0acd-ecb6-4967-afc5-a3b91ed54238 |
| primaryGenomicTestingConsent | string | Primary finding testing consent. Possible values are: undefined, yes, no |
| researchDiscussion | string | Whether the research discussion took place. Possible values are: undefined, yes, no |
| researchFindingConsent | string | Research Finding consent. Possible values are: undefined, yes, no |
| pharmocogenomicsFindingConsent | string | Pharmocogenomics Finding consent. Possible values are: undefined, yes, no. Please note there is a typo in this field it will be corrected in next releases. |
| healthRelatedFindingConsent | string | Health Related Finding testing consent. Possible values are: undefined, yes, no |
| carrierStatusConsent | string | Carrier Status consent. Possible values are: undefined, yes, no |
| laststring_modified | Datetime | Datetime of the last modification of the referral data |
{
econsent: [
{
participant_id: "d19d0b42-d04c-40c4-b9d2-2f444b205a12",
referral_id: "544cdf53-d502-4d86-8ec6-b15c8a9bdf2a",
primaryGenomicTestingConsent: "yes",
researchDiscussion: "yes",
researchFindingConsent: "yes",
pharmocogenomicsFindingConsent: "undefined",
healthRelatedFindingConsent: "undefined",
carrierStatusConsent: "undefined",
last_modified: "2021-11-29T15:18:58.915454Z"
},
{
participant_id: "97903fef-8e1f-4549-972a-44eb03eb2e80",
referral_id: "544cdf53-d502-4d86-8ec6-b15c8a9bdf2a",
primaryGenomicTestingConsent: "yes",
researchDiscussion: "yes",
researchFindingConsent: "yes",
pharmocogenomicsFindingConsent: "undefined",
healthRelatedFindingConsent: "undefined",
carrierStatusConsent: "undefined",
last_modified: "2021-11-29T15:19:00.353379Z"
},
{
participant_id: "428a56ed-927d-4d25-96f7-23b5b0b1928c",
referral_id: "544cdf53-d502-4d86-8ec6-b15c8a9bdf2a",
primaryGenomicTestingConsent: "yes",
researchDiscussion: "yes",
researchFindingConsent: "yes",
pharmocogenomicsFindingConsent: "undefined",
healthRelatedFindingConsent: "undefined",
carrierStatusConsent: "undefined",
last_modified: "2021-11-29T15:19:00.869038Z"
}
]
}
Referral Test Endpoint¶
| Field Name | Type | Description |
|---|---|---|
| referral_test_id | string | Human readable referral test identifier |
| clinical_indication_test_type_id | string | Internal identifier for the type of clinical indication test i.e a42fb6e7-532b-4a41-b944-d01840ec74fa |
| clinical_indication_test_code | string | clinical indication test code e.g. M80.1 |
| clinical_indication_test_name | string | clinical indication test name e.g. WGS Germline and Tumour |
| test_technology_id | string | Internal id of the technology used in this test |
| testTechnologyDescription | string | Description of the technology used in this test. e.g. WGS |
| ordering_date | date | Ordering date of this referral test |
| interpretation_request | string | Interpretation request URL associated to this referral (relationship between referral test and interpretation request is 1:1). Only WGS tests will have a interpretation request associated to it. |
| create_at | datetime | Datetime of the registration of the referral test data in the CIP-API |
| last_modified | datetime | Datetime of the last modification of the referral test data |
| interpreter_organisation_id | string | Interpreter Organisation id e.g. 2c429932-edd6-6b43-92b2-211ea05b4604 |
| interpreter_organisation_code | string | Interpreter organisation code e.g. RP4 |
| interpreter_organisation_name | string | Interpreter organisation name e.g. Great Ormond Street Hospital for Children NHS Foundation Trust) |
| interpreter_organisation_id | string | Interpreter Organisation id e.g. 2c429932-edd6-6b43-92b2-211ea05b4604 |
| interpreter_organisation_national_grouping_name | string | Interpreter GLH name e.g. London North |
| interpretation_request_id | integer | Interpretation request id associated to this referral |
| interpretation_request_version | interger | Interpretation request version associated to this referral |
{
"referral_test_id": "193a0c05-be6f-46c6-a91b-9bfd9b254166",
"clinical_indication_test_type_id": "1f3de9e5-9759-4849-9533-412b8294e14a",
"clinical_indication_test_code": "R104.3",
"clinical_indication_test_name": "Skeletal dysplasia WGS",
"test_technology_id": "2ad3a7f4-e917-4688-a53b-a560892bc748",
"testTechnologyDescription": "WGS",
"ordering_date": "2021-11-18",
"interpretation_request": "https://cipapi-gms-beta.gel.zone/api/2/interpretation-request/3106/1/",
"create_at": "2021-11-19T15:22:39.577805Z",
"last_modified": "2021-11-19T15:22:39.577829Z",
"interpreter_organisation_id": "79df6e6b-4c70-114b-9262-30ba10916cd9",
"interpreter_organisation_code": "69A70",
"interpreter_organisation_name": "North Thames Genomic Laboratory Hub",
"interpreter_organisation_national_grouping_id": "69A70",
"interpreter_organisation_national_grouping_name": "North Thames Genomic Laboratory Hub",
"interpretation_request_id": 3106,
"interpretation_request_version": 1
}
Last update:
2023-03-01