Operation Definition: Search Endpoint

Introduction

Search for active Endpoints where healthcare providers, which a patient has been registered at, make patient data available.

This operation does NOT change content.

Usage

Invocations

POST [base]/$search-endpoint

Parameters (In)

Name Cardinality Type Documentation
patient 1..1 Identifier Patient identifier, with system and value
apiSpecification 0..* uri Canonical ID of API Specification which the Endpoint implements

Valid patient identifiers

Return Values (Out)

Name Cardinality Type Documentation
return 1..1 Bundle Bundle of Endpoints that match the search criteria, together with the Organizations that make available the patient data at the endpoints. The Endpoints are referenced to from the Organizations using the Organization.endpoint element. If no Endpoints match the search criteria, the Bundle will be empty.

Validation messages

Validation messages are error, information or success messages that are returned as a result of an operation. These messages are returned in a OperationOutcome.

Error message Severity Parameter Comment
2-44-1: Required parameter missing. Error Parameters with cardinality 1..N must be supplied
2-44-2: Invalid format of personal identity number. Submit the personal identity number using 12 digits with or without hyphen, e.g. 198001032385. Error patient.valueIdentifier.value
2-44-3: Invalid format of coordination number. Submit the coordination number using 12 digits with or without hyphen, e.g. 198000602394. Error patient.valueIdentifier.value
2-44-4: Invalid system. Valid systems are http://electronichealth.se/identifier/personnummer, http://electronichealth.se/identifier/samordningsnummer. Error patient.valueIdentifier.system The Identifier.system value of parameter patient must be be from list of valid systems (see section Parameters (In) above)
2-44-9:Invalid parameter. Valid parameters are patient, healthcareProvider. Error

Examples

Example of request body

This example shows how to search for healthcare providers and the endpoints where they store patient data for the individual with personal identity number 198001092397. Note that the system ID http://electronichealth.se/identifier/personnummer is used for personal identity numbers. The request filters which endpoints should be returned by supplying two apiSpecification parameters.

{
"resourceType": "Parameters",
"id": "SearchEndpoint-VaccineAndDiagnosis-RequestBody",
"parameter": [
{
"name": "patient",
"valueIdentifier": {
"system": "http://electronichealth.se/identifier/personnummer",
"value": "198001092397"
}
},
{
"name": "apiSpecification",
"valueUri": "http://electronichealth.se/ntk/ActorDefinition/Utbildningsmiljo/exempel-vaccinationer-1"
},
{
"name": "apiSpecification",
"valueUri": "http://electronichealth.se/ntk/ActorDefinition/Utbildningsmiljo/exempel-diagnoser-1"
}
]
}
<Parameters xmlns="http://hl7.org/fhir">
<id value="SearchEndpoint-VaccineAndDiagnosis-RequestBody" />
<parameter>
<name value="patient" />
<valueIdentifier>
<system value="http://electronichealth.se/identifier/personnummer" />
<value value="198001092397" />
</valueIdentifier>
</parameter>
<parameter>
<name value="apiSpecification" />
<valueUri value="http://electronichealth.se/ntk/ActorDefinition/Utbildningsmiljo/exempel-vaccinationer-1" />
</parameter>
<parameter>
<name value="apiSpecification" />
<valueUri value="http://electronichealth.se/ntk/ActorDefinition/Utbildningsmiljo/exempel-diagnoser-1" />
</parameter>
</Parameters>

Example of successful response body

This example shows how the return body can look like when executing the operation, where the search parameters resulted in a match of one Endpoint where one Organization (healthcare provider) stores patient data. The Endpoint is referenced to by the Organization in the Organization.endpoint element, using the Endpoint's logical ID.

{
"resourceType": "Bundle",
"id": "102a4565-ff8c-489c-9ce0-392e56451126",
"type": "searchset",
"total": 2,
"link": [
{
"relation": "self",
"url": "[base]/$search-endpoint"
}
],
"entry": [
{
"fullUrl": "[base]/Endpoint/27a50668-ca2f-4333-9777-26a406944edd",
"resource": {
"resourceType": "Endpoint",
"id": "27a50668-ca2f-4333-9777-26a406944edd",
"meta": {
"profile": [
"http://electronichealth.se/fhir/NDI/StructureDefinition/endpoint-er"
]
},
"status": "active",
"connectionType": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/endpoint-connection-type",
"code": "hl7-fhir-rest"
}
]
}
],
"name": "Journalsystem 1",
"payload": [
{
"extension": [
{
"url": "http://electronichealth.se/fhir/NDI/StructureDefinition/endpoint-payload-actor-definition-er",
"valueCanonical": "http://electronichealth.se/ntk/ActorDefinition/Utbildningsmiljo/exempel-vaccinationer-1"
}
]
}
],
"address": "https://journalsystem1.exempel/fhir"
}
},
{
"fullUrl": "[base]/Organization/fb968068-aeaa-4795-9624-8664b74e64bc",
"resource": {
"resourceType": "Organization",
"id": "fb968068-aeaa-4795-9624-8664b74e64bc",
"meta": {
"profile": [
"http://electronichealth.se/fhir/NDI/StructureDefinition/organization-er"
]
},
"identifier": [
{
"system": "urn:oid:2.5.4.97",
"value": "5564362068"
}
],
"type": [
{
"coding": [
{
"system": "http://snomed.info/sct",
"version": "http://snomed.info/sct/45991000052106",
"code": "143591000052106",
"display": "vårdgivare"
}
]
}
],
"endpoint": [
{
"reference": "Endpoint/27a50668-ca2f-4333-9777-26a406944edd"
}
]
}
}
]
}
<Bundle xmlns="http://hl7.org/fhir">
<id value="102a4565-ff8c-489c-9ce0-392e56451126" />
<type value="searchset" />
<total value="2" />
<link>
<relation value="self" />
<url value="[base]/$search-endpoint" />
</link>
<entry>
<fullUrl value="[base]/Endpoint/27a50668-ca2f-4333-9777-26a406944edd" />
<resource>
<Endpoint>
<id value="27a50668-ca2f-4333-9777-26a406944edd" />
<meta>
<profile value="http://electronichealth.se/fhir/NDI/StructureDefinition/endpoint-er" />
</meta>
<status value="active" />
<connectionType>
<coding>
<system value="http://terminology.hl7.org/CodeSystem/endpoint-connection-type" />
<code value="hl7-fhir-rest" />
</coding>
</connectionType>
<name value="Journalsystem 1" />
<payload>
<extension url="http://electronichealth.se/fhir/NDI/StructureDefinition/endpoint-payload-actor-definition-er">
<valueCanonical value="http://electronichealth.se/ntk/ActorDefinition/Utbildningsmiljo/exempel-vaccinationer-1" />
</extension>
</payload>
<address value="https://journalsystem1.exempel/fhir" />
</Endpoint>
</resource>
</entry>
<entry>
<fullUrl value="[base]/Organization/fb968068-aeaa-4795-9624-8664b74e64bc" />
<resource>
<Organization>
<id value="fb968068-aeaa-4795-9624-8664b74e64bc" />
<meta>
<profile value="http://electronichealth.se/fhir/NDI/StructureDefinition/organization-er" />
</meta>
<identifier>
<system value="urn:oid:2.5.4.97" />
<value value="5564362068" />
</identifier>
<type>
<coding>
<system value="http://snomed.info/sct" />
<version value="http://snomed.info/sct/45991000052106" />
<code value="143591000052106" />
<display value="vårdgivare" />
</coding>
</type>
<endpoint>
<reference value="Endpoint/27a50668-ca2f-4333-9777-26a406944edd" />
</endpoint>
</Organization>
</resource>
</entry>
</Bundle>

Examples of failed response body

Errors are communicated by using a OperationOutcome that contains an error code and message in the issue.details element. The issue.severity indicates whether the issue is the cause of a failure, warning, information or success.

This example shows how an error is expressed when the format of a patient identifier is incorrect.

{
"resourceType": "OperationOutcome",
"id": "da2501bb-9efb-41a9-b0c7-266ab9dc6c2a",
"issue": [
{
"severity": "error",
"code": "value",
"details": {
"coding": [
{
"system": "http://electronichealth.se/CodeSystem/error-codes",
"code": "2-44-2",
"display": "Invalid format of personal identity number. Submit the personal identity number using 12 digits with or without hyphen, e.g. 198001032385."
}
]
},
"diagnostics": "patient.valueIdentifier.value"
}
]
}
<OperationOutcome xmlns="http://hl7.org/fhir">
<id value="da2501bb-9efb-41a9-b0c7-266ab9dc6c2a" />
<issue>
<severity value="error" />
<code value="value" />
<details>
<coding>
<system value="http://electronichealth.se/CodeSystem/error-codes" />
<code value="2-44-2" />
<display value="Invalid format of personal identity number. Submit the personal identity number using 12 digits with or without hyphen, e.g. 198001032385." />
</coding>
</details>
<diagnostics value="patient.valueIdentifier.value" />
</issue>
</OperationOutcome>

This example shows how an error is expressed when the system of a patient identifier is unknown.

{
"resourceType": "OperationOutcome",
"id": "1c227876-4b09-4adf-8bb0-629973bce4f6",
"issue": [
{
"severity": "error",
"code": "value",
"details": {
"coding": [
{
"system": "http://electronichealth.se/CodeSystem/error-codes",
"code": "2-44-4",
"display": "Invalid system. Valid systems are http://electronichealth.se/identifier/personnummer, http://electronichealth.se/identifier/\nsamordningsnummer."
}
]
},
"diagnostics": "patient.valueIdentifier.system"
}
]
}
<OperationOutcome xmlns="http://hl7.org/fhir">
<id value="1c227876-4b09-4adf-8bb0-629973bce4f6" />
<issue>
<severity value="error" />
<code value="value" />
<details>
<coding>
<system value="http://electronichealth.se/CodeSystem/error-codes" />
<code value="2-44-4" />
<display value="Invalid system. Valid systems are http://electronichealth.se/identifier/personnummer, http://electronichealth.se/identifier/\nsamordningsnummer." />
</coding>
</details>
<diagnostics value="patient.valueIdentifier.system" />
</issue>
</OperationOutcome>