Interface Guide

Building Requests

The FHIR Interface allows you to manage resources with a variety of basic interactions, including:

  • Read
  • Search
  • Create
  • Update
  • Delete

Basic interactions are performed by issuing a HTTP request to the appropriate resource address. Some sample requests are shown below. For complete details, see the HL7 FHIR Specification.

Interaction HTTP Request Type Sample Address
read GET [base]/Patient/1234-5678-90AB
search GET [base]/Patient?family=Demoski&given=Helen
create POST [base]/Patient
update PUT [base]/Patient/1234-5678-90AB
delete DELETE [base]/Patient/1234-5678-90AB

Supported Interactions

Not all resources support all interactions. For example, you may not alter Audit Event resources (as that would defeat the purposes of an audit trail), and Practitioners can be updated but not deleted. Specific endpoints may also limit access to interactions, providing read-only access or restricting search operations.

Access Tokens

Every request must include an access token granting you access to the resource. This token should be included in the request’s HTTP header:

Authorization: Bearer YOUR_ACCESS_TOKEN

To find out how to get an access token, see Authentication.

Data Format

FHIR requests use XML format by default. You can request JSON format instead by adding the “_format” query parameter to the request or adding a HTTP “Accept” header.

Format Query Parameter:



Accept: application/json

Request Body

POST and PUT operations contain the resource records to update/create in the HTTP request body. Both expect full records; partial updates are not supported. For more information about what FHIR fields are supported and how that data is stored in the HIEBus system, see Mapping.

Summary Searches

Many FHIR records contain a lot of data, and you can improve the performance of your search interactions by requesting only a summary of the matched records. Just add the “_summary” parameter to your search. For example:


Several summary formats are available. See FHIR specification for details.

Search Builder

The Search Builder app helps you build query parameters for search interactions. You can test out various combinations of search parameters and see live results.

To launch the app, go to the site’s implementation reference and select the “try it” option.

For example: hhttps://fhir.careevolution.com/Master.Adapter1.WebClient/fhir/search.

Search Test App
Search Test App

The Search Builder allows you to control how many results are returned, how the data is sorted, and what data is included in the results.

At the bottom of the search input box it shows you the complete URL and parameters for the specific query you selected. This can help you build the necessary query strings in your FHIR application.

Search Test App Query URL
Search Test App Query URL

Extended Operations

In addition to the basic RESTful create/read/update/delete interactions, extended operations provide additional ways to interact with the system.

Operations use GET or POST requests, with the operation name (preceded by a ‘$’) appended to the resource address. Some operations act on a resource, some on a resource instance, and some are not resource-specific at all. Some sample requests are shown below. For complete details, see the HL7 FHIR Specification.

Operation Resource Type Sample Address
validate (general) Resource [base]/Patient/$validate
validate (specific) Resource Instance [base]/Patient/1234-5678-90AB/$validate
compose-coding-system General [base]/$compose-coding-system

The POST body would contain any necessary input parameters, in XML or JSON format.

See the Interface Specification for details about all operations supported by the FHIR Interface.