PhenoTips » Developer Guide » API » API for pushing data to PhenomeCentral

API for pushing data to PhenomeCentral

 This API has only been used internally (by PhenoTips) and is subject to change within the next year. 

Anyone pushing data to phenomeCentral MUST have a PhenomeCentral account. While we can accept one account per site, we strongly recommend that each person sending data have their own personal PhenomeCentral account, for better keeping track of deposits and modifications.

Account requests are to be made at https://phenomecentral.org/register/PhenomeCentral/ and will be manually reviewed by the PhenomeCentral support team.

Please do not push test data to PhenomeCentral. In the development phase, use https://dev.phenomecentral.org as the receiving server.

Overview

Workflow

Sending data to PhenomeCentral is normally done in 2 steps:

1. Getting configuration from the server

Basically the configuration consists of 

  • Consents that users must tick off before depositing data: All users sending data to PhenomeCentral must (currently) confirm that the data they are about to deposit is from a real patient. Other consents, which are optional, allow users to publish more sensitive data such as family history, or to participate in matching over the MME.
  • Groups that the current is part of and that they may want to transfer ownership of a patient record to.

In theory this step can be skipped and the data be sent in Step 2 with a preset configuration. However this is not recommended because the list of required consents may evolve or the user's membership to PhenomeCentral groups may change.

2. Sending the patient data
This is where the user sends the actual patient data, together with the list of consents, the owner group (if applicable), and whether this should be a new record or an update to an existing record. if successful, the user will receive the PhenomeCentral identifier and URL of the patient they have deposited.

Push service endpoint

The main endpoint for communicating with PhenomeCentral is: https://phenomecentral.org/get/data/receivePatientData. Depending on the action parameter, this URL will:

  • for action = get_server_info, return the "server configuration", which includes:
    • consents that need to be ticked off by the user before they send any patient data
    • any PhenomeCentral groups that the user may want to transfer ownership of the data to
  • for action = push, send the patient data, together with the accepted consents and the ownership transfer (if any), as JSON.

The service ALWAYS returns a success HTTP status code (200: OK), unless there’s a server error. If the action failed for other reasons (e.g. wrong credentials, malformed input data, etc), this will be communicated in via a custom error code. See section "Error responses" for details.

How to push patient records to PhenomeCentral

Step 1: Get the configuration

URL: https://phenomecentral.org/get/data/receivePatientData
POST parameters:

  • action: get_server_info
  • username: <the PhenomeCentral user name>
  • password: <the PhenomeCentral account password>
  • push_protocol_version: 1.1
    The latest supported by PhenomeCentral (and recommended) protocol version is 1.1 . Previous protocol versions differ from this one in terms of expected patient JSON structure and consents support. Future protocol versions might add other incompatibilities.

    Response: JSON structured as follows:
{
 "success": true,
 "response_protocol_version": <server protocol version>,
 "user_groups": [...], // a JSON array (possibly empty) of strings, each string is a group name. These are the groups that the user is part of on PhenomeCentral.
 "consents": [
     {
      "id": <string>,
      "isRequired": {true|false},  // when true, server will reject any push requests which do not include the consent
      "status": {"set","not_set"},   // whether it is set by default; all PC consents are not set by default at the moment
      "label": <consent text to display to the user>
     },
     ...
  ],
 "accepted_fields": [...], //an array of internal field names which are enabled on the server
 "updates_enabled": {true|false},   // when true, an existing patient can be updated using GUID
 // other fields, not relevant for non-PhenoTips users
}

Example of consent JSON object:

{
 "id":"real",
 "isRequired":true,
 "status":"not_set",
 "label":"This patient is real"
}

Sample response:

{
 "accepted_fields": ["external_id", "last_name", "first_name", "date_of_birth", "date_of_death", "gender", "phenotype", "negative_phenotype", "omim_id"],
 "consents": [{
   "id": "real",
   "isRequired": true,
   "status": "not_set",
   "label": "I confirm that the data entered in this form corresponds to a real patient."
  }, {
   "id": "genes",
   "isRequired": false,
   "status": "not_set",
   "label": "I confirm that consent has been obtained to share this patient's genetic sequencing data (e.g., a VCF file) on restricted access databases."
  }],
 "user_groups": ["Care4Rare", "UDN"],
 "response_protocol_version": "1.2",
 "success": true,
 "updates_enabled": true
}

Step 2: Send the data

URL: https://phenomecentral.org/get/data/receivePatientData
POST parameters:

  • action: push
  • username: <the PhenomeCentral user name>
  • password: <the PhenomeCentral account password>
  • push_protocol_version: <version used>
  • patient_json: <the actual patient JSON object in PhenoTips format>
      The supported JSON format is documented in the PhenoTips Developer Guide.

  • patient_state: <JSON object>
    Format:{"consents" : [...] /*list of consent identifiers*/ }. The JSON object contains exactly one key consents, which is a JSON array of granted consents. Consent identifiers should be the ones received in get_server_info request. If a consent is configured as required on the receiving server, server will reject all push requests which do not include that consent.

  • groupname: <PhenomeCentral group name> (optional)
    (as returned by get_server_info request; when provided, the deposited patient will be owned by the group, and the user who pushes the data will be a collaborator)

  • patient_guid: <GUID of a patient that has been pushed previously> (optional)
    (as returned by a previous push request or by  get_patient_id request; when provided, an existing patient will be updated)

Response: JSON structured as follows:

{
   success: true,
   patient_guid: <GUID>, //internal id of the patient object within the system. It is guaranteed to stay the same even when patient is renamed/patient id is changed, and can be used to update an existing patient when pushing
  patient_id: <string>, //assigned PhenomeCentral patient id, e.g. P0000xxx
  patient_url: "https://phenomecentral.org/P0000xxx" //complete URL which can be used to view the created patient
}

Note on patient_json

Not all the fields described in the patient JSON format are needed, some will be discarded when pushing the data. The following fields are recommended:

  • external_id: usually the identifier of the record on the platform that pushes the data
  • sex: the patient's biological sex
  • date_of_birth: the patient's (obfuscated) date of birth
  • global_age_of_onset: age of onset of most symptoms (HPO term)
  • global_mode_of_inheritance: either suspected or confirmed mode of inheritance (HPO term)
  • features: phenotypes (HPO terms); USED IN MATCHING
  • genes: candidate or confirmed causative genes (HGNC symbols); USED IN MATCHING
  • disorders: (known disorders (OMIM ids)

Sample patient JSON:

{
 "external_id": "PUSHTEST123",
 "sex": "F",
 "date_of_birth": "2007-06-01",
 "global_age_of_onset": [{
   "id": "HP:0011463",
   "label": "Childhood onset"
  }],
 "global_mode_of_inheritance": [{
   "id": "HP:0000006",
   "label": "Autosomal dominant inheritance"
  }],
 "features": [{
   "id": "HP:0004325",
   "label": "Decreased body weight",
   "type": "phenotype",
   "observed": "yes"
  }, {
   "id": "HP:0000256",
   "label": "Macrocephaly",
   "type": "phenotype",
   "observed": "no"
  }],
 "genes": [{
   "gene": "VN1R3",
   "status": "candidate"
   }],
 "disorders": [{
   "id": "MIM:306700",
   "label": "#306700 HEMOPHILIA A; HEMA"
  }]
}

Error responses

In case the requests described above result in an error (on the application level), the response will be structured as follows:

{
   success: false
  <error_key_1>: true,
  <error_key_2>: true,
   ...
}

The success field will be set to false, and one or more of the following error keys will be set to true to indicate the error reason:

  • action_failed - the requested action failed for any reason
  • login_failed - login failed for any reason
  • unsupported_post_protocol_version - push protocol is not supported by the server
  • incorrect_credentials - username/password combo is incorrect
  • unauthorized_server - target server does not allow pushing from this server (PC accepts all servers?)
  • unsupported_action - specified action is incorrect (not one of "get_server_info", "push", and a few others)
  • missing_consent - a required consent was no set, push request is denied
  • incorrect_user_group - user group specified for pushing is not valid (does not exist or the user does not belong to the group)

For example:

{
 "success": false,
 "incorrect_credentials": true,
 "login_failed": true,
 "response_protocol_version": "1.2"
}

Availability

PhenoTips® is freely available under the terms of the the GNU Affero General Public License, version 3.0.

 Download the latest release
 Play with our demo
 Get the source code

Contact

 Ask for free support (by volunteers):
support@phenotips.org
 Inquire about commercial support:
info@gene42.com
 Follow us on twitter:
@phenotips

PhenoTips® is an exclusive trademark of Gene42 Inc.