International Patient Access
1.1.0 - STU1

International Patient Access, published by HL7 International / Patient Care. This guide is not an authorized publication; it is the continuous build for version 1.1.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 Server CapabilityStatement

Official URL: http://hl7.org/fhir/uv/ipa/CapabilityStatement/ipa-server | Version: 1.1.0
Standards status: Trial-use | Computable Name: InternationalPatientAccessAPI
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 server actor that is responsible for providing responses to queries submitted by International Patient Access requestors. The complete list of FHIR profiles, RESTful operations, and search parameters supported by International Patient Access servers are defined in this CapabilityStatement.

Raw OpenAPI-Swagger Definition file | Download

Generated Narrative: CapabilityStatement ipa-server

## International Patient Access Server CapabilityStatement

- Implementation Guide Version: 1.1.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: 2023-11-14
- 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

- http://hl7.org/fhir/smart-app-launch/ImplementationGuide/hl7.fhir.uv.smart-app-launch

## FHIR RESTful Capabilities

### Mode: `server`

The IPA Server SHALL:

1. Support the IPA Patient resource profile.

2. Support at least one additional resource profile from the list of IPA Profiles.

3. Implement the RESTful behavior according to the FHIR specification.

4. Return the following response classes:

   - (Status 400): invalid parameter

   - (Status 401/4xx): unauthorized request

   - (Status 403): insufficient scope

   - (Status 404): unknown resource

5. Support JSON source formats for all IPA interactions.

6. Declare a CapabilityStatement identifying the list of profiles, operations, and search parameters supported.

The IPA Server SHOULD:

1. Support XML source formats for all IPA interactions.

Security

> 1. See the General Security Considerations section for requirements and recommendations.
> 2. A server SHALL reject any unauthorized requests by returning an HTTP `401 Unauthorized`, `403 Forbidden`, or `404 Not Found` response code.

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 Type | Profile | R | S | U | C | Searches | `_include` | `_revinclude` | Operations
--- | --- | --- | --- | --- | --- | --- | --- | --- | ---
AllergyIntolerance | http://hl7.org/fhir/uv/ipa/StructureDefinition/ipa-allergyintolerance | y | y |  |  | clinical-status, patient, patient+clinical-status |  | `Provenance:target` |
Condition | http://hl7.org/fhir/uv/ipa/StructureDefinition/ipa-condition Additional supported profiles: IPA-problem-list-item | y | y |  |  | category, clinical-status, verification-status, code, onset-date, patient, patient+clinical-status, patient+category, patient+category+clinical-status, patient+code, patient+onset-date |  | `Provenance:target` |
DocumentReference | http://hl7.org/fhir/uv/ipa/StructureDefinition/ipa-documentreference | y | y |  |  | _id, category, contenttype, date, period, status, type, patient, patient+category, patient+category+date, patient+type, patient+contenttype, patient+status, patient+type+date, patient+type+period |  | `Provenance:target` | `$docref`
Immunization | http://hl7.org/fhir/uv/ipa/StructureDefinition/ipa-immunization | y | y |  |  | date, status, patient, patient+date, patient+status |  | `Provenance:target` |
Medication | http://hl7.org/fhir/uv/ipa/StructureDefinition/ipa-medication | y |  |  |  |  |  | `Provenance:target` |
MedicationRequest | http://hl7.org/fhir/uv/ipa/StructureDefinition/ipa-medicationrequest | y | y |  |  | category, code, authoredon, intent, status, patient, patient+intent, patient+intent+authoredon, patient+intent+status | `MedicationRequest:medication` | `Provenance:target` |
MedicationStatement | http://hl7.org/fhir/uv/ipa/StructureDefinition/ipa-medicationstatement | y | y |  |  | status, patient, patient+status | `MedicationStatement:medication` | `Provenance:target` |
Observation | http://hl7.org/fhir/uv/ipa/StructureDefinition/ipa-observation Additional supported profiles: Vital Signs Profile | y | y |  |  | category, code, date, status, patient, patient+category, patient+code, patient+category+date, patient+category+status, patient+code+date |  | `Provenance:target` |
Patient | http://hl7.org/fhir/uv/ipa/StructureDefinition/ipa-patient | y | y |  |  | _id, birthdate, family, gender, given, identifier, name, family+gender, birthdate+family, birthdate+name, gender+name |  | `Provenance:target` |
Practitioner | http://hl7.org/fhir/uv/ipa/StructureDefinition/ipa-practitioner | y |  |  |  |  |  | `Provenance:target` |
PractitionerRole | http://hl7.org/fhir/uv/ipa/StructureDefinition/ipa-practitionerrole | y |  |  |  |  | `PractitionerRole:endpoint`, `PractitionerRole:practitioner` | `Provenance:target` |

#### Resource Conformance: SHOULD AllergyIntolerance

Base System Profile
IPA-AllergyIntolerance
Profile Conformance
SHALL
Reference Policy
`resolves`

Interaction summary

- SHALL support `read`, `search-type`.

Search Parameters

Conformance | Parameter | Type | Documentation
--- | --- | --- | ---
SHALL | patient | `reference` | The client SHALL provide at least a id value and MAY provide both the Type and id values. The server SHALL support both.
MAY | clinical-status | `token` | active | inactive | resolved

Combined Search Parameters

Conformance | Parameters | Types
--- | --- | ---
SHOULD | patient+clinical-status | `reference`+`token`

#### Resource Conformance: SHOULD Condition

Base System Profile
IPA-Condition
Profile Conformance
SHALL
Reference Policy
`resolves`

Supported Profiles

IPA-problem-list-item

Interaction summary

- SHALL support `read`, `search-type`.

Documentation

> 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

Conformance | Parameter | Type | Documentation
--- | --- | --- | ---
SHALL | patient | `reference` | The client SHALL provide at least a id value and MAY provide both the Type and id values. The server SHALL support both.
MAY | category | `token` | The category of the condition
MAY | clinical-status | `token` | The clinical status of the condition
MAY | verification-status | `token` | The verification status of the condition
MAY | code | `token` | Code for the condition
MAY | onset-date | `date` | Date of onset for the condition

Combined Search Parameters

Conformance | Parameters | Types
--- | --- | ---
SHOULD | patient+clinical-status | `reference`+`token`
SHOULD | patient+category | `reference`+`token`
SHOULD | patient+category+clinical-status | `reference`+`token`+`token`
SHOULD | patient+code | `reference`+`token`
SHOULD | patient+onset-date | `reference`+`date`

#### Resource Conformance: SHOULD DocumentReference

Base System Profile
IPA-DocumentReference
Profile Conformance
SHALL
Reference Policy
`resolves`

Interaction summary

- SHALL support `read`, `search-type`.

Search Parameters

Conformance | Parameter | Type | Documentation
--- | --- | --- | ---
SHALL | _id | `token` |
SHALL | patient | `reference` | The client SHALL provide at least an id value and MAY provide both the Type and id values. The server SHALL support both.
MAY | category | `token` | Categorization of document
MAY | contenttype | `token` | Mime type of the content, may include charset
MAY | date | `date` | When this document reference was created
MAY | period | `date` | Time of service that is being documented
MAY | status | `token` | current | superseded | entered-in-error
MAY | type | `token` | Kind of document (LOINC if possible)

Combined Search Parameters

Conformance | Parameters | Types
--- | --- | ---
SHALL | patient+category | `reference`+`token`
SHALL | patient+category+date | `reference`+`token`+`date`
SHALL | patient+type | `reference`+`token`
SHOULD | patient+contenttype | `reference`+`token`
SHOULD | patient+status | `reference`+`token`
SHOULD | patient+type+date | `reference`+`token`+`date`
SHOULD | patient+type+period | `reference`+`token`+`date`

Extended Operations

Conformance | Operation | Documentation
--- | --- | ---
SHALL | $docref | A server SHOULD be capable of responding to a $docref operation and capable of returning at least a reference to a CDA document, if available. MAY provide references to other 'on-demand' and 'stable' documents (or 'delayed/deferred assembly') that meet the query parameters as well. If a context date range is supplied the server ** SHOULD** provide references to any document that falls within the date range If no date range is supplied, then the server SHALL provide references to last or current encounter. SHOULD document what resources, if any, are returned as included resources `GET [base]/DocumentReference/$docref?patient=[id]`

#### Resource Conformance: SHOULD Immunization

Base System Profile
IPA-Immunization
Profile Conformance
SHALL
Reference Policy
`resolves`

Interaction summary

- SHALL support `read`, `search-type`.

Search Parameters

Conformance | Parameter | Type | Documentation
--- | --- | --- | ---
SHALL | patient | `reference` | The client SHALL provide at least an id value and MAY provide both the Type and id values. The server SHALL support both.
MAY | date | `date` | Vaccination (non)-Administration Date
MAY | status | `token` | Immunization event status

Combined Search Parameters

Conformance | Parameters | Types
--- | --- | ---
SHOULD | patient+date | `reference`+`date`
SHOULD | patient+status | `reference`+`token`

#### Resource Conformance: SHOULD Medication

Base System Profile
IPA-Medication
Profile Conformance
SHALL
Reference Policy
`resolves`

Interaction summary

- SHALL support `read`.

Documentation

> The MedicationStatement and MedicationRequest resources can represent a medication, using an external reference to a Medication resource. If an external Medication Resource is used in a MedicationStatement or a MedicationRequest, then the READ and SEARCH Criteria SHALL be supported.

#### Resource Conformance: SHOULD MedicationRequest

Base System Profile
IPA-MedicationRequest
Profile Conformance
SHALL
Reference Policy
`resolves`

Interaction summary

- SHALL support `read`, `search-type`.

Documentation

> 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

Conformance | Parameter | Type | Documentation
--- | --- | --- | ---
SHALL | patient | `reference` | The client SHALL provide at least an id value and MAY provide both the Type and id values. The server SHALL support both.
SHOULD | category | `token` | Returns prescriptions with different categories
SHOULD | code | `token` | Return prescriptions of this medication code
MAY | authoredon | `date` | Returns prescriptions written on this date
MAY | intent | `token` | Return prescriptions with this encounter identifier
MAY | status | `token` | Status of the prescription

Combined Search Parameters

Conformance | Parameters | Types
--- | --- | ---
SHOULD | patient+intent | `reference`+`token`
SHOULD | patient+intent+authoredon | `reference`+`token`+`date`
SHOULD | patient+intent+status | `reference`+`token`+`token`

#### Resource Conformance: SHOULD MedicationStatement

Base System Profile
IPA-MedicationStatement
Profile Conformance
SHALL
Reference Policy
`resolves`

Interaction summary

- SHALL support `read`, `search-type`.

Documentation

> 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.

Search Parameters

Conformance | Parameter | Type | Documentation
--- | --- | --- | ---
SHALL | patient | `reference` | The client SHALL provide at least an id value and MAY provide both the Type and id values.
MAY | status | `token` | Return statements that match the given status

Combined Search Parameters

Conformance | Parameters | Types
--- | --- | ---
SHOULD | patient+status | `reference`+`token`

#### Resource Conformance: SHOULD Observation

Base System Profile
IPA-Observation
Profile Conformance
SHALL
Reference Policy
`resolves`

Supported Profiles

Vital Signs Profile

Interaction summary

- SHALL support `read`, `search-type`.

Search Parameters

Conformance | Parameter | Type | Documentation
--- | --- | --- | ---
MAY | category | `token` | The classification of the type of observation
MAY | code | `token` | The code of the observation type
MAY | date | `date` | Obtained date/time. If the obtained element is a period, a date that falls in the period
MAY | status | `token` | The status of the observation
MAY | patient | `reference` | The client SHALL provide at least an id value and MAY provide both the Type and id values. The server SHALL support both.

Combined Search Parameters

Conformance | Parameters | Types
--- | --- | ---
SHALL | patient+category | `reference`+`token`
SHALL | patient+code | `reference`+`token`
SHALL | patient+category+date | `reference`+`token`+`date`
SHOULD | patient+category+status | `reference`+`token`+`token`
SHOULD | patient+code+date | `reference`+`token`+`date`

#### Resource Conformance: SHALL Patient

Base System Profile
IPA-Patient
Profile Conformance
SHALL
Reference Policy
`resolves`

Interaction summary

- SHALL support `read`, `search-type`.

Documentation

> Servers SHALL support the capability for a client application to access the patient record using any of the following API calls:

> `GET [url]/Patient/[id]`

> `GET [url]/Patient?_id=[id]`

> `GET [url]/Patient?identifier=[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

Conformance | Parameter | Type | Documentation
--- | --- | --- | ---
SHALL | _id | `token` |
SHALL | identifier | `token` | The client SHALL provide both the system and code values. The server SHALL NOT support only code values.
SHOULD | birthdate | `date` | A client SHALL provide a value precise to the day. A server SHALL support a value a value precise to the day.
SHOULD | family | `string` |
SHOULD | gender | `token` | The client SHALL provide at least a code value and MAY provide both the system and code values. The server SHALL support both.
SHOULD | given | `string` |
SHOULD | name | `string` |

Combined Search Parameters

Conformance | Parameters | Types
--- | --- | ---
SHOULD | family+gender | `string`+`token`
SHOULD | birthdate+family | `date`+`string`
SHOULD | birthdate+name | `date`+`string`
SHOULD | gender+name | `token`+`string`

#### Resource Conformance: SHOULD Practitioner

Base System Profile
IPA-Practitioner
Profile Conformance
SHALL
Reference Policy
`resolves`

Interaction summary

- SHALL support `read`.

#### Resource Conformance: SHOULD PractitionerRole

Base System Profile
IPA-PractitionerRole
Profile Conformance
SHALL
Reference Policy
`resolves`

Interaction summary

- SHALL support `read`.