FHIR API


Roche Diabetes Care exposes an API using HL7 FHIR (Fast Healthcare Interoperability Resources) STU3 in order to allow EMRs, PHRs and other systems to communicate with Roche ecosystem.

FHIR is a standard for exchanging healthcare data electronically and takes a modern, web-based approach to API design. For more information about how to use FHIR, please visit the HL7 FHIR STU3 Documentation.


API INFORMATION


Title: FHIR API

Protocols: HTTPS

URI Live: https://api-services-eu.rochedcplatform.com/partners/fhir/stu3/api/

URI Demo: https://api-services-demo.rochedcplatform-sandbox.com/partners/fhir/stu3/api/

Swagger file: here


AUTHENTICATION


FHIR API is secured with mutual TLS for identifying both parties and for securing communication between systems.

More information can be found here: API Authentication


FHIR PROFILES


Below are the list of profiles used in Patient transactions like creation and update.

Below are the list of profiles used in practitioner transactions like creation and update.


ENDPOINTS




FHIR API: Patient Update v1


Note

This API version will be deprecated. We encourage you to migrate to the latest version of the API. You can find the documentation for the new API version at Patient Update v2.

Pre-requisites


Resource:

PUT /partners/fhir/stu3/api/Bundle/{patientIdentifier}

Authentication:

Endpoint is secured with mutual TLS. More information can be found here: API Authentication


API Request

Request Parameters

Name Description Type Required Example
patientIdentifier Patient business ID of the patient to be updated.
Note: patient.identifier.value received in the response of the Patient Creation v1 API		 String Yes 12345678Z

Request Headers

Name Description Type Required Example
org_id Organization OID String Yes 2.16.724.4.2
x-origin-request-id Request Unique ID generated by EMR middleware (UUID) String Yes 5109d51b-421e-4746-b673-16e3fe2b3442"
client_id Public identifier for organizations generated by Roche DC String Yes 1234567890
client_secret Client related secret known only to the EMR and Roche DC String Yes 1234567890
Content-Type json or fhir+json String Yes application/json or application/fhir+json

Profile overview

The list of profiles used in Patient Creation.


Request Example

  • The phone number of the patient with business id 12345678Z (already created in RDC) is updated from "123123123" to "123456789":
curl --location --request PUT 'https://api-services-eu.rochedcplatform.com/partners/fhir/stu3/api/v2/Bundle/12345678Z' \
--header 'client_id: 1234567890' \
--header 'client_secret: 1234567890' \
--header 'Content-Type: application/fhir+json' \
--header 'org_Id: 2.16.724.4.2' \
--data-raw '{
    "resourceType": "Bundle",
    "type": "message",
    "entry": [
        {
             "resource": {
                "resourceType": "MessageHeader",
                "id": "88a37162-3d7c-41c3-89ab-6e25fd68ba00",
                "event": {
                    "code": "new-bundle",
                    "system": "http://roche.com/fhir/rdc/message-type",
                    "display": "New bundle generated"
                },
                "source": {
                    "endpoint": "<Organization OID>",
                    "software": "EMR middleware",
                    "version": "1.0.0"
                },
                "timestamp": "2020-03-27T12:21:39.471Z",
                "meta": {
                    "profile":  [
                        "http://roche.com/fhir/rdc/StructureDefinition/message-header"
                    ]
                }
            }
        },
        {
            "resource": {
                "resourceType": "Patient",
                "meta": {
                	"profile":  [
                        "http://roche.com/fhir/rdc/StructureDefinition/patient-v2"
                    ]
                },
                "id": "12345678Z",
                "identifier": [
                    {
                        "system": "urn:oid:2.16.724.4.41",
                        "value": "12345678Z"
                    }
                ],
                "name": [
                    {
                        "family": "Doe",
                        "given": [
                            "John"
                        ]
                    }
                ],
                "telecom": [
                    {
                        "system": "phone",
                        "value": "123456789"
                    },
                    {
                        "system": "email",
                        "value": "johndoe123@email.com"
                    }
                ],
                "gender": "male",
                "birthDate": "1991-01-01"
            }
        },
        {
            "resource": {
                "resourceType": "Condition",
                "clinicalStatus": "active",
                "code": {
                    "coding": [
                        {
                            "system": "http://snomed.info/sct",
                            "code": "426875007",
                            "display": "Latent autoimmune diabetes mellitus in adult (disorder)"
                        }
                    ]
                },
                "subject": {
                    "reference": "Patient/sample-id-454b-b5c7-f1ed1fb4ght"
                }
            }
        }
    ]
}'

API Response

API code response

HTTP Response Code Description Response Body FHIR error code FHIR error code description
200 Patient Bundle updated Empty NA NA
400 Request failed because of incorrect parameters, returns no data OperationOutcome required Request failed because of incorrect parameters, returns no data
400 Request failed because of incorrect parameters, returns no data OperationOutcome structure A structural issue in the content such as wrong namespace, or unable to parse the content completely, or invalid json syntax.
400 Request failed because of incorrect parameters, returns no data OperationOutcome invalid Content invalid against the specification or a profile.
401 Request failed with unauthorized access, returns no data Empty NA NA
404 Patient Not Found OperationOutcome not-found Patient Not Found
405 Method Not Allowed Empty NA NA
415 Unsupported Media Type OperationOutcome not-supported Content-Type is not one of (application/json, application/fhir+json)
500 Request failed with internal exception OperationOutcome exception Internal server error.
501 Not implemented Empty NA NA

API Payload response

Successful response object: On successful updated Patient through API will return HTTP 200 Status Code with empty body.


Error response object:

As an example, if we try to update a record that does not exist, we will obtain a 404 HTTP error status code together the following response body:

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "not-found",
            "diagnostics": "Patient not found"
        }
    ]
}


FHIR API: Patient Creation v2


Pre-requisites


Resource:

POST /partners/fhir/stu3/api/v2/Bundle

Authentication:

Endpoint is secured with mutual TLS. More information can be found here: API Authentication


API Request

Request Headers

Name Description Type Required Example
org_id Organization OID String Yes 2.16.724.4.2
x-origin-request-id Request Unique ID generated by EMR middleware (UUID) String Yes 5109d51b-421e-4746-b673-16e3fe2b3442
client_id Public identifier for organizations generated by Roche DC String Yes 1234567890
client_secret Client related secret known only to the EMR and Roche DC String Yes 1234567890
Content-Type json or fhir+json String Yes application/json or application/fhir+json

Profile overview

The list of profiles used in Patient Creation.

Note

While creating a patient, the patient identifier value and the email must be unique.

Starting from the Patient Creation v2 API, the 'patient.managingOrganization' field can be sent as a optional parameter in the payload.


Request Example

  • Patient Request example with Type-1 diabetes condition:
curl --location --request POST 'https://api-services-eu.rochedcplatform.com/partners/fhir/stu3/api/v2/Bundle' \
--header 'client_id: 1234567890' \
--header 'client_secret: 1234567890' \
--header 'Content-Type: application/fhir+json' \
--header 'org_Id: 2.16.724.4.2' \
--data-raw '{
    "resourceType": "Bundle",
    "type": "message",
    "entry": [
        {
             "resource": {
                "resourceType": "MessageHeader",
                "id": "88a37162-3d7c-41c3-89ab-6e25fd68ba00",
                "event": {
                    "code": "new-bundle",
                    "system": "http://roche.com/fhir/rdc/message-type",
                    "display": "New bundle generated"
                },
                "source": {
                    "endpoint": "<Organization OID>",
                    "software": "EMR middleware",
                    "version": "1.0.0"
                },
                "timestamp": "2020-03-27T12:21:39.471Z",
                "meta": {
                    "profile":  [
                        "http://roche.com/fhir/rdc/StructureDefinition/message-header"
                    ]
                }
            }
        },
        {
            "resource": {
                "resourceType": "Patient",
                "meta": {
                	"profile":  [
                        "http://roche.com/fhir/rdc/StructureDefinition/patient-v2"
                    ]
                },
                "identifier": [
                    {
                        "system": "urn:oid:2.16.724.4.41",
                        "value": "12345678Z"
                    }
                ],
                "name": [
                    {
                        "family": "Doe",
                        "given": [
                            "John"
                        ]
                    }
                ],
                "telecom": [
                    {
                        "system": "phone",
                        "value": "123123123"
                    },
                    {
                        "system": "email",
                        "value": "johndoe123@email.com"
                    }
                ],
                "gender": "male",
                "birthDate": "1991-01-01",
                "managingOrganization": {
                    "identifier": [
                    {
                        "system": "urn:oid:1.3.6.1.4.1.56221.1.1",
                        "value": "2.16.724.4.2"
                    }
                    ]
                }
            }
        },
        {
            "resource": {
                "resourceType": "Condition",
                "clinicalStatus": "active",
                "code": {
                    "coding": [
                        {
                            "system": "http://snomed.info/sct",
                            "code": "426875007",
                            "display": "Latent autoimmune diabetes mellitus in adult (disorder)"
                        }
                    ]
                },
                "subject": {
                    "reference": "Patient/sample-id-454b-b5c7-f1ed1fb4ght"
                }
            }
        }
    ]
}'

API Response

API code response

HTTP Response Code Description Response Body FHIR error code FHIR error code description
201 Patient Bundle created Bundle NA NA
400 Request failed because of incorrect parameters, returns no data OperationOutcome required Request failed because of incorrect parameters, returns no data
400 Request failed because of incorrect parameters, returns no data OperationOutcome structure A structural issue in the content such as wrong namespace, or unable to parse the content completely, or invalid json syntax.
400 Request failed because of incorrect parameters, returns no data OperationOutcome invalid Content invalid against the specification or a profile.
401 Request failed with unauthorized access, returns no data Empty NA NA
403 Not Authorized, organization id not valid Empty NA NA
405 Method Not Allowed Empty NA NA
415 Unsupported Media Type. OperationOutcome not-supported Content-Type is not one of (application/json, application/fhir+json)
422 Unprocessed Entity OperationOutcome exception FHIRID creation failed. Retrieval of FHIRID from RDCP identities exceeded pre-defined Timeout
422 Conflict / User already exists OperationOutcome duplicate The resource already exists. Please retrieve the fhir-id from the field details.text and use it to request an update to the existing resource.
Note: the error response object also includes the expression field and the patient.id in the details.text field.
500 Request failed with internal exception OperationOutcome exception Internal server error.
501 Not implemented Empty NA NA

API Payload response

Successful response object:

{
    "resourceType": "Bundle",
    "type": "message",
    "entry": [
        {
             "resource": {
                "resourceType": "MessageHeader",
                "id": "88a37162-3d7c-41c3-89ab-6e25fd68ba00",
                "event": {
                    "code": "new-bundle",
                    "system": "http://roche.com/fhir/rdc/message-type",
                    "display": "New bundle generated"
                },
                "source": {
                    "endpoint": "<Organization OID>",
                    "software": "EMR middleware",
                    "version": "1.0.0"
                },
                "timestamp": "2020-03-27T12:21:39.471Z",
                "meta": {
                    "profile":  [
                        "http://roche.com/fhir/rdc/StructureDefinition/message-header"
                    ]
                }
            }
        },
        {
            "resource": {
                "resourceType": "Patient",
                "meta": {
                	"profile":  [
                        "http://roche.com/fhir/rdc/StructureDefinition/patient-v2"
                    ]
                },
                "id": "Bj6.1Lq-hvb-28",
                "identifier": [
                    {
                        "system": "urn:oid:2.16.724.4.41",
                        "value": "12345678Z"
                    }
                ],
                "name": [
                    {
                        "family": "Doe",
                        "given": [
                            "John"
                        ]
                    }
                ],
                "telecom": [
                    {
                        "system": "phone",
                        "value": "123123123"
                    },
                    {
                        "system": "email",
                        "value": "johndoe123@email.com"
                    }
                ],
                "gender": "male",
                "birthDate": "1991-01-01",
                "managingOrganization": {
                    "identifier": [
                    {
                        "system": "urn:oid:1.3.6.1.4.1.56221.1.1",
                        "value": "2.16.724.4.2"
                    }
                    ]
                }
            }
        },
        {
            "resource": {
                "resourceType": "Condition",
                "clinicalStatus": "active",
                "code": {
                    "coding": [
                        {
                            "system": "http://snomed.info/sct",
                            "code": "426875007",
                            "display": "Latent autoimmune diabetes mellitus in adult (disorder)"
                        }
                    ]
                },
                "subject": {
                    "reference": "Patient/sample-id-454b-b5c7-f1ed1fb4ght"
                }
            }
        }
    ]
}

Error response object:

As an example, If we try to create a record that already existis in Roche Diabetes Care (RDC), a 422 HTTP error status code is returned together the following response:

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "duplicate",
            "details": {
                "text": "Bj6.1Lq-hvb-28"
            },
            "diagnostics": "The resource already exists. Please retrieve the fhir-id from the field details.text and use it to request an update to the existing resource",
            "expression": [
                "Patient.identifier[0].value"
            ]
        }
    ]
}

Note

issue.details.text returns the patient FHIR ID that is already created.



FHIR API: Patient Creation v1


Note

This API version will be deprecated. We encourage you to migrate to the latest version of the API. You can find the documentation for the new API version at Patient Creation v2.

Pre-requisites


Resource:

POST /partners/fhir/stu3/api/Bundle


Authentication:

Endpoint is secured with mutual TLS. More information can be found here: API Authentication


API Request

Request Headers

Name Description Type Required Example
org_id Organization OID String Yes 2.16.724.4.2
x-origin-request-id Request Unique ID generated by EMR middleware (UUID) String Yes 5109d51b-421e-4746-b673-16e3fe2b3442
client_id Public identifier for organizations generated by Roche DC String Yes 1234567890
client_secret Client related secret known only to the EMR and Roche DC String Yes 1234567890
Content-Type json or fhir+json String Yes application/json or application/fhir+json

Profile overview

The list of profiles used in Patient Creation.

Note

While creating a patient, the patient identifier value and the email must be unique.


Request Example


Body Request Example:

  • Refer Patient Request example with Type-1 diabetes condition:
curl --location --request POST 'https://api-services-eu.rochedcplatform.com/partners/fhir/stu3/api/v2/Bundle' \
--header 'client_id: 1234567890' \
--header 'client_secret: 1234567890' \
--header 'Content-Type: application/fhir+json' \
--header 'org_Id: 2.16.724.4.2' \
--data-raw '{
    "resourceType": "Bundle",
    "type": "message",
    "entry": [
        {
             "resource": {
                "resourceType": "MessageHeader",
                "id": "88a37162-3d7c-41c3-89ab-6e25fd68ba00",
                "event": {
                    "code": "new-bundle",
                    "system": "http://roche.com/fhir/rdc/message-type",
                    "display": "New bundle generated"
                },
                "source": {
                    "endpoint": "<Organization OID>",
                    "software": "EMR middleware",
                    "version": "1.0.0"
                },
                "timestamp": "2020-03-27T12:21:39.471Z",
                "meta": {
                    "profile":  [
                        "http://roche.com/fhir/rdc/StructureDefinition/message-header"
                    ]
                }
            }
        },
        {
            "resource": {
                "resourceType": "Patient",
                "meta": {
                	"profile":  [
                        "http://roche.com/fhir/rdc/StructureDefinition/patient-v2"
                    ]
                },
                "identifier": [
                    {
                        "system": "urn:oid:2.16.724.4.41",
                        "value": "12345678Z"
                    }
                ],
                "name": [
                    {
                        "family": "Doe",
                        "given": [
                            "John"
                        ]
                    }
                ],
                "telecom": [
                    {
                        "system": "phone",
                        "value": "123123123"
                    },
                    {
                        "system": "email",
                        "value": "johndoe123@email.com"
                    }
                ],
                "gender": "male",
                "birthDate": "1991-01-01"
            }
        },
        {
            "resource": {
                "resourceType": "Condition",
                "clinicalStatus": "active",
                "code": {
                    "coding": [
                        {
                            "system": "http://snomed.info/sct",
                            "code": "426875007",
                            "display": "Latent autoimmune diabetes mellitus in adult (disorder)"
                        }
                    ]
                },
                "subject": {
                    "reference": "Patient/sample-id-454b-b5c7-f1ed1fb4ght"
                }
            }
        }
    ]
}'

API Response

API code response

HTTP Response Code Description Response Body FHIR error code FHIR error code description
200 Patient Bundle created Bundle NA NA
400 Request failed because of incorrect parameters, returns no data OperationOutcome required Request failed because of incorrect parameters, returns no data
400 Request failed because of incorrect parameters, returns no data OperationOutcome structure A structural issue in the content such as wrong namespace, or unable to parse the content completely, or invalid json syntax.
400 Request failed because of incorrect parameters, returns no data OperationOutcome invalid Content invalid against the specification or a profile.
401 Request failed with unauthorized access, returns no data Empty NA NA
405 Method Not Allowed Empty NA NA
409 Conflict / User already exists OperationOutcome duplicate Patient is already in use for this department.
415 Unsupported Media Type OperationOutcome not-supported Content-Type is not one of (application/json, application/fhir+json)
500 Request failed with internal exception OperationOutcome exception Internal server error.
501 Not implemented Empty NA NA

API Payload response

Successful response object:

{
    "resourceType": "Bundle",
    "type": "message",
    "entry": [
        {
             "resource": {
                "resourceType": "MessageHeader",
                "id": "88a37162-3d7c-41c3-89ab-6e25fd68ba00",
                "event": {
                    "code": "new-bundle",
                    "system": "http://roche.com/fhir/rdc/message-type",
                    "display": "New bundle generated"
                },
                "source": {
                    "endpoint": "<Organization OID>",
                    "software": "EMR middleware",
                    "version": "1.0.0"
                },
                "timestamp": "2020-03-27T12:21:39.471Z",
                "meta": {
                    "profile":  [
                        "http://roche.com/fhir/rdc/StructureDefinition/message-header"
                    ]
                }
            }
        },
        {
            "resource": {
                "resourceType": "Patient",
                "meta": {
                	"profile":  [
                        "http://roche.com/fhir/rdc/StructureDefinition/patient-v2"
                    ]
                },
                "id": "12345678Z",
                "identifier": [
                    {
                        "system": "urn:oid:2.16.724.4.41",
                        "value": "12345678Z"
                    }
                ],
                "name": [
                    {
                        "family": "Doe",
                        "given": [
                            "John"
                        ]
                    }
                ],
                "telecom": [
                    {
                        "system": "phone",
                        "value": "123123123"
                    },
                    {
                        "system": "email",
                        "value": "johndoe123@email.com"
                    }
                ],
                "gender": "male",
                "birthDate": "1991-01-01"
            }
        },
        {
            "resource": {
                "resourceType": "Condition",
                "clinicalStatus": "active",
                "code": {
                    "coding": [
                        {
                            "system": "http://snomed.info/sct",
                            "code": "426875007",
                            "display": "Latent autoimmune diabetes mellitus in adult (disorder)"
                        }
                    ]
                },
                "subject": {
                    "reference": "Patient/sample-id-454b-b5c7-f1ed1fb4ght"
                }
            }
        }
    ]
}

Error response object:

As an example, If we try to create a record that already existis in Roche Diabetes Care (RDC), a 409 HTTP error status code is returned together the following response:

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "duplicate",
            "diagnostics": "Patient is already in use for this department."
        }
    ]
}

Response Time (ms):


  • Average: 1500

  • Worst case scenario: 10000