GeneMatcher API
1.0
Overview:
GeneMatcher provided a REST based API to for submitting new submissions as well as updating existing submissions, suspending existing submissions, and deleting existing submissions.
1.1
API Key
An account is required if you want to use the API. You can create an account if you have not already done so, making sure you generate an API key in the process. If you already have an account and have not generated an API key, you can easily do so on your account information page.
The API key is for your own use, please do not share it as it enables access to create/update submissions without having to log into GeneMatcher. If you suspect that your API key has been compromised, you can very easily create a new one on your account information page.
The API key has to be included in the HTTP headers with every request using the 'X-Auth-Token' header. Requests whose API key is missing or invalid are automatically rejected. GeneMatcher only allows access over secured HTTP so the content of every request and response is encrypted and the API key which is transmitted with every request is never sent 'in the clear' over the Internet.
1.2
Request Headers & Data Formats
Two HTTP headers are required in every request, the 'X-Auth-Token' header which is used for the API key, and the 'Content-type' which is used to specify the request content type / version.
The 'X-Auth-Token' header and API key would look like this:
X-Auth-Token: FFFF
Only one content type / version is currently supported:
application/vnd.jhu.genematcher.v2.0+json
application/vnd.jhu.genematcher.v2.0+json; charset=utf-8
The 'Content-type' header and content type would look like this:
Content-type: application/vnd.jhu.genematcher.v2.0+json
1.3
Operations
The API supports three operations.
- A ping operation to check that the API key is working correctly.
- A submit operation to create new submissions as well as updating existing submissions.
- An activate operation to activate submissions (that are suspended).
- A suspend operation to suspend submissions (that are active)
- A delete operation to delete submissions.
1.4
Ping Operation
The ping operation is done using the GET method.
The url for the ping operation is (note the 'https'):
https://genematcher.org/api/ping
Various HTTP statuses are returned depending on the validation failure, and a text response message providing more information will be included. The various HTTP statuses are listed in section 1.9 below.
1.5
Submit Operation
The submit operation is done using the POST method to create a new submission, and using the PUT method to update an existing submission.
The url for the submit operation is (note the 'https'):
https://genematcher.org/api/submit
The content is formatted using JSON.
Submission fields are validated when creating and updating submissions, and invalid submissions are rejected. Various HTTP statuses are returned depending on the validation failure, and a text response message providing more information will be included. The various HTTP statuses are listed in section 1.9 below.
A submission ID is returned when a new submission is successfully created. This submission ID must be saved and included in the request when updating that submission.
You need to specify submitter information if you are entering this data on behalf of someone else. If you enter submitter information only they will be contacted if a match is made, otherwise you will be contacted.
Updates overwrites all existing data in a submission, updates to individual fields is not supported.
Submitting a submission to the database will cause it to be matched to other submissions and notifications will be sent out to other submitters.
A 'test' flag can be set which indicates that the submission should be parsed and validated only, it will not be stored in the database and it will not be matched against other submissions. The sample submission below demonstrates how to set the 'test' flag. You must use this flag to test your implementation.
Fields are as follows (fields are optional unless noted as required):
| Field Name | Description |
|---|---|
| identifier | The identifier (required) |
| submissionID | The submission ID (to update an existing submission) |
| submitterEmail | The submitter email |
| submitterFirstName | The submitter first name |
| submitterLastName | The submitter last name |
| submitterInstitution | The submitter institution |
| disorderList | The disorder list |
| inheritance | The inheritance (See table below for valid values) |
| organism | The organism (See table below for valid values) |
| familyMemberList | A list of family members (See table below for fields) |
| resultList | A list of results (See table below for fields) |
| mimMatchType | The OMIM disease match type, defaults to 'o' (See table below for valid values) |
| geneMatchType | The gene match type, defaults to 'r' (See table below for valid values) |
| locationMatchType | The location match type, defaults to 'o' (See table below for valid values) |
| featureMatchType | The phenotypic feature match type, defaults to 'i' (See table below for valid values) |
| featureMatchCoefficient | The phenotypic feature match coefficient - 1.00 to 0.05 (0.80 is the default) |
| researcherMatchType | The researcher match type, defaults to 'i' (See table below for valid values) |
| moresearcherMatchType | The model organism researcher match type, defaults to 'i' (See table below for valid values) |
| providerMatchType | The provider match type, defaults to 'i' (See table below for valid values) |
| patientMatchType | The patient match type, defaults to 'i' (See table below for valid values) |
| matchMakerExchangeMatch | To submit the submission to Matchmaker Exchange for matching (See table below for fields) |
Inheritance Values:
| Inheritance Value | Description |
|---|---|
| 'ad' | Autosomal dominant |
| 'ar' | Autosomal recessive |
| 'xd' | X-linked dominant |
| 'yr' | X-linked recessive |
| 'yl' | Y-linked |
| 'mi' | Mitochondrial |
| 'ic' | Isolated cases |
| 'un' | Unknown disorder |
Organism Values:
| Organism Value | Description |
|---|---|
| 8355 | African clawed frog / Xenopus laevis |
| 4754 | Ascomycetes / Pneumocystis carinii |
| 4932 | Baker's yeast / Saccharomyces cerevisiae |
| 9913 | Cattle / Bos taurus |
| 44689 | Cellular slime molds / Dictyostelium discoideum |
| 562 | Enterobacteria / Escherichia coli |
| 4896 | Fission yeast / Schizosaccharomyces pombe |
| 7227 | Fruit fly / Drosophila melanogaster |
| 3055 | Green algae / Chlamydomonas reinhardtii |
| 11103 | Hepatitis C virus / Hepatitis C virus |
| 10090 | House mouse / Mus musculus |
| 9606 | Human / Homo sapiens |
| 5833 | Malaria parasite P. falciparum / Plasmodium falciparum |
| 4577 | Monocots / Zea mays |
| 2104 | Mycoplasma / Mycoplasma pneumoniae |
| 6239 | Nematodes / Caenorhabditis elegans |
| 10116 | Norway rat / Rattus norvegicus |
| 4530 | Rice / Oryza sativa |
| 3702 | Thale cress / Arabidopsis thaliana |
| 31033 | Torafugu / Takifugu rubripes |
| 8364 | Western clawed frog / Xenopus tropicalis |
| 7955 | Zebrafish / Danio rerio |
Disorder:
| Field Value | Description |
|---|---|
| disorderType | The disorder type (See table below for valid values) |
| mimNumberList | The MIM number list, validated against OMIM |
| presumedLocus | The presumed locus (for 'l' type disorders) |
| unknownDisorder | The unknown disorder (for 'u' type disorders) |
Disorder Type Values:
| Disorder Type Value | Description |
|---|---|
| 'm' | Mendelian disorder described in OMIM |
| 'l' | Mendelian disorder with locus heterogeneity |
| 'u' | Unknown disorder |
Family member:
| Field Value | Description |
|---|---|
| relationship | The relationship (required) |
| sex | The sex, 'male/m' or 'female/f' |
| affected | The affected state, 'yes/y', 'no/n', 'unknown/unk/u' |
| deceased | deceased, 'yes/y', 'no/n' |
| deathAge | The age of death (See table below for valid values) |
| featureList | A list of phenotypic features (See table below for fields) |
Death Age Values:
| Death Age Value | Description |
|---|---|
| 'n' | Neonatal death (first 28 days of life) |
| 'i' | Death in infancy (first 24 months of life) |
| 'c' | Death in childhood (2 to 10 years) |
| 'a' | Death in adolescence (10 to 19 years) |
| 'e' | Death in early adulthood (20 to 25 years) |
Phenotypic Feature:
| Field Name | Description |
|---|---|
| featureID | The phenotypic feature ID (Required) |
| featureValue | The phenotypic feature value, 'a', 'n', 'u', 'l', 'r', 'b', 'i' |
Phenotypic Feature Values:
| Phenotypic Feature Value | Description |
|---|---|
| 'a' | abnormal |
| 'n' | normal |
| 'u' | unknown |
| 'l' | left |
| 'r' | right |
| 'b' | bilateral |
| 'u' | unilateral |
Match Type:
| Match Type | Description |
|---|---|
| 'i' | Ignored - means that the field is ignored when matching. |
| 'o' | Optional - means that this field will be queried but is not required for a match. |
| 'r' | Required - means that a match on that field is required to match this submission. |
Matchmaker Exchange Match:
| Field Value | Description |
|---|---|
| submitMIM | Submit MIM numbers, boolean |
| submitGene | Submit gene symbols, boolean |
| submitLocation | Submit genomic locations, boolean |
| submitFeature | Submit phenotypic features, boolean |
| resubmitPeriod | resubmission period, 'monthly' |
| matchmakerExchangeServerList | The list of Matchmaker Exchange servers to submit to (See table below for fields) |
Matchmaker Exchange Server List:
| Field Value | Description |
|---|---|
| Broad Matchbox | Broad Matchbox |
| DECIPHER | DECIPHER |
| MyGene2 | MyGene2 |
| PhenomeCentral | PhenomeCentral |
Result (human genes only, maximum of 10 genes only):
| Field Name | Description |
|---|---|
| geneSymbol | Gene symbol, validated against HGNC approved gene symbols |
| ensemblGeneID | Ensembl Gene ID |
| entrezGeneID | Entrez Gene ID |
| chromosome | Chromosome, 1-22,X,Y |
| startPosition | Start position, as a genomic location |
| endPosition | End position, as a genomic location |
| zygosity | The zygosity (See table below for valid values) |
| refgeneExonFunction | The refgene exon function (See table below for valid values) |
| inheritanceModel | The inheritance model (See table below for valid values) |
| assembly | The assembly, 'NCBI36', 'GRCh37' or 'GRCh38', defaults to 'GRCh37' if start position is set |
Zygosity Values:
| Zygosity Value | Description |
|---|---|
| 'het' | Heterozygous |
| 'hom' | Homozygous |
| 'hem' | Hemizygous |
| 'mos' | Mosaic |
Refgene Exon Function Values:
| Refgene Exon Function Values | Description |
|---|---|
| 'fsd' | Frameshift deletion |
| 'fsi' | Frameshift insertion |
| 'fss' | Frameshift substitution |
| 'nfsd' | Nonframeshift deletion |
| 'nfsi' | Nonframeshift insertion |
| 'nfss' | Nonframeshift substitution |
| 'ss' | Synonymous SNV |
| 'nss' | Nonsynonymous SNV |
| 'sgs' | Stopgain SNV |
| 'sls' | Stoploss SNV |
| 'sg' | Stopgain |
| 'sl' | Stoploss |
| 's' | Splicing |
| 'u' | Unknown |
Inheritance Model Values:
| Inheritance Model Value | Description |
|---|---|
| 'arch' | Autosomal recessive - Compound heterozygous |
| 'arh' | Autosomal recessive - Homozygous |
| 'ad' | Autosomal dominant |
| 'adnm' | Autosomal dominant - New mutation |
| 'adim' | Autosomal dominant - Inherited mutation |
| 'xlr' | X-Linked recessive |
| 'xld' | X-Linked dominant |
| 'pi' | Paternal imprinting |
| 'mi' | Maternal imprinting |
This sample JSON submission would create a new submission because there is no submission ID (note the use of the 'test' flag):
{
"phenoDB" : {
"test" : true,
"submission" : {
"identifier" : "CPD1018",
"submitterEmail" : "[email protected]",
"submitterFirstName" : "John",
"submitterLastName" : "Doe",
"submitterInstitution" : "Medical Center",
"mimMatchType" : "o",
"geneMatchType" : "r",
"locationMatchType" : "o",
"featureMatchType" : "o",
"featureMatchCoefficient" : 0.95,
"matchMakerExchangeMatch" : {
"submitMIM" : false,
"submitGene" : true,
"submitLocation" : false,
"submitFeature" : true,
"resubmitPeriod" : "monthly",
"serverList" : [
"BroadMatchbox",
"Decipher",
"PhenomeCentral",
"MyGene2"
]
},
"disorderList" : [
{
"disorderType" : "m",
"mimNumberList" : [
200150,
300200
]
},
{
"disorderType" : "l",
"mimNumberList" : [
300400,
300500
],
"presumedLocus" : "Presumed locus name"
},
{
"disorderType" : "u",
"mimNumber" : 700000,
"unknownDisorder" : "Unknown disorder name"
}
],
"inheritance" : "ar",
"familyMemberList" : [
{
"relationship" : "Patient",
"sex" : "male",
"affected" : "yes",
"featureList" : [
{
"featureID" : "phenodb:00001",
"featureValue" : "a"
},
{
"featureID" : "phenodb:00002",
"featureValue" : "a"
}
]
},
{
"relationship" : "Mother",
"sex" : "female",
"affected" : "yes"
},
{
"relationship" : "Father",
"sex" : "male",
"affected" : "unknown"
},
{
"relationship" : "Sister",
"sex" : "female",
"affected" : "unknown"
}
],
"resultList" : [
{
"geneSymbol" : "SCRN3",
"ensemblGeneID" : "ENSG00000144306",
"entrezGeneID" : "79634",
"chromosome" : "2",
"startPosition" : "175263171",
"endPosition" : "175263171"
},
{
"geneSymbol" : "SCRN3",
"ensemblGeneID" : "ENSG00000144306",
"entrezGeneID" : "79634",
"chromosome" : "2",
"startPosition" : "175292599",
"endPosition" : "175292611"
},
{
"geneSymbol" : "CNTLN",
"ensemblGeneID" : "ENSG00000044459",
"entrezGeneID" : "54875",
"chromosome" : "9",
"startPosition" : "17394994",
"endPosition" : "17394994"
},
{
"geneSymbol" : "CNTLN",
"ensemblGeneID" : "ENSG00000044459",
"entrezGeneID" : "54875",
"chromosome" : "9",
"startPosition" : "17486986",
"endPosition" : "17486986"
},
{
"geneSymbol" : "CUBN",
"ensemblGeneID" : "ENSG00000107611",
"entrezGeneID" : "8029",
"chromosome" : "10",
"startPosition" : "16996387",
"endPosition" : "16996387"
}
]
}
}
}
Sample JSON submission response:
{
"phenoDB" : {
"submissionID" : "33",
"submissionList" : [
{
"genomicCoordinateStarts" : "chr2:175263171, chr9:17394994, chr9:17486986, chr2:175292599, chr10:16996387",
"submissionID" : "8",
"identifier" : "CPD1018",
"dateUpdated" : "2016/05/01",
"submitterEmail" : "[email protected]",
"submitterInstitution" : "-",
"geneSymbols" : "SCRN3, CUBN, CNTLN",
"entrezGeneIDs" : "8029, 54875, 79634",
"submitterFirstName" : "Demo",
"submitterLastName" : "Account",
"ensemblGeneIDs" : "ENSG00000144306, ENSG00000044459, ENSG00000107611"
},
{
"genomicCoordinateStarts" : "chr2:175263171, chr9:17394994, chr9:17486986, chr2:175292599, chr10:16996387",
"submissionID" : "9",
"identifier" : "CPD1018",
"dateUpdated" : "2014/06/01",
"submitterEmail" : "[email protected]",
"submitterInstitution" : "-",
"geneSymbols" : "SCRN3, CUBN, CNTLN",
"entrezGeneIDs" : "8029, 54875, 79634",
"submitterFirstName" : "Demo",
"submitterLastName" : "Account",
"ensemblGeneIDs" : "ENSG00000144306, ENSG00000044459, ENSG00000107611"
},
{
"genomicCoordinateStarts" : "chr2:175263171, chr9:17394994, chr9:17486986, chr2:175292599, chr10:16996387",
"submissionID" : "10",
"identifier" : "CPD1031",
"dateUpdated" : "2015/04/16",
"submitterEmail" : "[email protected]",
"submitterInstitution" : "-",
"geneSymbols" : "SCRN3, CUBN, CNTLN",
"entrezGeneIDs" : "8029, 54875, 79634",
"submitterFirstName" : "Demo",
"submitterLastName" : "Account",
"ensemblGeneIDs" : "ENSG00000144306, ENSG00000044459, ENSG00000107611"
}
]
}
}
1.6
Activate Operation
The activate operation is done using the PUT method.
The url for the activate operation is (note the 'https'):
https://genematcher.org/api/activate
And the 'submissionID' parameter, for example:
submissionID=34
The full url would be as follows:
https://genematcher.org/api/activate?submissionID=34
Various HTTP statuses are returned depending on the validation failure, and a text response message providing more information will be included. The various HTTP statuses are listed in section 1.9 below.
1.7
Suspend Operation
The suspend operation is done using the PUT method.
The url for the suspend operation is (note the 'https'):
https://genematcher.org/api/suspend
And the 'submissionID' parameter, for example:
submissionID=34
The full url would be as follows:
https://genematcher.org/api/suspend?submissionID=34
Various HTTP statuses are returned depending on the validation failure, and a text response message providing more information will be included. The various HTTP statuses are listed in section 1.9 below.
1.8
Delete Operation
The delete operation is done using the DELETE method.
The url for the delete operation is (note the 'https'):
https://genematcher.org/api/delete
And the 'submissionID' parameter, for example:
submissionID=34
The full url would be as follows:
https://genematcher.org/api/delete?submissionID=34
Various HTTP statuses are returned depending on the validation failure, and a text response message providing more information will be included. The various HTTP statuses are listed in section 1.9 below.
1.9
Response HTTP status codes
The API returns different HTTP status codes based on the outcome. A status of 200 / OK will contain a submission response described above, any other HTTP status is an error and the response will contain a message explaining why the error occurred.
The HTTP status codes are as follows:
| HTTP Status Code | Description |
|---|---|
| 200 / OK | Request completed with no errors |
| 400 / BAD_REQUEST | Missing or invalid data |
| 401 / UNAUTHORIZED | Missing or invalid API key |
| 405 / METHOD_NOT_ALLOWED | Invalid method |
| 406 / NOT_ACCEPTABLE | Unsupported API version |
| 415 / UNSUPPORTED_MEDIA_TYPE | Missing or invalid content type |
| 422 / UNPROCESSABLE_ENTITY | Missing or invalid request body |
| 500 / INTERNAL_SERVER_ERROR | Something really bad happened |
1.10
Code Library
You can download a code library (written in Python) that implements all these operations if you have an account.