This guide introduces some basic concepts and workflows that will be important as you begin using the API.
Contents
All Convert API operations assume the input data represents a single individual.
For the “to FHIR” operations (including Combine FHIR Bundles), you may optionally specify a patientID
in the URL segment. This value will be used for the id
field in the resulting Patient
resource within the output bundle. Although the Convert service will generate a default patient ID if none is provided, it is strongly recommended that you provide your own patient ID. Patient IDs must conform to the FHIR ID requirements.
All of the “to FHIR” operations (including Combine FHIR Bundles) return a FHIR R4 Bundle containing the input data converted into FHIR resources. The bundle will be of type searchSet
, equivalent to performing a Patient/$everything
request against a traditional FHIR server.
The following special considerations apply to the FHIR bundles from these operations.
These bundles include an OperationOutcome resource
. An OperationOutcome is a collection of issue
elements detailing what was parsed from the input, as well as any problems with the conversion. See Operation Outcomes for details.
The convert API will generate unique logical ids for all resources that were converted from the input. Resources within a bundle may refer to other resources within the same bundle (e.g., a Condition referencing a Patient/{ID}). The convert API is stateless, and different requests are considered independent of one another. Submitting the same input information to the API multiple times will result in different logical ID elements being generated for the equivalent input concept. Business identifiers are retained if sent in the input data.
As part of the conversion process, the API will use the Terminology service to standardize input codes. This will result in the following enhancements to output data.
FHIR code elements represent enumerations with a set of possible values (e.g., Patient.gender, Condition.status). In these situations, the code in the FHIR bundle will be the equivalent input field translated into an equivalent value in the enumeration. An extension element will be added (e.g., Patient._gender, Condition._status) that contains the input code as sent represented as a Coding.
In addition to the data directly present in the input, CodeableConcepts may have additional codings representing the standardized reference codes from the Terminology service. These added codings can be identified by the userSelected: false
property.
This can include the following: