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

The encoding character set can be specified using 'charset', however it is redundant since all requests and responses must be encoded using utf-8:

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.