Documentation
This DRAFT document outlines the RESTful API calls your application can make on behalf of users (i.e. beneficiaries ). An OAuth2 application client_id and a OAuth2 user token are required to execute these API calls. This API consists of these Functions:
- Get User's Profile Information as OpenIDConnect
- Get User's Profile Information as in FHIR®
- Get User's ExplanationOfBenefit Record(s) in FHIR®
- Get User's Patient Record in FHIR®
Get User Profile
HTTP GET /connect/userinfo
The above URL fetches the user's basic account information. This is most often used when creating an account within your application, An HTTP GET is called and the response is returned as JSON. A sample response is as follows:
{
"sub": "fflinstone",
"prefered_username": "fflinstone",
"given_name": "Fred",
"family_name:, "Flinstone,
"name": "Fred Flinstone",
"email": "pebbles-daddy@example.com",
"created": "2017-11-28",
}
Get User's ExplanationOfBenefit Record(s)
/bluebutton/fhir/v1/ExplanationOfBenefit/?patient=[sub][_format=json | _format=xml]
The ExplanationOfBenefit is an episode of care. The above URL returns the user's personal health information as an ExplanationOfBenefit FHIR resource according to DSTU3. The record identifier corresponding to "me" is set by the server so this value is arbitrary and therefore could be anything. As a security measure the date of birth, SSN, and HICN are not provided. If the "_format" option is omitted, then JSON is returned by default. Below is a sample JSON response:
{
"resourceType": "ExplanationOfBenefit",
"id": "EB3500",
"text": {
"status": "generated",
"div": "A human-readable rendering of the ExplanationOfBenefit"
},
"identifier": [
{
"system": "http://www.BenefitsInc.com/fhir/explanationofbenefit",
"value": "987654321"
}
],
"status": "active",
"type": {
"coding": [
{
"system": "http://hl7.org/fhir/ex-claimtype",
"code": "oral"
}
]
},
"patient": {
"reference": "Patient/pat1"
},
"created": "2014-08-16",
"organization": {
"reference": "Organization/2"
},
"claim": {
"reference": "Claim/100150"
},
"claimResponse": {
"reference": "ClaimResponse/R3500"
},
"outcome": {
"coding": [
{
"system": "http://hl7.org/fhir/remittance-outcome",
"code": "complete"
}
]
},
"disposition": "Claim settled as per contract.",
"careTeam": [
{
"sequence": 1,
"provider": {
"reference": "Practitioner/example"
}
}
],
"insurance": {
"coverage": {
"reference": "Coverage/9876B1"
}
},
"item": [
{
"sequence": 1,
"careTeamLinkId": [
1
],
"service": {
"coding": [
{
"system": "http://hl7.org/fhir/service-uscls",
"code": "1200"
}
]
},
"servicedDate": "2014-08-16",
"unitPrice": {
"value": 135.57,
"system": "urn:iso:std:iso:4217",
"code": "USD"
},
"net": {
"value": 135.57,
"system": "urn:iso:std:iso:4217",
"code": "USD"
},
"adjudication": [
{
"category": {
"coding": [
{
"code": "eligible"
}
]
},
"amount": {
"value": 120.00,
"system": "urn:iso:std:iso:4217",
"code": "USD"
}
},
{
"category": {
"coding": [
{
"code": "eligpercent"
}
]
},
"value": 0.80
},
{
"category": {
"coding": [
{
"code": "benefit"
}
]
},
"amount": {
"value": 96.00,
"system": "urn:iso:std:iso:4217",
"code": "USD"
}
}
]
}
],
"totalCost": {
"value": 135.57,
"system": "urn:iso:std:iso:4217",
"code": "USD"
},
"totalBenefit": {
"value": 96.00,
"system": "urn:iso:std:iso:4217",
"code": "USD"
}
}
Get User's Patient Record
HTTP GET /bluebutton/fhir/v1/Patient/[sub][?_format=json | ?_format=xml]
The above Patient URL returns the user's personal health information as a Patient FHIR resource according to DSTU3. The record identifier corresponding to "me" is set by the server so it is arbitrary. "me" could replaced with anything. If the _format option is omitted, then JSON is returned by default. As a security measure the date of birth, SSN, and HICN are not provided. Below is a sample JSON response:
.
{
"resourceType": "Patient",
"id": "example",
"text": {
"status": "generated",
"div": "\n \n \n \n \n \n \n \n Name \n \n Peter James \n Chalmers ("Jim")\n \n \n \n \n \n \n Address \n \n 534 Erewhon, Pleasantville, Vic, 3999 \n \n \n \n \n \n Contacts \n \n Home: unknown. Work: (03) 5555 6473 \n \n \n \n \n \n Id \n \n MRN: 12345 (Acme Healthcare) \n \n \n \n \n \n
\n \n "
},
"identifier": [
{
"use": "usual",
"type": {
"coding": [
{
"system": "http://hl7.org/fhir/v2/0203",
"code": "MR"
}
]
},
"system": "urn:oid:1.2.36.146.595.217.0.1",
"value": "12345",
"period": {
"start": "2001-05-06"
},
"assigner": {
"display": "Acme Healthcare"
}
}
],
"active": true,
"name": [
{
"use": "official",
"family": "Chalmers",
"given": [
"Peter",
"James"
]
},
{
"use": "usual",
"given": [
"Jim"
]
}
],
"telecom": [
{
"use": "home"
},
{
"system": "phone",
"value": "(03) 5555 6473",
"use": "work"
}
],
"gender": "male",
"birthDate": "1974-12-25",
"_birthDate": {
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/patient-birthTime",
"valueDateTime": "1974-12-25T14:35:45-05:00"
}
]
},
"deceasedBoolean": false,
"address": [
{
"use": "home",
"type": "both",
"line": [
"534 Erewhon St"
],
"city": "PleasantVille",
"district": "Rainbow",
"state": "Vic",
"postalCode": "3999",
"period": {
"start": "1974-12-25"
}
}
],
"contact": [
{
"relationship": [
{
"coding": [
{
"system": "http://hl7.org/fhir/patient-contact-relationship",
"code": "partner"
}
]
}
],
"name": {
"family": "du Marché",
"_family": {
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/humanname-own-prefix",
"valueString": "VV"
}
]
},
"given": [
"Bénédicte"
]
},
"telecom": [
{
"system": "phone",
"value": "+33 (237) 998327"
}
],
"address": {
"use": "home",
"type": "both",
"line": [
"534 Erewhon St"
],
"city": "PleasantVille",
"district": "Rainbow",
"state": "Vic",
"postalCode": "3999",
"period": {
"start": "1974-12-25"
}
},
"gender": "female",
"period": {
"start": "2012"
}
}
],
"managingOrganization": {
"reference": "Organization/1"
}
}
Authors and Contributors
@aviars @ekivemark @karldavis | Comments and pull request welcome :)
Support or Contact
Contact: Alan Viars @aviars , Mark Scrimshire @ekivemark , or Karl Davis @karldavis