Quick start guide (researchers)


The most current reference implementation of the Medication Safety Code System is available as a REST API at http://safety-code.org/msc3/. When you visit that link, you should see the message “Welcome to the Medication Safety Code!”. To start using it, just follow the steps outlined in the Quickstart section below. For further information, please refer to the API documentation available at http://safety-code.org/msc3/api-docs/.

Quick Start Guide

Pharmacogenomic profiles

The most important resource available via the MSC system is the profile page for an anonymous pharmacogenetic profile. Have a look at the description to see what it is, or start with a simple example.


A pharmacogenomic profile URL looks like this:


The variable parts of the URL {assay} and {profile} are explained below. Both of them are represented using this modified Base64 character set of digits:


The {assay} part is a two-digit identifier for the assay used to conduct the pharmacogenomic test. You can ignore this and just use 00 (i.e. zero-zero, the default value), as the assay does not have any effect on the resulting page at the moment.

The {profile} part is more interesting, as it represents the pharmacogenomic test results. There are three types of entities represented in this part of the URL:

Type Description Representation Examples
Gene A gene that was part of the conducted pharmacogenetic test. Phenotypes and Haplotypes are reported on a per-gene basis. 1 x 1-digit Base64 String TPMT, CYP2C9, CYP2C19, VKORC1
Phenotype The phenotype result from the pharmacogenetic test. One phenotype per gene.  1 x 1-digit Base64 String  Wild-type phenotype, High activity, Poor metabolizer
Haplotype The haplotype result from the pharmacogenetic test. Two haplotypes per gene. 2 x 2-digit Base64 String *1, *1A, *9, *39XN, *VII, Mediterranean Haplotype

Thus, the data for each gene is encoded into a 6-digit block: 1 digit for the gene, 1 digit for the phenotype, and 2 digits for the first and second haplotype, respectively. The concatenation of these per-gene blocks gives you the full profile part of the URL. The process is summarized in the image below:


The identifiers for genes, phenotypes and haplotypes can be found in the genes.properties, phenotypes.properties and haplotypes.properties files, respectively, which are located in our GitLab repository. For genes, the values in the property file refer to the URL part representing that gene. For phenotypes and haplotypes, the URL part is represented as the urlFragment attribute. To see the MSC system in action, continue with the simple example below or have a look at the demo profile.


Here is a simple example for a profile page:



Open the link to be presented with a HTML page showing the medication recommendations for a patient with a “Poor metabolizer” phenotype for the TPMT gene. The TPMT gene encodes for the Thiopurine methyltransferase protein, which is an enzyme with an important role in the metabolism of thiopurine drugs such as azathioprine or mercaptopurine. Accordingly, the page for this patient profile shows recommendations for the usage of these drugs. Click or tap on any of them to show the related information, including the specific recommendation text, the reason why this recommendation applies to this profile, a link to the guideline in PharmGKB and the last time this guideline was updated in the MSC system.

You can also view the pharmacogenomic data that is encoded in the link by expanding the “Show pharmacogenomic data” section: as you can see, the example link only includes data for the TPMT gene with the “Poor metabolizer” phenotype. Additionally, the URL includes information about the two haplotypes of that gene, namely *2 and *3A.

Pocket cards

A pocket card is a business card sized summary of the recommendations for a pharmacogenetic profile. The pocket card for the example profile above can be found here:


As you can see, the pocket card includes the same information as the profile page, but in a condensed format suitable for printing and carrying around. Scanning the QR code on the front will take you to the profile page with the detailed guidelines.

As you can see, the pocket card above is anonymous, just like the profile page. However, the pocket card can be individualized via URL parameters to include patient-specific information:

URL parameter Description Example
lab Contact information of the laboratory where the pharmacogenetic test was conducted. Should be no more than 4 lines. %2B0123456789%0A
name  The name of the patient. John%20Wayne
birthday The patient’s date of birth. 01.02.1934
cardnumber The card number, which can be used internally. 0000001
date The date the card was printed. If not included, defaults to the current date. 21.12.2015

Note that URLs use the ASCII character set, and special characters have to be URL encoded. For example, a space in a URL is encoded as %20.

Here is what the link to the example pocket card would look like with all parameters set:


For contributors

The repository for the Java-based Medication Safety Code reference implementation is available at https://gitlab.com/medication-safety/msc-server. The internal Javadocs are publicly available at http://safety-code.org/msc3/docs/.