INTEROPen
0. References
HL7 UK | Care Connect Profile: Patient |
HL7 FHIR Resource: Patient |
User Stories: [DSTU2] Bristol Connecting Care POC |
1. Read
Return a single Patient for the specified id.
All requests SHALL contain a valid ‘Authorization’ header and SHALL contain an ‘Accept’ header. The `Accept` header indicates the format of the response the client is able to understand, this will be one of the following application/json+fhir or application/xml+fhir.
1.1. Response
A full set of response codes can be found here API Response Codes. FHIR Servers SHALL support the following response codes:
| 200 | successful operation |
| 404 | resource not found |
| 410 | resource deleted |
2. Search Parameters
Fetches a bundle of all Patient resources for the specified patient or search criteria.
All requests SHALL contain a valid ‘Authorization’ header and SHALL contain an ‘Accept’ header. The `Accept` header indicates the format of the response the client is able to understand, this will be one of the following application/json+fhir or application/xml+fhir.
2.1. Search Parameters
This implementation guide outlines some suggested search parameters for the Patient resource in the table below. To be conformant, provider systems are required to implement all of the SHALL parameters. Provider systems may implement the full list of search parameters for the Patient resource (HL7 FHIR STU3 Patient).
| Name | Type | Description | Conformance | Path |
|---|---|---|---|---|
address-postalcode |
string |
A postalCode specified in an address | MAY | Patient.address.postalCode |
birthdate |
date |
The patient's date of birth | SHALL | Patient.birthDate |
email |
token |
A value in an email contact | MAY | Patient.telecom (system=email) |
family |
string |
A portion of the family name of the patient | SHALL | Patient.name.family |
gender |
token |
Gender of the patient | SHALL | Patient.gender |
given |
string |
A portion of the given name of the patient | SHALL | Patient.name.given |
identifier |
token |
A patient identifier (NHS Number, Hospital Number, etc) | SHALL | Patient.identifier |
name |
string |
A portion of either family or given name of the patient | SHALL | Patient.name |
phone |
token |
A value in a phone contact | MAY | Patient.telecom(system=phone) |
Client systems SHALL provide at least two parameters of differing types, unless searching on identifier where one parameter is permitted. Systems SHALL support the following search combinations:
- name + gender
- name + birthdate
- family + gender
- given + gender
2.1.1. address-postalcode
See string for details on this parameter.
GET [baseUrl]/Patient?address-postalcode=NG10%201ZZ
Return all Patient resources with Post Code of NG10 1ZZ.2.1.2. birthdate
See date for details on this parameter. ‘birthdate’ can be used multiple times as a search parameter
GET [baseUrl]/Patient?birthdate=ge2010-01-01&birthdate=le2011-12-31
Return all Patient resources that have a birthdate greater than or equal to 1st Jan 2010, a birthdate less than or equal to 31st Dec 2011.2.1.3. email
See string for details on this parameter.
GET [baseUrl]/Patient?email=bernie.kanfeld@chumhum.com
Return all Patient resources with email address of bernie.kanfeld@chumhum.com.2.1.4. family
See string for details on this parameter.
GET [baseUrl]/Patient?family=kanfeld
Return all Patient resources with surname of Kanfeld.2.1.5. gender
GET [baseUrl]/Patient?gender=[code]
See token for details on this parameter.
GET [baseUrl]/Patient?gender=female
Return all Patient resources with Administrative Sex of female. 2.1.6. given
See string for details on this parameter.
GET [baseUrl]/Patient?given=bernie
Return all Patient resources with forename of Bernie.2.1.7. identifier (NHS Number, Hospital Number, etc)
GET [baseUrl]/Patient?identifier=[code]
See token for details on this parameter.
GET [baseUrl]/Patient?identifier=https://fhir.nhs.uk/Id/nhs-number|9876543210
Return all Patient resources with NHS Number of 9876543210.2.1.8. name
See string for details on this parameter.
GET [baseUrl]/Patient?name=bernie%20kanfeld
Return all Patient resources with name of Bernie Kanfeld.2.1.9. phone
See string for details on this parameter.
GET [baseUrl]/Patient?phone=07999123456
Return all Patient resources with phone number of 07999 123456.2.2. Search Response
If the search fails (cannot be executed, not that there is no matches), the return value is a status code 4xx or 5xx with an OperationOutcome.
If the search succeeds, the return content is a Bundle with type = searchset containing the results of the search as a list of resources in a defined order. The result list can be long, so servers MAY use paging. If they do, they SHALL use this Paging method for breaking the list into pages if appropriate. The server MAY also return an OperationOutcome resource with additional information about the search; if one is sent it SHALL NOT include any errors, and it shall be marked with an entry mode of include.
A full set of response codes can be found here API Response Codes. FHIR Servers SHALL support the following response codes:
| 200 | successful operation |
| 404 | resource not found |
| 410 | resource deleted |
3. Example
3.1 Request Query
3.1 cURL
Return all Patient resources with a NHS Number 9876543210, the format of the response body will be xml. The Reference Implementation is hosted at ‘https://data.developer.nhs.uk/ccri/’.
curl -X GET -H 'Accept: application/xml+fhir' -H 'Authorisation: BEARER [token]' -v 'https://data.developer.nhs.uk/ccri/STU3/Patient?identifier=https://fhir.nhs.uk/Id/nhs-number%7C9876543210'
3.2 Explore the Response
Explore the response in XML & JSON on the Reference Implementation below
Reference Implementation
XML Patient NHS number search RI viewer
JSON Patient NHS number search RI viewer