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.
- message-header (mandatory)
- patient-v2 (mandatory)
- condition (optional)
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.