Meridian FHIR API Documentation

Home

Getting started

Meridian FHIR Server is a read-only RESTful API, based on standards developed by HL7 in FHIR® STU 3. This documentation will guide to access your health resources.

Details of accessing FHIR Server is explained with the help of below mentioned sections.

Terms of Use

This section discusses the terms and conditions of using FHIR API Server.

Documentation of FHIR API Server and materials including the support of the FHIR® Specification (referred to as the "Materials") have been made available for development and testing. The Materials are provided to developers as-is with no other warranties expressed or implied. Developers may use the Materials with adherence to the below terms and conditions:

    terms and conditions
  • Meridian FHIR API Server has the most up-to-date documentation. Developers may keep copies of the Materials; however, they may not be distributed. Developers wishing to share the Materials may do so via linking other developers to the Materials hosted on the FHIR API Server.
  • Developers own developments using the Materials whereas Meridian owns improvements to or derivatives as well, such as enhancements to the testing tools or documentation. A Meridian developer environment is encouraged. Any suggested improvements may become part of the Materials without any obligation or notice to the submitter.
  • Developers are responsible for the products developed to consume the API. Developers are also responsible for complying with all applicable laws, including (but not limited to) those related to Meridian's intellectual property rights. Resources available on the Meridian FHIR API portal may require a customer to license additional functionality or build additional workflows.
  • Developers interested in advertising products using Meridian's FHIR API, Meridian's name, or Meridian's logo must contact Jessica.Rydel@m3meridian.com to obtain permission
  • Meridian FHIR Server API works in conjunction with VertexDr version 9

Authentication

Fhir Server is secured using OAuth2 basic http authentication. The token has an an expiration returned in the expires_in property of the response.Once token is expired Client will need to re-authenticate with the server.

client configuration

Authentication End Point: {ApiURL}/authtoken 

HTTP Client Configuration Steps

  • Start your API client (ie, Postman)
  • Enter the authentication URL with HTTP Request as POST
  • Click the Body Tab and select x-www-form-urlencoded
  • Enter the below entries:
    • Key= grant_type Value= password
    • Key= username Value= <Username>
    • Key= password Value= <password>
  • Click the Send Button to retrieve the token
  • Now enter the url of any resource with HTTP Request as GET
  • Click the Headers tab and enter Key= Authorization, Value= bearer <Authentication token> (E.g. bearer D5jkd3adf23aERsdgy312)
  • Click the Send Button to retrieve the requested resources

HTTP Header:

Key Value
Content-Type application/x-www-form-urlencoded

Body Parameter: 

Key Value
grant_type password
username <Username>
password <password>

Authorization Header: 

Need to send valid Access token, received after authentication with every request to validate user. If the token is missing or expired, the server will respond with a 401 UNAUTHORIZED.

Key Value
Authorization bearer: <access_token>

API Details

This section discusses details about Meridian FHIR API. Covers all the samples to access the Health resources.

    api mapping
  • Meridian FHIR API allows you to access(read) patient health information that is part of the Common Clinical Data Set.
  • §170.315(g)(7), §170.315(g)(8) and §170.315(g)(9) - API interface would allow a request for “all” the patient data, or specific “by specific data category.” Available data via the API interface is limited by the data defined by the Common Clinical Data Set.
  • Patient(Patient ID) is the required parameter for all the request.





Url's of Meridian FHIR Server:
Application Name URL
Authentication End Point {ApiURL}/authtoken
API End Point {ApiURL}/Fhir

Search operaters for Date:

Operator Description
[parameter]=eq2013-01-14 2013-01-14T00:00 matches.
2013-01-14T10:00 not match - it's not in the range
[parameter]=ne2013-01-14 2013-01-15T00:00 matches - it's not in the range
2013-01-14T00:00 does not match - it's in the range
[parameter]=lt2013-01-14 2013-01-13T00:00 matches
2013-01-14T00:00 does not match - it's in the range
[parameter]=gt2013-01-14 2013-01-15T00:00 matches
2013-01-14T00:00 does not match - it's in the range
[parameter]=ge2013-03-14 2013-01-14T00:00 matches
2013-01-13T00:00 does not match - it's in the range
[parameter]=le2013-03-14 2013-01-14T00:00 matches
2013-01-15T00:00 does not match - it's in the range

Meridian FHIR API server maps Individual Data Categories from Common Clinical Dataset to FHIR resources

Common Clinical Dataset FHIR Resource Resource Reference Documentation
Patient Demographics including Race/Ethnicity Patient

Required Search Parameter: Patient

Optional Search Parameter: NIL

Description: This is method is used to access patient resource.

URL Syntax: GET [base_url]/Fhir/Patient/_search?Patient=[id], GET [base_url]/Fhir/Patient/[id]

Example: GET https://[base_url]/Fhir/Patient/_search?Patient=1, GET https://[base_url]/Fhir/Patient/1

Return Type: JSON or XML

JSON Result: 

{
    "resourceType": "Patient",
    "id": "1",
    "extension": [
        {
            "url": "http://hl7.org/fhir/StructureDefinition/us-core-race",
            "extension": [
                {
                    "url": "detailed",
                    "valueCoding": {
                        "code": "2106-3",
                        "display": "White"
                    }
                }
            ]
        },
        {
            "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity",
            "extension": [
                {
                    "url": "detailed",
                    "valueCoding": {
                        "code": "2135-2",
                        "display": "Hispanic or Latino"
                    }
                }
            ]
        }
    ],
    "identifier": [
        {
            "system": "https:\\vertexdr.m3meridian.com",
            "value": "000000798"
        }
    ],
    "name": [
        {
            "family": "ABRAHAM",
            "given": [
                "Peter"
            ]
        }
    ],
    "gender": "male",
    "birthDate": "8/27/1930 12:00:00 AM",
    "address": [
        {
            "line": [
                "500 street 1"
            ],
            "city": "WINDSOR",
            "state": "CT",
            "postalCode": "6095"
        }
    ],
    "communication": [
        {
            "language": {
                "coding": [
                    {
                        "code": "es"
                    }
                ],
                "text": "Spanish; Castilian"
            }
        }
    ]
}

Medications MedicationStatement

Required Search Parameter: Patient

Optional Search Parameter: dateasserted

Description: This is method is used to access MedicationStatement resource.

URL Syntax: GET [base_url]/Fhir/MedicationStatement/_search?Patient=[id]&dateasserted=geYYYY-MM-DD&dateasserted=leYYYY-MM-DD

Example: GET [base_url]/Fhir/MedicationStatement/_search?patient=1&dateasserted=ge2017-08-22&dateasserted=le2018-01-22

Return Type: JSON or XML

JSON Result: 

{
    "resourceType": "Bundle",
    "id": "8e33f323-a0a9-41e3-8510-2033017705ec",
    "entry": [
        {
            "resource": {
                "resourceType": "MedicationStatement",
                "id": "314",
                "status": "active",
                "medicationCodeableConcept": {
                    "coding": [
                        {
                            "code": "197318"
                        }
                    ],
                    "text": "Albuterol 4 MG Oral Tablet"
                },
                "effectiveDateTime": "2017-08-22T00:00:00+05:30",
                "dateAsserted": "2017-08-22T00:00:00+05:30",
                "subject": {
                    "reference": "Patient/1"
                },
                "taken": "unk"
            }
        }
    ]
}

Problems/Health concerns Condition

Required Search Parameter: Patient

Optional Search Parameter: onsetDateTime

Description: This is method is used to access Problems/Health concerns as Condition resource.

URL Syntax: GET [base_url]/Fhir/Condition/_search?Patient=[id]&onsetDateTime=geYYYY-MM-DD&onsetDateTime=leYYYY-MM-DD

Example: GET [base_url]/Fhir/Condition/_search?patient=1&onsetDateTime=ge2012-12-15&onsetDateTime=le2012-12-30

Return Type: JSON or XML

JSON Result: 

{
    "resourceType": "Bundle",
    "id": "621beb24-f146-4b58-b0e7-1fb6f3686d3c",
    "entry": [
        {
            "resource": {
                "resourceType": "Condition",
                "id": "346",
                "clinicalStatus": "inactive",
                "verificationStatus": "confirmed",
                "category": [
                    {
                        "coding": [
                            {
                                "system": "http://hl7.org/fhir/condition-category",
                                "code": "problem-list-item",
                                "display": "problem-list-item"
                            }
                        ]
                    }
                ],
                "code": {
                    "coding": [
                        {
                            "system": "http://snomed.info/sct",
                            "code": "266569009"
                        }
                    ]
                },
                "subject": {
                    "reference": "Patient/1"
                },
                "onsetDateTime": "2012-12-15T12:08:00+05:30"
            }
        }
    ]
}

Unique Device Identifier(s) for a Patient’s Implantable Device(s) Device

Required Search Parameter: Patient

Optional Search Parameter: ManufactureDate,ExpirationDate,Date(ImplantDate)

Description: This is method is used to access Device resource.

URL Syntax: GET [base_url]/Fhir/Device/_search?Patient=[id]&Date=geYYYY-MM-DD&Date=leYYYY-MM-DD

Example: GET [base_url]/Fhir/Device/_search?patient=1&date=ge2017-10-12&date=le2017-10-30

Return Type: JSON or XML

JSON Result: 

{
	"resourceType": "Bundle",
	"id": "3b9c0c5f-2a00-4c90-a8d8-50072c691c03",
	"entry": [
		{
			"resource": {
				"resourceType": "Device",
				"id": "1",
				"udi": {
					"deviceIdentifier": "(01)10884521062856(11)141231(17)150707(10)A213B1(21)1234",
					"name": "Polyester suture"
				},
				"status": "active",
				"type": {
					"coding": [
						{
							"system": "http://hl7.org/fhir/identifier-type",
							"code": "UNK"
						}
					]
				},
				"manufacturer": "Ti-Cron",
				"manufactureDate": "2014-12-31T00:00:00+05:30",
				"expirationDate": "2015-07-07T00:00:00+05:30",
				"version": "88863380-82",
				"patient": {
					"reference": "Patient/1"
				},
				"safety": [
					{
						"text": "Labeling does not contain MRI Safety Information"
					}
				]
			}
		}
	]
}

Immunizations Immunization

Required Search Parameter: Patient

Optional Search Parameter: date

Description: This is method is used to access Immunization resource.

URL Syntax: GET [base_url]/Fhir/Immunization/_search?Patient=[id]&date=geYYYY-MM-DD&date=leYYYY-MM-DD

Example: GET [base_url]/Fhir/Immunization/_search?patient=1&date=ge2013-1-15&date=le2013-5-5

Return Type: JSON or XML

JSON Result: 

{
	"resourceType": "Bundle",
	"id": "796be861-0ce9-4c3a-b469-12cbb20c5291",
	"entry": [
		{
			"resource": {
				"resourceType": "Immunization",
				"id": "14",
				"status": "completed",
				"notGiven": true,
				"vaccineCode": {
					"coding": [
						{
							"code": "144"
						}
					]
				},
				"patient": {
					"reference": "Patient/1"
				},
				"date": "1/15/2013 10:00:00 AM",
				"primarySource": true
			}
		}
	]
}

Goals Goal

Required Search Parameter: Patient

Optional Search Parameter: startDate

Description: This is method is used to access Goal resource.

URL Syntax: GET [base_url]/Fhir/Goal/_search?Patient=[id]&startDate=geYYYY-MM-DD&startDate=leYYYY-MM-DD

Example: GET [base_url]/Fhir/Goal?Patient=1&startDate=ge2015-06-21&startDate=le2015-06-25

Return Type: JSON or XML

JSON Result: 

{
	"resourceType": "Bundle",
	"id": "c0995a03-785f-41b4-8a94-5e9d76263d3b",
	"entry": [
		{
			"resource": {
				"resourceType": "Goal",
				"id": "2497",
				"status": "proposed",
				"description": {
					"text": "Patient Goals"
				},
				"subject": {
					"reference": "Patient/1"
				},
				"startDate": "2015-06-22"
			}
		}
	]
}

Medication Allergies AllergyIntolerance

Required Search Parameter: Patient

Optional Search Parameter: onsetdatetime

Description: This is method is used to access Medication Allergies as AllergyIntolerance resource.

URL Syntax: GET [base_url]/Fhir/AllergyIntolerance/_search?Patient=[id]&dateasserted=geYYYY-MM-DD&dateasserted=leYYYY-MM-DD

Example: GET [base_url]/Fhir/AllergyIntolerance/_search?patient=1&onsetDateTime=ge2012-08-15&onsetDateTime=le2012-10-15

Return Type: JSON or XML

JSON Result: 

{
	"resourceType": "Bundle",
	"id": "58371a42-d4f8-4e54-8a8f-fce8c5873c81",
	"entry": [
		{
			"resource": {
				"resourceType": "AllergyIntolerance",
				"id": "12",
				"clinicalStatus": "active",
				"verificationStatus": "confirmed",
				"type": "allergy",
				"category": [
					"medication"
				],
				"code": {
					"coding": [
						{
							"system": "http://snomed.info/sct",
							"code": "416098002"
						}
					]
				},
				"patient": {
					"reference": "Patient/1"
				},
				"onsetDateTime": "2012-08-15T00:00:00+05:30",
				"assertedDate": "12/19/2013"
			}
		}
	]
}

Care Team Member(s) CareTeam

Required Search Parameter: Patient

Optional Search Parameter: start

Description: This is method is used to access Care Team Member(s) as CareTeam resource.

URL Syntax: GET [base_url]/Fhir/CareTeam/_search?Patient=[id]&start=geYYYY-MM-DD&start=leYYYY-MM-DD

Example: GET [base_url]/Fhir/CareTeam?Patient=1&start=ge2015-06-29&start=le2015-07-29

Return Type: JSON or XML

JSON Result: 

{
	"resourceType": "Bundle",
	"id": "6884e286-6267-49e2-b813-256bbe6cc356",
	"entry": [
		{
			"resource": {
				"resourceType": "CareTeam",
				"status": "active",
				"subject": {
					"reference": "Patient/1"
				},
				"period": {
					"start": "2015-06-29T12:55:00+05:30"
				},
				"participant": [
					{
						"role": {
							"coding": [
								{
									"system": "http://hl7.org/fhir/us/core/ValueSet/us-core-careteam-provider-roles",
									"code": "158965000",
									"display": "Medical Practitioner"
								}
							]
						},
						"member": {
							"reference": "Practitioner/_search?Patient=1&_id=11667"
						}
					}
				]
			}
		}
	]
}

Vital Signs Observation

Required Search Parameter: Patient

Optional Search Parameter: effectiveDateTime

Description: This is method is used to access Vital Signs as Observation resource.

URL Syntax: GET [base_url]/Fhir/Observation/_search?Patient=[id]&effectiveDateTime=geYYYY-MM-DD&effectiveDateTime=leYYYY-MM-DD

Example: GET [base_url]/Fhir/Observation?Patient=1&effectiveDateTime=ge2015-6-23&effectiveDateTime=le2015-12-23

Return Type: JSON or XML

JSON Result: 

{
	"resourceType": "Bundle",
	"id": "ae9bceb9-9d58-40ea-a90e-5c108a11114e",
	"entry": [
		{
			"resource": {
				"resourceType": "Observation",
				"id": "471",
				"status": "final",
				"category": [
					{
						"coding": [
							{
								"system": "http://hl7.org/fhir/observation-category",
								"code": "vital-signs"
							}
						]
					}
				],
				"code": {
					"coding": [
						{
							"system": "http://loinc.org",
							"code": "8480-6"
						}
					],
					"text": "Vital signs, weight, height, head circumference, oxygen saturation & BMI panel"
				},
				"subject": {
					"reference": "Patient/1"
				},
				"effectiveDateTime": "2015-08-23T13:43:38.527+05:30",
				"valueQuantity": {
					"value": 83.91452,
					"unit": "kg",
					"system": "http://unitsofmeasure.org"
				}
			}
		}
	]
}

Smoking Status Observation

Required Search Parameter: Patient

Optional Search Parameter: issued

Description: This is method is used to access Smoking Status as Observation resource.

URL Syntax: GET [base_url]/Fhir/Observation/_search?Patient=[id]&issued=geYYYY-MM-DD&issued=leYYYY-MM-DD

Example: GET [base_url]/Fhir/Observation?Patient=1&issued=ge2012-12-15&issued=le2013-02-15

Return Type: JSON or XML

JSON Result: 

{
	"resourceType": "Bundle",
	"id": "da3b0506-5e45-458f-9fa4-61f9feca94e4",
	"entry": [
		{
			"resource": {
				"resourceType": "Observation",
				"id": "769",
				"status": "unknown",
				"category": [
					{
						"coding": [
							{
								"system": "http://hl7.org/fhir/observation-category"
							}
						]
					}
				],
				"code": {
					"coding": [
						{
							"system": "http://loinc.org",
							"code": "72166-2"
						}
					]
				},
				"subject": {
					"reference": "Patient/1"
				},
				"issued": "2013-01-15T10:00:00+05:30",
				"valueCodeableConcept": {
					"coding": [
						{
							"system": "http://snomed.info/sct",
							"code": "8517006",
							"display": "Former smoker (CDC 3)"
						}
					]
				}
			}
		}
	]
}

Procedures Procedure

Required Search Parameter: Patient

Optional Search Parameter: performeddatetime

Description: This is method is used to access Procedure resource.

URL Syntax: GET [base_url]/Fhir/Procedure/_search?Patient=[id]&performeddatetime=geYYYY-MM-DD&performeddatetime=leYYYY-MM-DD

Example: GET [base_url]/Fhir/Procedure?Patient=1&performeddatetime=ge2012-08-1&performeddatetime=le2012-10-15

Return Type: JSON or XML

JSON Result: 

{
	"resourceType": "Bundle",
	"id": "c70a45b4-5d6a-4f1f-a47c-9ef58cafe90d",
	"entry": [
		{
			"resource": {
				"resourceType": "Procedure",
				"id": "1727",
				"status": "unknown",
				"code": {
					"coding": [
						{
							"system": "http://snomed.info/sct",
							"code": "103699006"
						}
					]
				},
				"subject": {
					"reference": "Patient/1"
				},
				"performedDateTime": "2012-08-15T10:01:00+05:30"
			}
		}
	]
}

Assessment and Plan of Treatment CarePlan

Required Search Parameter: Patient

Optional Search Parameter: start

Description: This is method is used to access Assessment and Plan of Treatment as CarePlan resource.

URL Syntax: GET [base_url]/Fhir/CarePlan/_search?Patient=[id]&start=geYYYY-MM-DD&start=leYYYY-MM-DD

Example: GET [base_url]/Fhir/CarePlan?Patient=1&start=ge2013-01-10&start=le2013-01-30

Return Type: JSON or XML

JSON Result: 

{
	"resourceType": "Bundle",
	"id": "77e95858-231f-4101-b5e0-63f4240eb5f7",
	"entry": [
		{
			"resource": {
				"resourceType": "CarePlan",
				"id": "1190",
				"text": {
					"status": "generated",
					"div": "Oral Hypoglycemics Glyburide"
				},
				"status": "unknown",
				"intent": "order",
				"category": [
					{
						"coding": [
							{
								"system": "http://snomed.info/sct",
								"code": "412774003"
							}
						],
						"text": "Clinical management plan"
					}
				],
				"subject": {
					"reference": "Patient/1"
				},
				"period": {
					"start": "2013-01-15T10:00:00+05:30"
				}
			}
		}
	]
}

Laboratory Tests Observation

Required Search Parameter: Patient

Optional Search Parameter: issued

Description: This is method is used to access Laboratory Tests as Observation resource.

URL Syntax: GET [base_url]/Fhir/MedicationStatement/_search?Patient=[id]&issued=geYYYY-MM-DD&issued=leYYYY-MM-DD

Example: GET [base_url]/Fhir/MedicationStatement?Patient=1&issued=ge2012-07-15&issued=le2012-09-15

Return Type: JSON or XML

JSON Result: 

{
	"resourceType": "Bundle",
	"id": "2bb5e5d0-c072-4186-9d00-ea8af3f3d346",
	"entry": [
		{
			"resource": {
				"resourceType": "Observation",
				"id": "116",
				"status": "final",
				"category": [
					{
						"coding": [
							{
								"system": "http://hl7.org/fhir/observation-category",
								"code": "LAB"
							}
						]
					}
				],
				"code": {
					"coding": [
						{
							"system": "http://loinc.org",
							"code": "2028-9",
							"display": "C02"
						}
					]
				},
				"subject": {
					"reference": "Patient/1"
				},
				"effectiveDateTime": "2012-08-15T19:32:24+05:30",
				"issued": "2012-08-15T19:32:24+05:30"
			}
		}
	]
}

Laboratory Values(s)/Result(s) Observation

Required Search Parameter: Patient

Optional Search Parameter: issued

Description: This is method is used to access Laboratory Values(s)/Result(s) as Observation resource.

URL Syntax: GET [base_url]/Fhir/Observation/_search?Patient=[id]&issued=geYYYY-MM-DD&issued=leYYYY-MM-DD

Example: GET [base_url]/Fhir/Observation?Patient=1&issued=ge2017-10-1&issued=le2017-10-30

Return Type: JSON or XML

JSON Result: 

{
	"id": "eaf16125-bfea-41ab-9873-79a40a50a02e",
	"entry": [
		{
			"resource": {
				"resourceType": "Observation",
				"id": "214",
				"status": "preliminary",
				"category": [
					{
						"coding": [
							{
								"system": "http://hl7.org/fhir/observation-category",
								"code": "LAB"
							}
						]
					}
				],
				"code": {
					"coding": [
						{
							"system": "http://loinc.org",
							"code": "5778-6",
							"display": "YELLOW"
						}
					]
				},
				"subject": {
					"reference": "Patient/1"
				},
				"effectiveDateTime": "2017-10-17T12:55:49.157+05:30",
				"issued": "2017-10-17T12:55:49.157+05:30"
			}
		}
	]
}

CCD Binary

Required Search Parameter: Patient

Optional Search Parameter: fromDate,toDate

Description: This is method is used to access CCD's as Binary resource.

URL Syntax: GET [base_url]/Fhir/Binary/_search?Patient=[id]&toDate=YYYY-MM-DD&toDate=YYYY-MM-DD

Example: GET [base_url]/Fhir/Binary?Patient=1&fromDate=2017-10-1&toDate=2017-10-30

Return Type: JSON or XML

Note: Search will only support (=) operator as mentioned in example

JSON Result:
 

{
    "resourceType": "Bundle",
    "id": "37c6d605-0fdb-4194-a38f-950e89025620",
    "entry": [
        {
            "resource": {
                "resourceType": "Binary",
                "id": "1231",
                "contentType": "application/xml",
                "content": "U2FtcGxlIEJpbmFyeSBSZXN1bHQ="
            }
        }
    ]
}

HTTP Methods

Supported request type:

    method
  • HTTP GET

Unsupported request types:

  • HTTP POST
  • HTTP DELETE
  • HTTP PUT

Request and Response

This section discusses about the request and response. FHIR Server is capable of providing the responses in both JSON & XML format

Application/JSONresponse

  • [Api Base Url]/fhir/Device/_search?Patient=PatientID&_format=JSON
  • This will provide a response in JSON format.

Application/XML

  • [Api Base Url]/fhir/Device/_search?Patient=PatientID&_format=XML
  • This request will provide a response in XML format.

GET fhir/{type}/_search

Description: This endpoint is used to search all the resources with search parameters.

FhirResponse:

Name Description Type
Resource   Resource

GET fhir/{type}/{id}

Description: This endpoint is used to get the resource with Id. Only patient resource can be accessed with this endpoint.

FhirResponse:

Name Description Type
Resource   Resource

Error Handling

FHIR Server will return OperationOutcome Resource with error message for all the valid request with status code 200 in XML/JSON format.

erros and exceptions

Example:

{
	"resourceType": "OperationOutcome",
	"text": {
		"status": "generated"
	},
	"issue": [
		{
			"severity": "error",
			"code": "processing",
			"diagnostics": "Trying to access another user's profile."
		}
	]
}

Below is a list of errors messages:

Error Message Description
Trying to access another user's profile. Permission is denied to access another patient's profile.
Missing required search parameter Patient id ex:Patient=123. Patient Id is required parameter for all the requests.
Only Patient resource can be accessed with identifier ({type}/{id}). Only Patient resource can be accessed directly with identifier ({type}/{id}). Other resources can be accessed with search.

Not Found - HTTP Status Code - 404

  • Any request with invalid or bad URL will return HTTP-404 response along with error message

Unauthorized - HTTP Status Code - 401

  • Any request with Invalid/Missing token will return HTTP-401 response along with error message