• Verified
  • CIE Hub API Technical Documentation based on FHIR Standard

    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 https://build.fhir.org/ig/HL7/fhir-sdoh-clinicalcare/ .

    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

    Resource

    Description

    FHIR Link

    ServiceRequest

    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.

    https://hl7.org/fhir/us/sdoh-clinicalcare/2022jan/StructureDefinition-SDOHCC-ServiceRequest-definitions.html

    Observation

    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 .

    https://hl7.org/fhir/us/sdoh-clinicalcare/2022jan/StructureDefinition-SDOHCC-ObservationScreeningResponse.html

    Patient

    In the context of a CIE Hub, this FHIR resource is the person that is experiencing one or more social needs.

     

    http://hl7.org/fhir/us/core/STU4/StructureDefinition-us-core-patient.html

    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.

    http://hl7.org/fhir/R4/healthcareservice.html

    Location

    A location at which a service is offered or performed

    http://hl7.org/fhir/R4/location.html

    Procedure

    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

    Consent

    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

    Bundle

    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

    https://www.hl7.org/fhir/bundle.html

    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

    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.

    Authorization

    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.

    FHIR Patient

    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.

    FHIR Bundle

    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

     

    • please note that the bundle contains multiple resources that have been created. The response has a link to all of the resources that where created. The location contains the resource id that was created for the record.

     

    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

    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.

    Authorization

    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.

    ServiceRequest?_id={serviceRequestID}

    The following search parameter can be used to get a bundle of the ServiceRequest and all the associated Tasks

    ServiceRequest?_id={serviceRequestID}&_revinclude=Task:based-on

    The following parameter(s) can be used to get all of the service requests that have been previously submitted by your organization.

    Organization?_id=Value&_revinclude=ServiceRequest:requester&_revinclude=Task:based-on

     

     

    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

     

    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.

    Authorization

    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.

     

    GET ServiceRequest?performer=ORGANIZATION&status=NEW&_include=ServiceRequest:subject&_revinclude=Observation:based-on&_revinclude=Task:based-on

     

     

    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}

    https://build.fhir.org/servicerequest.html

    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

     

     

     

     

     

    Â