International Patient Access
1.0.0 - STU1 International flag

International Patient Access, published by HL7 International / Patient Care. This guide is not an authorized publication; it is the continuous build for version 1.0.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/fhir-ipa/ and changes regularly. See the Directory of published versions

CapabilityStatement: International Patient Access Client CapabilityStatement

Official URL: http://hl7.org/fhir/uv/ipa/CapabilityStatement/ipa-client Version: 1.0.0
Standards status: Trial-use Computable Name: InternationalPatientAccessClientAPI

Copyright/Legal: Used by permission of HL7 International all rights reserved Creative Commons License

This CapabilityStatement describes the basic rules for the International Patient Access client actor that initiates a data access request to and retrieves patient data from an IPA Responder. In addition, it lists the client conformance expectations for each resource type documented in IPA. These expectations include supported FHIR profiles, RESTful operations, and search parameters. International Patient Access clients define their capabilities by choosing from this list based on the resource types they need to access.

Raw OpenAPI-Swagger Definition file | Download

International Patient Access Client CapabilityStatement

  • Implementation Guide Version: 1.0.0
  • FHIR Version: 4.0.1
  • Supported Formats: SHALL support json, SHOULD support xml
  • Supported Patch Formats: SHOULD support application/json-patch+json
  • Published on: Thu Dec 08 00:00:00 UTC 2022
  • Published by: HL7 International / Patient Care

Note to Implementers: FHIR Capabilities

Any FHIR capability may be 'allowed' by the system unless explicitly marked as "SHALL NOT". A few items are marked as MAY in the Implementation Guide to highlight their potential relevance to the use case.

SHALL Support the Following Implementation Guides

FHIR RESTful Capabilities

Mode: client

The IPA Client SHALL:

  1. Support the IPA conformance expectations for the Patient resource profile.
  2. Support the IPA conformance expectations for each IPA resource type they support
  3. Implement the RESTful behavior according to the FHIR specification.
  4. Support JSON source formats for all IPA interactions.

The IPA Client SHOULD:

  1. For the purposes of safety, specify the patient id when searching other resources.
Security
  1. See the General Security Considerations section for requirements and recommendations.
Summary of System-wide Interactions
  • MAY support the transaction interaction.
  • MAY support the batch interaction.
  • MAY support the search-system interaction.
  • MAY support the history-system interaction.

Capabilities by Resource/Profile

Summary

The summary table lists the resources that are part of this configuration, and for each resource it lists:

  • The relevant profiles (if any)
  • The interactions supported by each resource (Read, Search, Update, and Create, are always shown, while VRead, Patch, Delete, History on Instance, or History on Type are only present if at least one of the resources has support for them.
  • The required, recommended, and some optional search parameters (if any).
  • The linked resources enabled for _include
  • The other resources enabled for _revinclude
  • The operations on the resource (if any)
Resource TypeProfileRSUCSearches_include_revincludeOperations
AllergyIntolerancehttp://hl7.org/fhir/uv/ipa/StructureDefinition/ipa-allergyintoleranceyyclinical-status, patient, patient+clinical-statusProvenance:target
Conditionhttp://hl7.org/fhir/uv/ipa/StructureDefinition/ipa-condition
Additional supported profiles:
  IPA-problem-list-item
yycategory, clinical-status, verification-status, code, onset-date, patient, patient+clinical-status, patient+category, patient+category+clinical-status, patient+code, patient+onset-dateProvenance:target
DocumentReferencehttp://hl7.org/fhir/uv/ipa/StructureDefinition/ipa-documentreferenceyy_id, category, contenttype, date, period, status, type, patient, patient+category, patient+category+date, patient+type, patient+contenttype, patient+status, patient+type+date, patient+type+periodProvenance:target$docref
Immunizationhttp://hl7.org/fhir/uv/ipa/StructureDefinition/ipa-immunizationyydate, status, patient, patient+date, patient+statusProvenance:target
Medicationhttp://hl7.org/fhir/uv/ipa/StructureDefinition/ipa-medicationyProvenance:target
MedicationRequesthttp://hl7.org/fhir/uv/ipa/StructureDefinition/ipa-medicationrequestyycategory, code, authoredon, intent, status, patient, patient+intent, patient+intent+authoredon, patient+intent+statusMedicationRequest:medicationProvenance:target
MedicationStatementhttp://hl7.org/fhir/uv/ipa/StructureDefinition/ipa-medicationstatementyystatus, patient, patient+statusMedicationStatement:medicationProvenance:target
Observationhttp://hl7.org/fhir/uv/ipa/StructureDefinition/ipa-observation
Additional supported profiles:
  Vital Signs Profile
yycategory, code, date, status, patient, patient+category, patient+code, patient+category+date, patient+category+status, patient+code+dateProvenance:target
Patienthttp://hl7.org/fhir/uv/ipa/StructureDefinition/ipa-patientyy_id, birthdate, family, gender, given, identifier, name, family+gender, birthdate+family, birthdate+name, gender+nameProvenance:target
Practitionerhttp://hl7.org/fhir/uv/ipa/StructureDefinition/ipa-practitioneryProvenance:target
PractitionerRolehttp://hl7.org/fhir/uv/ipa/StructureDefinition/ipa-practitionerroleyPractitionerRole:endpoint, PractitionerRole:practitionerProvenance:target

Resource Conformance: SHOULDAllergyIntolerance

Profile Conformance
SHALL
Reference Policy
resolves

Interaction summary
  • SHALL support read, search-type.

Documentation

If the client supports the AllergyIntolerance resource, the client SHALL support the IPA profile and the conformance expectations for the AllergyIntolerance resource.

Search Parameters
ConformanceParameterTypeDocumentation
SHALLpatientreference

The client SHALL provide at least a id value and MAY provide both the Type and id values. The server SHALL support both.

MAYclinical-statustoken

active | inactive | resolved

Combined Search Parameters
ConformanceParametersTypes
SHOULDpatient+clinical-statusreference+token

Resource Conformance: SHOULDCondition

Profile Conformance
SHALL
Reference Policy
resolves

Interaction summary
  • SHALL support read, search-type.

Documentation

If the client supports the Condition resource, the client SHALL support the IPA profile and the conformance expectations for the Condition resource.

Client applications should be prepared to encounter codes they do not recognize and handle the records accordingly. Servers SHOULD populate Condition.code.coding.display and/or Condition.code.text so that clients can always at least display the condition even if they do not know the codes that are used. Clients should be careful making use of the code search parameter given that the codes used vary so much.

Safety Issues:

  • Clients SHALL not treat all conditions as if they are part of the patient's current problem list
    • Note that some Condition resources may not have these status codes - this is usually due to poor record keeping reflected in legacy data
    • Servers SHOULD avoid leaving these status codes missing
  • Clients SHALL pay attention to the clinicalStatus and verificationStatus and display and process them correctly * Clients SHALL still work safely when the server does not support all the search parameters listed here.
Search Parameters
ConformanceParameterTypeDocumentation
SHALLpatientreference

The client SHALL provide at least a id value and MAY provide both the Type and id values. The server SHALL support both.

MAYcategorytoken

The category of the condition

MAYclinical-statustoken

The clinical status of the condition

MAYverification-statustoken

The verification status of the condition

MAYcodetoken

Code for the condition

MAYonset-datedate

Date of onset for the condition

Combined Search Parameters
ConformanceParametersTypes
SHOULDpatient+clinical-statusreference+token
SHOULDpatient+categoryreference+token
SHOULDpatient+category+clinical-statusreference+token+token
SHOULDpatient+codereference+token
SHOULDpatient+onset-datereference+date

Resource Conformance: SHOULDDocumentReference

Profile Conformance
SHALL
Reference Policy
resolves

Interaction summary
  • SHALL support read, search-type.

Documentation

If the client supports the DocumentReference resource, the client SHALL support the IPA profile and the conformance expectations for the DocumentReference resource.

Search Parameters
ConformanceParameterTypeDocumentation
SHALLpatientreference

The client SHALL provide at least an id value and MAY provide both the Type and id values. The server SHALL support both.

SHOULD_idtoken
MAYcategorytoken

Categorization of document

MAYcontenttypetoken

Mime type of the content, may include charset

MAYdatedate

When this document reference was created

MAYperioddate

Time of service that is being documented

MAYstatustoken

current | superseded | entered-in-error

MAYtypetoken

Kind of document (LOINC if possible)

Combined Search Parameters
ConformanceParametersTypes
SHOULDpatient+categoryreference+token
SHOULDpatient+category+datereference+token+date
SHOULDpatient+typereference+token
SHOULDpatient+contenttypereference+token
SHOULDpatient+statusreference+token
SHOULDpatient+type+datereference+token+date
SHOULDpatient+type+periodreference+token+date
Extended Operations
ConformanceOperationDocumentation
SHOULD$docref

A client SHOULD be capable of transacting a $docref operation and capable of accessing the document using the using the link provided in the DocumentReference.content.attachment.url element.

Resource Conformance: SHOULDImmunization

Profile Conformance
SHALL
Reference Policy
resolves

Interaction summary
  • SHALL support read, search-type.

Documentation

If the client supports the Immunization resource, the client SHALL support the IPA profile and the conformance expectations for the Immunization resource.

Search Parameters
ConformanceParameterTypeDocumentation
SHALLpatientreference

The client SHALL provide at least an id value and MAY provide both the Type and id values. The server SHALL support both.

MAYdatedate

Vaccination (non)-Administration Date

MAYstatustoken

Immunization event status

Combined Search Parameters
ConformanceParametersTypes
SHOULDpatient+datereference+date
SHOULDpatient+statusreference+token

Resource Conformance: SHOULDMedication

Profile Conformance
SHALL
Reference Policy
resolves

Interaction summary
  • SHALL support read.

Documentation

If the client supports the the MedicationStatement or MedicationRequest resource, the client SHALL support the IPA profile and the conformance expectations for the Medication resource.

Resource Conformance: SHOULDMedicationRequest

Profile Conformance
SHALL
Reference Policy
resolves

Interaction summary
  • SHALL support read, search-type.

Documentation

If the client supports the MedicationRequest resource, the client SHALL support the IPA profile and the conformance expectations for the MedicationStatement, MedicationRequest and Medication resource.

Clients SHALL query for both MedicationStatement and MedicationRequest when fetching patient Medication information.

The MedicationRequest resources can represent a medication using either a code or refer to the Medication resource. When referencing Medication, the resource may be contained or an external resource. The server application MAY choose any one way or more than one method, but if an external reference to Medication is used, the server SHALL support the _include parameter for searching this element. The client application SHALL support all methods. For example, A server SHALL be capable of returning all medications for a patient using one of or both:

GET /MedicationStatement?patient=[id]

GET /MedicationStatement?patient=[id]&_include=MedicationStatement:medication

When representing a prescribed medication, servers SHOULD use codings at the level of a clinical drug rather than ingredient or dose form (e.g. "loratadine 10mg oral tablet", rather than a bare ingredient like "loratadine" or a dose form like "loratadine oral tablet").

Search Parameters
ConformanceParameterTypeDocumentation
SHALLpatientreference

The client SHALL provide at least an id value and MAY provide both the Type and id values. The server SHALL support both.

SHOULDcategorytoken

Returns prescriptions with different categories

SHOULDcodetoken

Return prescriptions of this medication code

MAYauthoredondate

Returns prescriptions written on this date

MAYintenttoken

Return prescriptions with this encounter identifier

MAYstatustoken

Status of the prescription

Combined Search Parameters
ConformanceParametersTypes
SHOULDpatient+intentreference+token
SHOULDpatient+intent+authoredonreference+token+date
SHOULDpatient+intent+statusreference+token+token

Resource Conformance: SHOULDMedicationStatement

Profile Conformance
SHALL
Reference Policy
resolves

Interaction summary
  • SHALL support read, search-type.

Documentation

If the client supports the MedicationStatement resource, the client SHALL support the IPA profile and the conformance expectations for the MedicationStatement, MedicationRequest and Medication resource.

Clients SHALL query for both MedicationStatement and MedicationRequest when fetching patient Medication information.

The MedicationStatement resources can represent a medication using either a code or refer to the Medication resource. When referencing Medication, the resource may be contained or an external resource. The server application MAY choose any one way or more than one method, but if an external reference to Medication is used, the server SHALL support the _include parameter for searching this element. The client application SHALL support all methods.For example, A server SHALL be capable of returning all medications for a patient using one of or both:

GET /MedicationStatement?patient=[id]

GET/MedicationStatement?patient=[id]&_include=MedicationStatement:medication

Search Parameters
ConformanceParameterTypeDocumentation
SHALLpatientreference

The client SHALL provide at least an id value and MAY provide both the Type and id values.

MAYstatustoken

Return statements that match the given status

Combined Search Parameters
ConformanceParametersTypes
SHOULDpatient+statusreference+token

Resource Conformance: SHOULDObservation

Profile Conformance
SHALL
Reference Policy
resolves

Interaction summary
  • SHALL support read, search-type.

Documentation

If the client supports the Observation resource, the client SHALL support the IPA profile and the conformance expectations for the Observation resource.

Search Parameters
ConformanceParameterTypeDocumentation
SHALLpatientreference

The client SHALL provide at least an id value and MAY provide both the Type and id values. The server SHALL support both.

MAYcategorytoken

The classification of the type of observation

MAYcodetoken

The code of the observation type

MAYdatedate

Obtained date/time. If the obtained element is a period, a date that falls in the period

MAYstatustoken

The status of the observation

Combined Search Parameters
ConformanceParametersTypes
SHOULDpatient+categoryreference+token
SHOULDpatient+codereference+token
SHOULDpatient+category+datereference+token+date
SHOULDpatient+category+statusreference+token+token
SHOULDpatient+code+datereference+token+date

Resource Conformance: SHALLPatient

Profile Conformance
SHALL
Reference Policy
resolves

Interaction summary
  • SHALL support read, search-type.

Documentation

Client applications SHALL be able to access the patient record using the following API call:

GET [url]/Patient/[id]

Client application MAY use these search parameters that servers are required to support to access the patient record:

  • _id
  • identifier

Servers are not required to support any additional search parameters, and clients SHOULD not expect servers to do so.

Additional rules and guidance for supporting Patient.link:

  • The server:
    • SHALL have no more than one Patient with a status of active = "true" from the server being queried
    • MAY include inactive patients on the same server
    • MAY include inactive or active patients from a different server
    • When returning a search Bundle that contains more than one Patient record for the same patient, the Patient record(s) SHALL use the Patient.link attribute to cross-link the Patient resources.
  • The client:
    • SHALL be able to follow the link(s) to the other Patient resource(s) and understand the direction of the link (in other words, which Patient is linked to which other Patient)
    • SHALL understand the Patient.link.type code which defines the type of link between this Patient resource and another Patient resource
    • SHALL be aware of the linked Patient active flag and that inactive patients may have relevant information
Search Parameters
ConformanceParameterTypeDocumentation
SHOULD_idtoken
SHOULDbirthdatedate

A client SHALL provide a value precise to the day. A server SHALL support a value a value precise to the day.

SHOULDfamilystring
SHOULDgendertoken

The client SHALL provide at least a code value and MAY provide both the system and code values. The server SHALL support both.

SHOULDgivenstring
SHOULDidentifiertoken

The client SHALL provide both the system and code values. The server SHALL NOT support only code values.

SHOULDnamestring
Combined Search Parameters
ConformanceParametersTypes
SHOULDfamily+genderstring+token
SHOULDbirthdate+familydate+string
SHOULDbirthdate+namedate+string
SHOULDgender+nametoken+string

Resource Conformance: SHOULDPractitioner

Profile Conformance
SHALL
Reference Policy
resolves

Interaction summary
  • SHALL support read.

Documentation

If the client supports the Practitioner resource, the client SHALL support the IPA profile and the conformance expectations for the Practitioner resource.

Resource Conformance: SHOULDPractitionerRole

Profile Conformance
SHALL
Reference Policy
resolves

Interaction summary
  • SHALL support read.

Documentation

If the client supports the PractitionerRole resource, the client SHALL support the IPA profile and the conformance expectations for the PractitionerRole resource.