CIE Hub API Based on FHIR Standard
Page Links
The following is the technical documentation for the API for the 211 Community Information Exchange (CIE) Hubs. The API conforms to the HL7 FHIR standard. For information on that standard please visit this page https://build.fhir.org/ig/HL7/fhir-sdoh-clinicalcare/ .
Authorization
The endpoints use the OAuth2 Authentication. The procedure can be found here https://brightstreetgroup.atlassian.net/wiki/spaces/CIEP/pages/1309802703 . A CIE Hub admin can provide credentials for getting a OAuth2 token. Please note that depending on your permissions your client id may be limited to certain scopes.
Objects Supported
The following FHIR resources will be supported by the CIE Hub.
Resource | Description | FHIR Link |
|---|---|---|
This FHIR resource enables a client to request a service to be performed whereby the CIE Hub manages the routing of that request as well as documenting who the requester is. | https://hl7.org/fhir/us/sdoh-clinicalcare/2022jan/StructureDefinition-SDOHCC-ServiceRequest-definitions.html | |
An observation is the accepted generic term for information associated with an individual that aids in documenting the specific circumstances/needs that the individual is currently experiencing. For example, an observation can be the results of a SDOH screening, an assessment value that is coded in SNOMED, LOINC, or Gravity project codes, or a narrative explaining the reason for the service request . |
| |
In the context of a CIE Hub, this FHIR resource is the person that is experiencing one or more social needs. |
| |
Organization | This resource is either the organization performing a service/fulfilling a need or the organization requesting a service for a community member. |
|
HealthCareService | This represents a specific service that can be performed by a Community Based Organization or other social services entity. This service will have the same id as its record in the statewide 211 social services directory. |
|
Location | A location at which a service is offered or performed |
|
This FHIR resource is being used as the repository of intervention(s) for an individual and corresponds to Gravity Works object intervention. |
| |
Represents consent that was given by the individual to an organization to share information (make a service request) or perform a procedure. |
| |
A bundle is a JSON payload that can contain one or more of the FHIR Objects that can be transmitted simultaneously to the CIE Hub |
|
Common Use Cases with Examples
The following will be common use cases that may require multiple FHIR resources and the flow.
Submit a Service Request with Associated Assessment
The flow will use the following resources Service Request, Patient, Observations, Consent.
Sequence Diagram
Submit a Service Request Sequence Diagram
Implementation Details
The following are the implementation details broken down by steps in the process.
Process Step | Description | Implementation Links |
|---|---|---|
Retrieve a OAuth2 Bearer token | Using the standard OAuth2 client credentials (CIE Admin will give a client ID and Secret) flow get a Bearer Token. This token will be used to make calls to the API. |
|
Process the Patient | This step will process the patient in the CIE Hub. The one POST method will check to see if a existing patient is already in the system and if that is the case the existing PatientId will be returned. If the Patient is not found then a new Patient will be created in the system and the Patient ID will be returned. |
|
Example Request Payload for Patient | ||
POST https://fhir.{baseURL}.org/Patient
{
"resourceType":"Patient",
"active":true,
"name":[
{
"use":"official",
"family":"Tester",
"given":[
"Test"
]
}
],
"telecom":[
{
"system":"phone",
"value":"(616) 111-1111",
"use":"mobile"
},
{
"system":"phone",
"value":"(616) 111-1111",
"use":"home"
},
{
"system":"email",
"value":"test@test.com",
"use":"home"
}
],
"address":[
{
"use":"home",
"type":"physical",
"text":"15821 Vine Avenue, Spring Lake, MI, USA",
"line":[
"15821 Vine Avenue"
],
"city":"Spring Lake",
"state":"Michigan",
"district":"Ottawa",
"postalCode":"49456"
}
],
"managingOrganization":{
"reference":"Organization/MI211"
}
} | ||
Example Response | ||
{
"status": 201,
"statusText": "Created",
"data": {
"active": true,
"address": [
{
"city": "Spring Lake",
"district": "Ottawa",
"line": [
"15821 Vine Avenue"
],
"postalCode": "49456",
"state": "Michigan",
"text": "15821 Vine Avenue, Spring Lake, MI, USA",
"type": "physical",
"use": "home"
}
],
"id": "ab08def6-03de-43b0-a9c3-f33041315bd1", // This will be the ID that was created or retrieved
"managingOrganization": {
"reference": "Organization/MI211"
},
"meta": {
"lastUpdated": "2023-02-22T14:10:28.823605+00:00",
"versionId": "MTY3NzA3NTAyODgyMzYwNTAwMA"
},
"name": [
{
"family": "Tester",
"given": [
"Test"
],
"use": "official"
}
],
"resourceType": "Patient",
"telecom": [
{
"system": "phone",
"use": "mobile",
"value": "(616) 111-1111"
},
{
"system": "phone",
"use": "home",
"value": "(616) 111-1111"
},
{
"system": "email",
"use": "home",
"value": "test@test.com"
}
]
},
"success": true
} | ||
Process the ServiceRequest Bundle | This step will take a bundle of multiple FHIR Resources that represent a Service Request and save in the CIE. The Patient ID will from the previous step can be used to create the resources. |
Within the Bundle the following FHIR Resources can be added
Please not that Observations and Consent are optional. If all you need is a ServiceRequest object you can just call POST \ServiceRequest. |
Example ServiceRequest Payload Bundle with ServiceRequest, Consent, Observation | ||
{
"resourceType":"Bundle",
"type":"transaction",
"entry":[
{
"request":{
"method":"POST",
"url":"Consent"
},
"fullUrl":"urn:uuid:3018c9a8-8ad3-4bce-a5bc-bf37e190c756",
"resource":{
"resourceType":"Consent",
"status":"active",
"scope":{
"coding":[
{
"system":"http://terminology.hl7.org/CodeSystem/consentscope",
"code":"patient-privacy"
}
]
},
"category":[
{
"coding":[
{
"system":"http://loinc.org",
"code":"59284-0"
}
]
}
],
"patient":{
"reference":"Patient/ab08def6-03de-43b0-a9c3-f33041315bd1" // This will be id from Patient post call
},
"dateTime":"2018-12-28",
"organization":[
{
"reference":"Organization/MI211"
}
],
"policy":[ // This will be a link to your policy document
{
"authority":"mi211.org",
"uri":"https://mi211.org/homevisiting"
}
],
"provision":{
"type":"deny",
"provision":[
{
"type":"permit",
"period":{
"start":"1964-01-01",
"end":"2019-01-01"
}
}
]
}
}
},
{
"request":{
"method":"POST",
"url":"Observation"
},
"fullUrl":"urn:uuid:03c67275-8caa-43a4-b30d-11026872f230",
"resource":{
"resourceType":"Observation",
"status":"final",
"code":{ // This will set the code for the observation. It can be a loinc, snowmed, gravity, or custom.
"coding":[
{
"system":"https://loinc.org",
"code":"99951-6",
"display":"Zip Code" // This will be the display of the observation. For a assessment it will be the assessment quesiton
}
]
},
"effectiveDateTime":"2023-02-22T09:10:31.000Z",
"valueString":"49456-Ottawa",
"subject":{
"reference":"Patient/ab08def6-03de-43b0-a9c3-f33041315bd1" // This will be
},
"basedOn":[
{
"reference":"urn:uuid:a5d7c250-4410-4409-915f-80b5193a633e",
"type":"ServiceRequest"
}
]
}
},
{
"request":{
"method":"POST",
"url":"Observation"
},
"fullUrl":"urn:uuid:31d786b5-d334-4ea5-b8f8-f861418f8d8e",
"resource":{
"resourceType":"Observation",
"status":"final",
"code":{
"coding":[
{
"system":"https://loinc.org",
"code":"97071-5",
"display":"Is someone in the household currently pregnant"
}
]
},
"effectiveDateTime":"2023-02-22T09:10:31.000Z",
"valueBoolean":true,
"subject":{
"reference":"Patient/ab08def6-03de-43b0-a9c3-f33041315bd1"
},
"basedOn":[
{
"reference":"urn:uuid:a5d7c250-4410-4409-915f-80b5193a633e",
"type":"ServiceRequest"
}
]
}
},
{
"request":{
"method":"POST",
"url":"Observation"
},
"fullUrl":"urn:uuid:6b9a532b-ace9-49b3-a690-87ffc560b00e",
"resource":{
"resourceType":"Observation",
"status":"final",
"code":{
"coding":[
{
"system":"https://loinc.org",
"code":"63962-5",
"display":"Pregnancy Type"
}
]
},
"effectiveDateTime":"2023-02-22T09:10:31.000Z",
"valueString":"First Pregnancy",
"subject":{
"reference":"Patient/ab08def6-03de-43b0-a9c3-f33041315bd1"
},
"basedOn":[
{
"reference":"urn:uuid:a5d7c250-4410-4409-915f-80b5193a633e",
"type":"ServiceRequest"
}
]
}
},
{
"request":{
"method":"POST",
"url":"Observation"
},
"fullUrl":"urn:uuid:0ab16d31-66d9-4d6d-82e9-d4ac0b2669e7",
"resource":{
"resourceType":"Observation",
"status":"final",
"code":{
"coding":[
{
"system":"https://loinc.org",
"code":"95369-5",
"display":"Affiliated with a tribe"
}
]
},
"effectiveDateTime":"2023-02-22T09:10:31.000Z",
"valueBoolean":true,
"subject":{
"reference":"Patient/ab08def6-03de-43b0-a9c3-f33041315bd1"
},
"basedOn":[
{
"reference":"urn:uuid:a5d7c250-4410-4409-915f-80b5193a633e",
"type":"ServiceRequest"
}
]
}
},
{
"request":{
"method":"POST",
"url":"Observation"
},
"fullUrl":"urn:uuid:d65bc85c-6a09-40fd-895c-fe1be6e0bd70",
"resource":{
"resourceType":"Observation",
"status":"final",
"code":{
"coding":[
{
"system":"https://loinc.org",
"code":"MI211-27268-1",
"display":"Number of children under the age of 6 living in household"
}
]
},
"effectiveDateTime":"2023-02-22T09:10:31.000Z",
"valueInteger":0,
"subject":{
"reference":"Patient/ab08def6-03de-43b0-a9c3-f33041315bd1"
},
"basedOn":[
{
"reference":"urn:uuid:a5d7c250-4410-4409-915f-80b5193a633e",
"type":"ServiceRequest"
}
]
}
},
{
"request":{
"method":"POST",
"url":"ServiceRequest"
},
"fullUrl":"urn:uuid:a5d7c250-4410-4409-915f-80b5193a633e",
"resource":{
"resourceType":"ServiceRequest",
"identifier":[ // You can put in assessment id here or other id's that you would like the hub to track
{
"use":"official",
"type":{
"text":"recommendation_id"
},
"system":"mi211.org",
"value":"3c60550b-7675-4dd4-872e-b0ba9450cd30"
}
],
"requisition":{
"use":"official",
"system":"https://mi211.org",
"value":"9SvBgU658WUCFncmwtdLEp"
},
"status":"active",
"intent":"original-order",
"category":[ // Can put in a category code here to futher define metadata about the service
{
"coding":[
{
"system":"http://mi211.org",
"code":"home-visiting",
"display":"Home Visiting"
}
]
}
],
"code":{ // This could be left blank or if a specific Service is being requested this can be filled in
"coding":[
{
"system":"https://211taxonomy.org/",
"code":"Family Spirit",
"display":"Family Spirit"
},
{
"system":"https://211taxonomy.org/",
"code":"Maternal Infant Health Program",
"display":"Maternal Infant Health Program"
}
]
},
"requester":{
"reference":"Patient/ab08def6-03de-43b0-a9c3-f33041315bd1"
},
"subject":{
"reference":"Patient/ab08def6-03de-43b0-a9c3-f33041315bd1"
},
"supportingInfo":[
{
"reference":"urn:uuid:3018c9a8-8ad3-4bce-a5bc-bf37e190c756",
"type":"Consent"
}
],
"performer":[ // This could be a requested performer that corresponds to a ID in our Social Services Directory API
{
"reference":"HealthcareService/168526",
"type":"HealthcareService"
},
{
"reference":"HealthcareService/40366",
"type":"HealthcareService"
}
]
}
}
]
} | ||
Example ServiceRequest Response Bundle with ServiceRequest, Consent, Observation | ||
| ||
Get the Status of a Previously Submitted ServiceRequest
The following will retrieve the status of a previous submitted ServiceRequest. Please note that you can also request all of your organizations open ServiceRequests also with query parameters on the get call.
Sequence Diagram
Implementation Details
The following are the implementation details broken down by steps in the process.
Process Step | Description | Implementation Links |
|---|---|---|
Retrieve a OAuth2 Bearer token | Using the standard OAuth2 client credentials (CIE Admin will give a client ID and Secret) flow get a Bearer Token. This token will be used to make calls to the API. |
|
Get the ServiceRequest | This step will get the ServiceRequest resource. There is a status in the payload that can be checked. More details around the ServiceRequest can also be queried including the Tasks that are in the workflow with data and notes at the Task Level. | The following search parameter can be used to just get the ServiceRequest.
The following search parameter can be used to get a bundle of the ServiceRequest and all the associated Tasks
The following you can use to get all of the service requests that have been requested by your organization.
|
Retrieve a List of Service Requests that are assigned to organization
The following will allow a client to get and manage service Requests in the CIE Hub
| Description | Implementation Links |
|---|---|---|
Retrieve a OAuth2 Bearer token | Using the standard OAuth2 client credentials (CIE Admin will give a client ID and Secret) flow get a Bearer Token. This token will be used to make calls to the API. |
|
Query for for your organizations Service Requests. | You would use the FHIR endpoint to query for a list of Service Requests that have been assigned to your organization. Along with the Service Request you will also get the Patient, Observations and any tasks that will be associated with that Service Request.
|
|
Update the ServiceRequest in the Hub to update the status that you received the ServiceRequest | You will need to keep the ServcieRequest updated in the system so that we can track and give feedback to the requester | PUT ServiceRequest/{id}
|
Once you have completed the service request you can set the status and add notes. Or create a Procedure in the status if you have done a intervention. | Once this is done we can update the requester of the ServiceRequest that this has been completed | PUT ServiceRequest/{id}
Optional POST Procedure
|