CIE Hub API Technical Documentation based on FHIR Standard
- Pete Richardson
- Bob Kreha
Page Links
The following is the technical documentation for the API for the Community Information Exchange (CIE) Hubs. The API conforms to the HL7 FHIR standard. For information on that standard please visit this page IG Home - SDOH Clinical Care v2.2.0 .
Authorization
The endpoints use the OAuth2 Authentication. The procedure can be found here Authorization . A CIE Hub administrator can provide credentials for acquiring an OAuth2 token. Please note that depending on your permissions your client id may be limited to certain OAuth2 scopes.
Objects Supported
The following FHIR resources are supported by the CIE Hub.
Resource | Description | FHIR Link |
|---|---|---|
This FHIR resource enables an authorized CIE partner organization to submit a service request to be processed by the CIE Hub. which could include managing the routing of that request, assigning it to a social navigator for outreach to the community member, additional assessments, or direct transfer to a performing social agency, as well as documenting the requesting organization. | HL7.FHIR.US.SDOH-CLINICALCARE\SDOHCC ServiceRequest - Definitions - FHIR v4.0.1 | |
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 . | HL7.FHIR.US.SDOH-CLINICALCARE\SDOHCC Observation Screening Response - FHIR v4.0.1 | |
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 on behalf of a community member. | http://hl7.org/fhir/us/core/STU4/StructureDefinition-us-core-organization.html |
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 or a federated partner directory accessible through the CIE Hub. | |
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 Project object interventions wherever possible. There will be services and interventions that do not yet have a specific Gravity code. | https://build.fhir.org/ig/HL7/fhir-sdoh-clinicalcare/StructureDefinition-SDOHCC-Procedure.html | |
Represents consent that was given by the individual to an organization to share information (make a service request) or perform a procedure. | https://hl7.org/fhir/us/sdoh-clinicalcare/2022jan/StructureDefinition-SDOHCC-Consent.html | |
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 an 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 an 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 new Patient ID will be returned. | |
Example Request Payload for Patient | ||
POST https://fhir.{baseURL}.org/Patient
{
"resourceType":"Patient",
"active":true,
"identifiers":
"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"
}
],
"identifier":[ // You can put in your patient id here or other id's that you would like the hub to track
{
"use":"official",
"type":{
"text":"patient_id"
},
"system":"{YOURID}.org",
"value":"3c60550b-7675-4dd4-872e-b0ba9450cd30"
}
],
} | ||
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
"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 from the previous step is used to create the FHIR resources. | Within the Bundle the following FHIR Resources can be added
Please note that Observations and Consent are optional. If all that is needed is a ServiceRequest object the referring org 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 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 an 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 parameter(s) can be used to get all of the service requests that have been previously submitted by your organization.
|
Retrieve a List of Service Requests that are assigned to your organization
The following will allow a service provider to get and manage their Service Requests in the CIE Hub
| Description | Implementation Links |
|---|---|---|
Retrieve an 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 your organization's 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.
|
|
Access the ServiceRequest in the Hub to update the status of the request, including your acceptance or rejection of the request, or simply that you received the ServiceRequest | This PUT call enables authorized CIE organizations to provide updates to the status of the request, which would typically then be shared with the requesting org. | PUT ServiceRequest/{id} |
Once you have completed the service request you can set the final status and add notes. Or create a Procedure in the status if you have completed an intervention on behalf of the community member/patient. | This PUT call enables authorized CIE organizations to provide final updates to the status of the request, which would typically then be shared with the requesting org. | PUT ServiceRequest/{id} https://build.fhir.org/servicerequest.html Optional POST Procedure https://build.fhir.org/procedure.html
|