Universal API Implementation Guide
1.1.19 - ci-build
Universal API Implementation Guide - Local Development build (v1.1.19). See the Directory of published versions
Genentech FHIR Server will return information in response to searches on the resources below:
| Resource | Parameters | Example |
|---|---|---|
| CoverageEligibilityResponse | SHOULD: status, outcome, request, patient | GET [base]/CoverageEligibilityResponse?status=active |
Coverage, Organization and Practitioner resources will be included as contained resources within CoverageEligibilityResponse. They will not be persisted in corresponding resource tables in FHIR Server.
If the requested resource is not supported then search-result will include OperationOutcome indicating that either specific Resource or Parameters are not supported.
The UAPI Query message requests specific information from Genentech FHIR Server. The desired information is specified as FHIR search statements which are sent as “query-string” parameters in the message. Genentech FHIR Server executes these searches for the Organization which is identified in MessageHeader by two attributes - the source.name and sender.identifier.value, which need to be concatenated to execute Organization search in Genentech FHIR Server. The results are returned for single Patient within above Organization, identified using “requester-patient” parameter in the message - the identifier used to execute Patient search in Genentech FHIR Server is passed in identifier.value field.
For example:
"resourceType" : "MessageHeader",
"id" : "04ba6102-8344-4c3e-b96e-e9fc75a7840c",
"eventCoding" : {
"system" : "http://hl7.org/fhir/us/specialty-rx/CodeSystem/specialty-rx-event-type",
"code" : "query"
},
"sender" : {
"type" : "Organization",
"identifier" : {
"use" : "usual",
"system" : "http://vendor.com/ab",
"value" : "HOSP-12345",
"assigner" : {
"display" : "AB Vendor"
}
}
},
"source" : {
"name" : "Vendor_AB",
"endpoint" : "http://vendor.com/ab"
},
The above MessageHeader identifies Organization for specific Vendor system - source.name = “Vendor_AB” with organization identifier - sender.identifier.value = “HOSP-12345”. This results in matching in Genentech FHIR server to Organization with “official” identifier = Vendor_AB_HOSP-12345.
"resourceType" : "Parameters",
"id" : "61ebe359-bfdc-4613-8bf2-c5e300945f0b",
"parameter" : [
{
"name" : "requester-patient",
"valueReference" : {
"type" : "Patient",
"identifier" : {
"use" : "official",
"type" : {
"coding" : [
{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0203",
"code" : "PI",
"display" : "Patient internal identifier"
}
]
},
"system" : "http://vendor.com/ab",
"value" : "6bcd8467-0473-4836-9128-2e7972f23177",
"assigner" : {
"display" : "AB Vendor"
}
}
}
},
The above “requester-patient” parameter identifies Patient within Organization by “official” identifier - identifier.value = “6bcd8467-0473-4836-9128-2e7972f23177”
The “query-string” parameters can request CoverageEligibilityResponse resources for given Patient within Organization.
Example:
"resourceType" : "Parameters",
"id" : "61ebe359-bfdc-4613-8bf2-c5e300945f0b",
"parameter" : [
{
"name" : "requester-patient",
"valueReference" : {
"type" : "Patient",
"identifier" : {
"use" : "official",
"type" : {
"coding" : [
{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0203",
"code" : "PI",
"display" : "Patient internal identifier"
}
]
},
"system" : "http://vendor.com/ab",
"value" : "6bcd8467-0473-4836-9128-2e7972f23177",
"assigner" : {
"display" : "AB Vendor"
}
}
}
},
{
"name" : "query-string",
"valueString" : "CoverageEligibilityResponse?status=active"
}
This will result in internal query in FHIR server:
GET [base]/CoverageEligibilityResponse?status=active&patient=<internal fhirid>
The above will return ALL CoverageEligibilityResponse resources which were received for given Patient in the Organization.
If Patient was submitted in multiple enrollments then those results might need to be filtered out further.
In order to narrow down search results to only specific enrollment transaction “requester-bundle-enrollment-id” parameter SHOULD be used.
Example:
"resourceType" : "Parameters",
"id" : "61ebe359-bfdc-4613-8bf2-c5e300945f0b",
"parameter" : [
{
"name" : "requester-patient",
"valueReference" : {
"type" : "Patient",
"identifier" : {
"use" : "official",
"type" : {
"coding" : [
{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0203",
"code" : "PI",
"display" : "Patient internal identifier"
}
]
},
"system" : "http://vendor.com/ab",
"value" : "6bcd8467-0473-4836-9128-2e7972f23177",
"assigner" : {
"display" : "AB Vendor"
}
}
}
},
{
"name" : "requester-bundle-enrollment-id",
"valueReference" : {
"type" : "Bundle",
"identifier" : {
"type" : {
"coding" : [
{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0203",
"code" : "RI",
"display" : "Resource identifier"
}
]
},
"system" : "http://dev.gene.com/fhir/uapi/enrollment/transactionid",
"value" : "b73f7586-0be9-4cdf-8c98-4fe120e09bb9"
}
}
},
{
"name" : "query-string",
"valueString" : "CoverageEligibilityResponse?status=active"
}
This will result in series of internal queries in FHIR server:
GET [base]/CoverageEligibilityRequest?identifier=http://dev.gene.com/fhir/uapi/enrollment/transactionid|b73f7586-0be9-4cdf-8c98-4fe120e09bb9&patient=<internal fhirid>
GET [base]/CoverageEligibilityResponse?status=active&patient=<internal fhirid>&request=<request id from #1>
The above will return specific CoverageEligibilityResponse resources associated with enrollment transaction id which were requested for given Patient in the Organization.
In order to narrow down search results to only specific service requests types “requester-servicerequest” parameter SHOULD be used.
Example:
"resourceType" : "Parameters",
"id" : "61ebe359-bfdc-4613-8bf2-c5e300945f0b",
"parameter" : [
{
"name" : "requester-patient",
"valueReference" : {
"type" : "Patient",
"identifier" : {
"use" : "official",
"type" : {
"coding" : [
{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0203",
"code" : "PI",
"display" : "Patient internal identifier"
}
]
},
"system" : "http://vendor.com/ab",
"value" : "6bcd8467-0473-4836-9128-2e7972f23177",
"assigner" : {
"display" : "AB Vendor"
}
}
}
},
{
"name" : "requester-servicerequest",
"valueReference" : {
"reference" : "urn:uuid:aecbb129-9a73-4b59-9d66-ff5cdb3f3164"
}
},
{
"name" : "requester-servicerequest",
"valueReference" : {
"reference" : "urn:uuid:47aaa05f-33fe-4672-b0bf-0168bdd81630"
}
},
{
"name" : "query-string",
"valueString" : "CoverageEligibilityResponse?status=active"
}
The “requester-servicerequest” parametere is a reference to ServiceRequest resources which are included in the message query bundle. Currently only code.coding.code value is used for filtering.
Example:
{
"fullUrl" : "urn:uuid:aecbb129-9a73-4b59-9d66-ff5cdb3f3164",
"resource" : {
"resourceType" : "ServiceRequest",
"id" : "sr4gpf",
"meta" : {
"profile" : [
"http://dev.gene.com/fhir/uapi/StructureDefinition/uapi-servicerequest"
]
},
"status" : "active",
"intent" : "order",
"code" : {
"coding" : [
{
"system" : "http://terminology.gene.com/fhir/usix/uapi/CodeSystem/uapi-sr-type",
"code" : "gpf"
}
]
},
"subject" : {
"reference" : "urn:uuid:fc2e5a72-c363-4616-ae00-4ad25cbcb45c",
"type" : "Patient"
}
}
}
In the above example code.coding.code = “gpf” is the value which will be used by FHIR Server to narrow down search results.
This will result in series of internal queries in FHIR server:
GET [base]/CoverageEligibilityRequest?patient=<internal fhirid>&uapi-sr-type=gpf
GET [base]/CoverageEligibilityResponse?status=active&patient=<internal fhirid>&request=<request id from #1>
The above will return specific CoverageEligibilityResponse resources associated with service request type(s) which were requested for given Patient in the Organization.