Overview

Introduction

The ImmPort FHIR program is advancing data interoperability through the translation of ImmPort shared data to FHIR (Fast Healthcare Interoperability Resources) format. FHIR data is commonly used in clinical care and, while its application in research is new and not widely adopted, it may be considered one potential solution to address data interoperability challenges. Adoption of FHIR in ImmPort expands the potential community of data consumers to include clinicians and researchers already using FHIR data while providing an easily accessible interface for novice users to learn about FHIR.

The goals of the FHIR program include:

enhanced data interoperability,
streamline data submission, download and reuse, and
encourage a new community of data providers and consumers to explore the use of FHIR for research.

Further information on FHIR may be found at: https://fhir.org/

FHIR Server

Version Details

Artifact	Version
Server	HAPI FHIR R5 Server
Software	HAPI FHIR Server - 5.6.0-PRE2-SNAPSHOT/28cc51393b/2021-09-03
FHIR Base	https://fhir.immport.org/fhir

ImmPort FHIR Mappings

Current Mappings

FHIR Term	ImmPort Templates/Terms
Observation	Lab Test Component, Assessments Component
Specimen	Subject, Biosample: type
Patient	Subject (Human): gender, race, ehtinicity
ResearchSubject	Linking Identifiers of Study, Subject, and Arm/cohort
DiagnosticReport	Lab Tests Panel, Assessments Panel, and link to the components
PractitionerRole	Study Personnel
Group	Subject: species, arm name, arm type
Organization	Study Personnel
Practitioner	Study Personnel
ResearchStudy	Basic Study Design

Future Mappings

FHIR Terms currently in the process of being mapped ImmPort Model:

Study Intervention Agent
Study Protocol
Intervention Agent
Age at enrollment of the subject with a range
Subject phenotype
Planned Visits
Mechanistic Assays

Authentication

REST API

ImmPort FHIR API Base URL

https://fhir.immport.org/fhir

ImmPort FHIR API endpoints are all secured and require an ImmPort JWT token for authentication and authorization. An ImmPort token can be obtained by sending a request to the following authentication endpoint with ImmPort username and password credentials. If you do not have an account, you can easily register with your email address here: ImmPort Registration.

ImmPort JWT Token Endpoint

https://www.immport.org/auth/token

Shell Command

curl -X POST https://www.immport.org/auth/token -d username="REPLACE_WITH_USERNAME" -d password="REPLACE_WITH_PASSWORD"

Sample Output

{
"status" : 200,
"access_token" : "Example-OiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MjMzNTE5NDMsInVzZXJfbmFtZSI6ImNhbXBqbyIsImF1dGhvcml0aWVzIjpbIlJPTEVfVVNFUiIsIlJPTEVfQ1VSQVRJT05fVVNFUiIsIlJPTEVfQURNSU4iLCJST0xFX0lNTVBPUlRfREFUQV9NQU5BR0VNRU5UX0FETUlOIiwiUk9MRV9VU0VSX0FETUlOSVNUUkFUSU9OX0FETUlOIiwiUk9MRV9TSEFSSU5HX1VTRVIiLCJST0xFX0RBVEFfQlJPV1NFUl9BRE1JTiJdLCJqdGkiOiI1ZjFkMzQ3Mi03MWU5LTQ0ODUtYjQ2Zi0wM2E4MGY2Mjk4NDUiLCJjbGllbnRfaWQiOiJpbW1wb3J0LWF1dGgtdG9rZW4tY2xpZW50Iiwic2NvcGUiOlsiYnJvd3NlIiwiZG93bmxvYWQiXX0.PC9vinTYFffEMvD3UXrOq2X6DuQF_8I3HpfuzHw2EG-j8c9GufCChgRieLhmqJ8_K9ngLe_sHzvyWN6GOofUPDr5AQOGYDxurhDzWhLD58841uOQYEhbZtVF0FcO84Ybi1ld_Zgj0Rhauv2jjvZJj-vakANOndEQtsIVmMSKLcnJ93Zk8_Mxtt35yxphZOizbYMmbq8tOy40vGF4O8yHLGgJS-SEebD7shiE7DoWFW5urKvyU6szIa0sz_i1oUoBJLtVeb3pW_lpgkQ3xo4-lCBgK2SkEvdq5g-So5cUNKzW619Tcznjs68z88droOX3gqu3oHxO4Z5Do824_2lzeA"
}

The token returned is a JWT token. JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object.

The token must be used to initiate a API request that requires authentication within 3600 seconds. After 3600 seconds the token will be invalid and the user will need to get a new token.

Sample API call

In the following example, an authentication token is saved as an environment variable (token) and passed to the HTTP header in the curl command to retrieve ELISA results data.

The first line is a POST to the authentication URL https://www.immport.org/auth/token with the username and password to get an authentication token. The fgrep command is used search the response for a token and then assign the value of the token to an environment variable named "token".

The second line is a GET on the URL https://fhir.immport.org/fhir/ResearchStudy/SDY1. The authentication token ("token") is passed in the HTTP header as shown.

The response will return the ResearchStudy FHIR resource for the ImmPort study with accession "SDY1". The default format of the response is JSON.

The above shell script or any code starting with #!/bin/bash can be copied to a .sh file (e.g. getImmPortFhirData.sh )and executed at the command prompt of a terminal and the output can be directed to a file. (Please replace the REPLACE_WITH_USERNAME with your username and REPLACE_WITH_PASSWORD with your password.)

#!/bin/bash

export token=`curl -X POST https://www.immport.org/auth/token -d username="REPLACE_WITH_USERNAME" -d password="REPLACE_WITH_PASSWORD" 2>&1  | fgrep '"access_token"' | sed -e 's/^.*"access_token":"//;s/".*$//'`

curl -k -H "Authorization: bearer $token" "https://fhir.immport.org/fhir/ResearchStudy/SDY1"

Sample Output

{
"resourceType": "ResearchStudy",
"id": "SDY1",
"meta": {
  "versionId": "6",
  "lastUpdated": "2023-05-18T18:29:34.501+00:00",
  "source": "#RFILCehHooeDA5Jw"
},
"identifier": [ {
  "use": "official",
  "type": {
    "coding": [ {
      "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
      "code": "ACSN",
      "display": "Accession ID"
    } ]
  },
  "value": "SDY1"
}, {
  "use": "official",
  "value": "10.21430/M38Y09R3R9"
} ],
"version": "DR21",
"title": "Efficacy and Safety Evaluation of Allergen Immunotherapy Co-Administered with Omalizumab (an anti-IgE Monoclonal Antibody)",
"label": [ {
  "type": {
    "coding": [ {
      "code": "short"
    } ]
  },
  "value": "Efficacy and Safety Evaluation of Allergen Immunotherapy Co-Administered with Omalizumab (an anti-IgE Monoclonal Antibody) (ITN019AD)"
} ],
"relatedArtifact": [ {
  "type": "citation",
  "label": "Clinicaltrials.gov",
  "url": "http://clinicaltrials.gov/ct2/show/NCT00078195"
}, {
  "type": "citation",
  "label": "ImmuneTolerance.org",
  "url": "http://www.immunetolerance.org/studies/efficacy-and-safety-evaluation-allergen-immunotherapy-co-administered-with-omalizumab-anti-i"
} ],
"status": "active",
"category": [ {
  "text": "Clinical Trial"
} ],
"focus": [ {
  "productCode": {
    "coding": [ {
      "system": "https://uts.nlm.nih.gov/uts/umls/concept",
      "code": "C0966225",
      "display": "omalizumab "
    } ],
    "text": "error (Typo): Omilazumab"
  },
  "focusType": [ {
    "coding": [ {
      "system": "http://hl7.org/fhir/ValueSet/research-study-focus-type",
      "code": "intervention",
      "display": "Intervention"
    } ],
    "text": "intervention"
  } ]
} ],
"condition": [ {
  "coding": [ {
    "system": "http://purl.obolibrary.org/obo",
    "code": "DOID_4481",
    "display": "allergic rhinitis"
  } ],
  "text": "allergic rhinitis"
} ],
"descriptionSummary": "A series of allergy shots may reduce symptoms of seasonal ragweed allergies. This study will determine whether taking a drug called omalizumab (also known as Xolair) before getting the allergy shots is more effective than allergy shots alone or other treatments, such as prescription antihistamines.",
"description": "<p>Allergic rhinitis affects 20 to 40 million Americans annually. Allergy symptoms, which can range from mild to seriously debilitating, may affect quality of life. Left untreated, allergic rhinitis can exacerbate or trigger more serious conditions, such as asthma and sinus inflammation.</p><p>Individuals with allergies react to harmless particles such as dust or pollen. Proteins in the blood called IgE antibodies treat the harmless particles as invaders and trigger an immune system response. The immune response results in harmful inflammation of healthy tissues. In ragweed allergy, inflammation occurs in the airways and causes familiar allergy symptoms like sneezing, coughing, and general discomfort.</p><p>Omalizumab is an investigational drug that has been shown to block the effects of IgE antibodies. The blocking effect of omalizumab is temporary, but giving the drug to people before their regular allergy shots may make the shots more effective.</p><p>Participants in this study will be randomly assigned to receive injections of omalizumab or a placebo before an accelerated course of allergy shots (given over 12 weeks). The participants will return for follow-up for up to one year, and they may have as many as 27 study visits.</p>",
"period": {
  "start": "2003-04-01"
},
"associatedParty": [ {
  "name": "Dr. Thomas Casale MD",
  "role": {
    "coding": [ {
      "system": "http://purl.obolibrary.org/obo/OBI_0000103",
      "code": "697",
      "display": "Principal Investigator"
    } ],
    "text": "Principal Investigator"
  },
  "party": {
    "reference": "PractitionerRole/496140",
    "type": "PractitionerRole"
  }
}, {
  "name": "NIAID",
  "role": {
    "coding": [ {
      "system": "http://hl7.org/fhir/research-study-party-role",
      "code": "sponsor",
      "display": "Sponsor"
    } ],
    "text": "Sponsor"
  },
  "party": {
    "reference": "Organization/34515",
    "type": "Organization"
  }
} ],
"recruitment": {
  "targetNumber": 168,
  "actualNumber": 159
},
"comparisonGroup": [ {
  "identifierIdentifier": {
    "use": "official",
    "type": {
      "coding": [ {
        "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
        "code": "ACSN",
        "display": "Accession ID"
      } ]
    },
    "value": "ARM1"
  },
  "name": "Placebo Immunotherapy with placebo anti-IgE",
  "description": "Placebo omalizumab pre-treatment, placebo RIT, placebo omalizumab + placebo IT",
  "observedGroup": {
    "reference": "Group/ARM1"
  }
}, {
  "identifierIdentifier": {
    "use": "official",
    "type": {
      "coding": [ {
        "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
        "code": "ACSN",
        "display": "Accession ID"
      } ]
    },
    "value": "ARM2"
  },
  "name": "Immunotherapy with placebo anti-IgE",
  "description": "Placebo omalizumab pre-treatment, ragweed RIT, placebo omalizumab + ragweed IT",
  "observedGroup": {
    "reference": "Group/ARM2"
  }
}, {
  "identifierIdentifier": {
    "use": "official",
    "type": {
      "coding": [ {
        "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
        "code": "ACSN",
        "display": "Accession ID"
      } ]
    },
    "value": "ARM3"
  },
  "name": "Placebo Immunotherapy with anti-IgE",
  "description": "Omalizumab pre-treatment, placebo RIT, omalizumab + placebo IT",
  "observedGroup": {
    "reference": "Group/ARM3"
  }
}, {
  "identifierIdentifier": {
    "use": "official",
    "type": {
      "coding": [ {
        "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
        "code": "ACSN",
        "display": "Accession ID"
      } ]
    },
    "value": "ARM4"
  },
  "name": "Immunotherapy with anti-IgE",
  "description": "Omalizumab pre-treatment, ragweed RIT, omalizumab + ragweed IT",
  "observedGroup": {
    "reference": "Group/ARM4"
  }
} ],
"objective": [ {
  "name": "<p><b>Primary Objective: </b></p><p>To examine whether omalizumab given prior to RIT followed by 12 weeks of dual omalizumab and IT is more effective than RIT followed by IT alone in preventing the symptoms of ragweed-induced SAR. </p><p><b>Secondary Objective: </b></p><p>To examine whether omalizumab given prior to RIT followed by 12 weeks of dual omalizumab and IT is safe and more effective than omalizumab alone or placebo in preventing the symptoms of ragweed-induced SAR; to assess the immunologic mechanisms associated with the therapies; and to assess whether clinical tolerance has been achieved after discontinuation of the therapies.</p><p>Allergic rhinitis affects 20 to 40 million Americans annually. Allergy symptoms, which can range from mild to seriously debilitating, may affect quality of life. Left untreated, allergic rhinitis can exacerbate or trigger more serious conditions, such as asthma and sinus inflammation.</p><p>Individuals with allergies react to harmless particles such as dust or pollen. Proteins in the blood called IgE antibodies treat the harmless particles as invaders and trigger an immune system response. The immune response results in harmful inflammation of healthy tissues. In ragweed allergy, inflammation occurs in the airways and causes familiar allergy symptoms like sneezing, coughing, and general discomfort.</p><p>Omalizumab is an investigational drug that has been shown to block the effects of IgE antibodies. The blocking effect of omalizumab is temporary, but giving the drug to people before their regular allergy shots may make the shots more effective.</p><p>Participants in this study will be randomly assigned to receive injections of omalizumab or a placebo before an accelerated course of allergy shots (given over 12 weeks). The participants will return for follow-up for up to one year, and they may have as many as 27 study visits.</p>"
} ],
"outcomeMeasure": [ {
  "description": "<p><b>Primary Objective: </b></p><p>To examine whether omalizumab given prior to RIT followed by 12 weeks of dual omalizumab and <p><b>Primary Endpoint:</b></p><p>The primary endpoint will be the average daily allergy severity score, which will be calculated from 5 symptom scores of participants</p> <ul><li>sneezing; </li><li>rhinorrhea/runny nose;</li><li>itchy nose, throat, and palate;</li><li>itchy, watery eyes;</li><li>nasal congestion/stuffiness</li></ul>during the 2003 ragweed pollen season.<p>Symptom scores are recorded twice daily (AM and PM). </p><p>The ragweed pollen season begins when the ragweed pollen counts rise to 10 ragweed pollen grains/m<sup>3</sup>/24 hours or above on two consecutive recorded days, and the ragweed pollen season ends when the ragweed pollen counts fall below 10 ragweed pollen grains/m<sup>3</sup>/24 hours on two consecutive recorded days. The ragweed pollen season is from approximately August 15, 2003 to October 1, 2003, but varies among the sites. </p><p>The sum of the individual symptom scores will be averaged over AM and PM to give a daily score. Each daily score will then be averaged to obtain one measure of the average daily allergy severity score for each participant. </p><p><b>Secondary Endpoint: </b></p><ol><li>The incidence and severity of adverse events;</li><li>Number of days with rescue medication use during the 2003 ragweed season;</li><li>Number of rescue medication capsules (fexofenadine HCl 60 mg) used during the 2003 ragweed season;</li><li>Rhinoconjunctivitis QOL questionnaire (RQLQ) scores during the 2003 ragweed season;</li><li>Daily AM allergy symptom scores during the 2003 ragweed season;</li><li>Daily PM allergy symptom scores during the 2003 ragweed season; and</li><li>Individual allergy symptom scores during the 2003 ragweed season.</li></ol>IT is more effective than RIT followed by IT alone in preventing the symptoms of ragweed-induced SAR. </p><p><b>Secondary Objective: </b></p><p>To examine whether omalizumab given prior to RIT followed by 12 weeks of dual omalizumab and IT is safe and more effective than omalizumab alone or placebo in preventing the symptoms of ragweed-induced SAR; to assess the immunologic mechanisms associated with the therapies; and to assess whether clinical tolerance has been achieved after discontinuation of the therapies.</p><p>Allergic rhinitis affects 20 to 40 million Americans annually. Allergy symptoms, which can range from mild to seriously debilitating, may affect quality of life. Left untreated, allergic rhinitis can exacerbate or trigger more serious conditions, such as asthma and sinus inflammation.</p><p>Individuals with allergies react to harmless particles such as dust or pollen. Proteins in the blood called IgE antibodies treat the harmless particles as invaders and trigger an immune system response. The immune response results in harmful inflammation of healthy tissues. In ragweed allergy, inflammation occurs in the airways and causes familiar allergy symptoms like sneezing, coughing, and general discomfort.</p><p>Omalizumab is an investigational drug that has been shown to block the effects of IgE antibodies. The blocking effect of omalizumab is temporary, but giving the drug to people before their regular allergy shots may make the shots more effective.</p><p>Participants in this study will be randomly assigned to receive injections of omalizumab or a placebo before an accelerated course of allergy shots (given over 12 weeks). The participants will return for follow-up for up to one year, and they may have as many as 27 study visits.</p>"
} ],........

Web App

ImmPort FHIR Web App

https://fhir.immport.org

FHIR server web client is secured by the ImmPort authentication service using the Authorization code workflow of the OAuth2/OIDC protocol. Users will be redirected to the ImmPort login page when accessing any secured web page on the FHIR server. Please login to the server using your ImmPort credentials to proceed. If you do not have an account, you can easily register with your email address here: ImmPort Registration.

ImmPort FHIR Server login screen