NAV Navbar
http

Introduction

Welcome to the docare.ch API! You can use our API to access docare.ch FHIR API endpoints, which can get information on patients and encounters in our database.

API Endpoint URL

Authentication

To get an access token, send the following request:

POST /oauth/v2/token HTTP/1.1
Content-Type: multipart/form-data
Host: {endpoint_url}

client_id: "{clientid}"
client_secret: "{clientsecret}"
grant_type: "client_credentials"

Make sure to replace {clientid} and {clientsecret} with your OAuth client id and secret and to use the correct API endpoint url (staging or production).

The above request returns the following response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "token_type": "Bearer",
  "access_token": "add72ae475214adc83ea227c21fee0e5",
  "expires_in": 3600
}

docare.ch uses a token to allow access to the API. An OAuth client credentials request is used to obtain a token. Contact us to get your OAuth client id and client secret. The token can be used for the number of sconds returned in the expires_in field.

docare.ch expects the access token to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer 94b760b2dff748f992dc8e52e9a5bd51

Patient

The docare.ch FHIR Patient resource covers demographics and other administrative information about a patient.

Create a Patient

POST /fhir/v4/Patient HTTP/1.1
Authorization: Bearer {access_token}
Content-Type: application/json
Host: {endpoint_url}

{
  "resourceType": "Patient",
  "name": [{
    "use": "usual",
    "family": "Mulligan",
    "given": ["Buck"]
  }],
  "telecom": [{
    "system": "phone",
    "use": "mobile",
    "value": "+41790000000"
  }],
  "birthDate": "2017-03-05",
  "gender": "male"
}

The above request returns the following response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: {endpoint_url}/fhir/v4/Patient/5b9613fc-43ef-4f90-bf10-9cbe7451fe02

{
  "resourceType": "Patient",
  "id": "5b9613fc-43ef-4f90-bf10-9cbe7451fe02",
  "identifier": [{
      "system": "{endpoint_url}/concepts/patient_number",
      "value": "103"
  }],
  "name": [{
    "use": "usual",
    "text": "Buck Mulligan",
    "family": "Mulligan",
    "given": ["Buck"]
  }],
  "telecom": [{
    "system": "phone",
    "use": "mobile",
    "value": "+41790000000"
  }],
  "birthDate": "2017-03-05",
  "gender": "male"
}

This endpoint creates a new patient.

HTTP Request

POST /fhir/v4/Patient

JSON Attributes

Name Type Description
resourceType string "Patient" constant
name HumanName Name associated with the patient
telecom ContactPoint Contact detail for the patient
birthDate date The date of birth for the patient
gender code Gender of the patient: male, female

Get All Patients

To get all patients with the string Mulligan in the name, send the following request:

GET /fhir/v4/Patient?name=Mulligan HTTP/1.1
Authorization: Bearer {access_token}
Host: {endpoint_url}

The above request returns the following response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "fullUrl": "{endpoint_url}/fhir/v4/Patient/2f5da8c2-cbf1-42d1-9d7a-165f3ed80541",
      "resource": {
        "resourceType": "Patient",
        "id": "2f5da8c2-cbf1-42d1-9d7a-165f3ed80541",
        "name": [{
          "use": "usual",
          "text": "Buck Mulligan",
          "family": "Mulligan",
          "given": ["Buck"]
        }],
        "birthDate": "2017-03-05",
        "gender": "male"
      }
    }
  ]
}

This endpoint retrieves all patients.

HTTP Request

GET /fhir/v4/Patient

Query Parameters

Parameter Type Description
name string A portion of the family or given name of the patient.

Get a Specific Patient

To get the patient with id 2f5da8c2-cbf1-42d1-9d7a-165f3ed80541, send the following request:

GET /fhir/v4/Patient/2f5da8c2-cbf1-42d1-9d7a-165f3ed80541 HTTP/1.1
Authorization: Bearer {access_token}
Host: {endpoint_url}

The above request returns the following response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "resourceType": "Patient",
  "id": "2f5da8c2-cbf1-42d1-9d7a-165f3ed80541",
  "identifier": [{
      "system": "{endpoint_url}/concepts/patient_number",
      "value": "103"
  }],
  "name": [{
    "use": "usual",
    "text": "Buck Mulligan",
    "family": "Mulligan",
    "given": ["Buck"]
  }],
  "telecom": [{
    "system": "phone",
    "use": "mobile",
    "value": "+41790000000"
  }],
  "birthDate": "2017-03-05",
  "gender": "male"
}

This endpoint retrieves a specific patient.

HTTP Request

GET /fhir/v4/Patient/<ID>

URL Parameters

Parameter Description
ID The ID of the patient to retrieve

Update a Patient

POST /fhir/v4/Patient/5b9613fc-43ef-4f90-bf10-9cbe7451fe02 HTTP/1.1
Authorization: Bearer {access_token}
Content-Type: application/json
Host: {endpoint_url}

{
  "resourceType": "Patient",
  "name": [{
    "use": "usual",
    "text": "Buck Mulligan",
    "family": "Mulligan",
    "given": ["Buck"]
  }],
  "telecom": [{
    "system": "phone",
    "use": "mobile",
    "value": "+41790000000"
  }],
  "birthDate": "2017-03-05",
  "gender": "male"
}

The above request returns the following response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "resourceType": "Patient",
  "id": "5b9613fc-43ef-4f90-bf10-9cbe7451fe02",
  "identifier": [{
      "system": "{endpoint_url}/concepts/patient_number",
      "value": "103"
  }],
  "name": [{
    "use": "usual",
    "text": "Buck Mulligan",
    "family": "Mulligan",
    "given": ["Buck"]
  }],
  "telecom": [{
    "system": "phone",
    "use": "mobile",
    "value": "+41790000000"
  }],
  "birthDate": "2017-03-05",
  "gender": "male"
}

This endpoint updates all patient data.

HTTP Request

POST /fhir/v4/Patient/<ID>

URL Parameters

Parameter Description
ID The ID of the patient to update

JSON Attributes

Name Type Description
resourceType string "Patient" constant
name HumanName Name associated with the patient
telecom ContactPoint Contact detail for the patient
birthDate date The date of birth for the patient
gender code Gender of the patient: male, female

Delete a Patient

To delete the patient with id 5b9613fc-43ef-4f90-bf10-9cbe7451fe02, send the following request:

DELETE /fhir/v4/Patient/5b9613fc-43ef-4f90-bf10-9cbe7451fe02 HTTP/1.1
Authorization: Bearer {access_token}
Host: {endpoint_url}

The above request returns the following response:

HTTP/1.1 204 No Content

This endpoint deletes a patient.

HTTP Request

DELETE /fhir/v4/Patient/<ID>

URL Parameters

Parameter Description
ID The ID of the patient to delete

Encounter

The docare.ch FHIR Encounter resource covers a consultation recorded in docare.ch.

Create an Encounter

To create a new encounter for the patient with id d0a31764-6030-4284-984e-3bd967106ea4, send the following request:

POST /fhir/v4/Encounter HTTP/1.1
Authorization: Bearer {access_token}
Content-Type: application/json
Host: {endpoint_url}

{
  "resourceType": "Encounter",
  "class": {
    "code": "AMB"
  },
  "subject": {
    "reference": "{endpoint_url}/fhir/v4/Patient/d0a31764-6030-4284-984e-3bd967106ea4"
  },
  "period": {
    "start": "2018-11-12",
    "end": "2018-11-12"
  }
}

The above request returns the following response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: {endpoint_url}/fhir/v4/Encounter/931a68c2-62ca-470e-b1f5-a590577d2936

{
  "resourceType": "Encounter",
  "id": "931a68c2-62ca-470e-b1f5-a590577d2936",
  "status": "in-progress",
  "class": {
    "code": "AMB"
  },
  "subject": {
    "reference": "{endpoint_url}/fhir/v4/Patient/d0a31764-6030-4284-984e-3bd967106ea4"
  },
  "period": {
    "start": "2018-11-12",
    "end": "2018-11-12"
  },
  "serviceProvider": {
    "reference": "{endpoint_url}/fhir/v4/Organization/04d2256f-8424-432d-80fc-af58e10dcfe1"
  }
}

This endpoint creates a new encounter.

HTTP Request

POST /fhir/v4/Encounter

JSON Attributes

Name Type Description
resourceType string "Encounter" constant
class Coding Classification of patient encounter
subject Reference The patient present at the encounter
period Period The start and end time of the encounter

Get All Encounters

To get all encounters for the patient with id 2f5da8c2-cbf1-42d1-9d7a-165f3ed80541, send the following request:

GET /fhir/v4/Encounter?subject=Patient/2f5da8c2-cbf1-42d1-9d7a-165f3ed80541 HTTP/1.1
Authorization: Bearer {access_token}
Host: {endpoint_url}

The above request returns the following response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "fullUrl": "{endpoint_url}/fhir/v4/Encounter/19d4c5a3-fa8d-4aa0-aa11-f9a1f31656d8",
      "resource": {
        "resourceType": "Encounter",
        "id": "19d4c5a3-fa8d-4aa0-aa11-f9a1f31656d8",
        "class": {
          "code": "AMB"
        },
        "subject": {
          "reference": "{endpoint_url}/fhir/v4/Patient/2f5da8c2-cbf1-42d1-9d7a-165f3ed80541"
        },
        "period": {
          "start": "2018-11-17",
          "end": "2018-11-17"
        }
      }
    }
  ]
}

This endpoint retrieves all encounters.

HTTP Request

GET /fhir/v4/Encounter

Query Parameters

Parameter Type Description
subject reference The patient present at the encounter.

Get a Specific Encounter

To get the encounter with id 19d4c5a3-fa8d-4aa0-aa11-f9a1f31656d8, send the following request:

GET /fhir/v4/Encounter/19d4c5a3-fa8d-4aa0-aa11-f9a1f31656d8 HTTP/1.1
Authorization: Bearer {access_token}
Host: {endpoint_url}

The above request returns the following response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "resourceType": "Encounter",
  "id": "19d4c5a3-fa8d-4aa0-aa11-f9a1f31656d8",
  "class": {
    "code": "AMB"
  },
  "subject": {
    "reference": "{endpoint_url}/fhir/v4/Patient/2f5da8c2-cbf1-42d1-9d7a-165f3ed80541"
  },
  "period": {
    "start": "2018-11-17",
    "end": "2018-11-17"
  },
  "serviceProvider": {
    "reference": "{endpoint_url}/fhir/v4/Organization/04d2256f-8424-432d-80fc-af58e10dcfe1"
  }
}

This endpoint retrieves a specific encounter.

HTTP Request

GET /fhir/v4/Encounter/<ID>

URL Parameters

Parameter Description
ID The ID of the encounter to retrieve

Update an Encounter

To update the encounter with id 931a68c2-62ca-470e-b1f5-a590577d2936, send the following request:

POST /fhir/v4/Encounter/931a68c2-62ca-470e-b1f5-a590577d2936 HTTP/1.1
Authorization: Bearer {access_token}
Content-Type: application/json
Host: {endpoint_url}

{
  "resourceType": "Encounter",
  "class": {
    "code": "AMB"
  },
  "period": {
    "start": "2018-11-12",
    "end": "2018-11-12"
  }
}

The above request returns the following response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: {endpoint_url}/fhir/v4/Encounter/931a68c2-62ca-470e-b1f5-a590577d2936

{
  "resourceType": "Encounter",
  "id": "931a68c2-62ca-470e-b1f5-a590577d2936",
  "subject": {
    "reference": "{endpoint_url}/fhir/v4/Patient/d0a31764-6030-4284-984e-3bd967106ea4"
  },
  "period": {
    "start": "2018-11-12",
    "end": "2018-11-12"
  },
}

This endpoint updates all encounter data.

HTTP Request

POST /fhir/v4/Encounter/<ID>

URL Parameters

Parameter Description
ID The ID of the encounter to update

JSON Attributes

Name Type Description
resourceType string "Encounter" constant
class Coding Classification of patient encounter
period Period The start and end time of the encounter

Delete an Encounter

To delete the encounter with id 931a68c2-62ca-470e-b1f5-a590577d2936, send the following request:

DELETE /fhir/v4/Encounter/931a68c2-62ca-470e-b1f5-a590577d2936 HTTP/1.1
Authorization: Bearer {access_token}
Host: {endpoint_url}

The above request returns the following response:

HTTP/1.1 204 No Content

This endpoint deletes an encounter.

HTTP Request

DELETE /fhir/v4/Encounter/<ID>

URL Parameters

Parameter Description
ID The ID of the encounter to delete

QuestionnaireResponse

The docare.ch FHIR QuestionnaireResponse resource contains all the answers from the patient's questionnaire.

Get All Questionnaire Responses

To get all questionnaire responses for the patient with id 2f5da8c2-cbf1-42d1-9d7a-165f3ed80541, send the following request:

GET /fhir/v4/QuestionnaireResponse?subject=Patient/2f5da8c2-cbf1-42d1-9d7a-165f3ed80541 HTTP/1.1
Authorization: Bearer {access_token}
Host: {endpoint_url}

The above request returns the following response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "fullUrl": "{endpoint_url}/fhir/v4/QuestionnaireResponse/d605cd56-c554-4cbd-9c6b-8d7b16903443",
      "resource": {
        "resourceType": "Encounter",
        "id": "d605cd56-c554-4cbd-9c6b-8d7b16903443",
        "status": "completed",
        "questionnaire": "{endpoint_url}/fhir/v4/Questionnaire/history_dermatology",
        "authored": "2018-04-25T14:15:33.811244+00:00",
        "subject": {
          "reference": "{endpoint_url}/fhir/v4/Patient/2f5da8c2-cbf1-42d1-9d7a-165f3ed80541"
        },
        "encounter": {
          "reference": "{endpoint_url}/fhir/v4/Encounter/931a68c2-62ca-470e-b1f5-a590577d2936"
        }
      }
    }
  ]
}

This endpoint retrieves all questionnaire responses for a given patient.

HTTP Request

GET /fhir/v4/QuestionnaireResponse

Query Parameters

Parameter Type Description
subject reference The patient of the questions.

Get a Specific Questionnaire Response

To get the questionnaire response with id d605cd56-c554-4cbd-9c6b-8d7b16903443, send the following request:

GET /fhir/v4/QuestionnaireResponse/d605cd56-c554-4cbd-9c6b-8d7b16903443 HTTP/1.1
Authorization: Bearer {access_token}
Host: {endpoint_url}

The above request returns the following response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "resourceType": "QuestionnaireResponse",
  "id": "d605cd56-c554-4cbd-9c6b-8d7b16903443",
  "meta": {
    "lastUpdated": "2019-07-12T09:16:03.157753+00:00"
  },
  "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p>Konsultationsgrund: Allergie. Beschwerden seit 2 Wochen. Bisherige Abkl&#228;rungen: Allergietest.</p><p>Keine Dauerbeschwerden. Beschwerden treten nicht bei bestimmten T&#228;tigkeiten auf.</p></div>"
  },
  "status": "completed",
  "authored": "2019-07-12T09:16:03.157753+00:00",
  "subject": {
    "reference": "{endpoint_url}/fhir/v4/Patient/2f5da8c2-cbf1-42d1-9d7a-165f3ed80541"
  },
  "encounter": {
    "reference": "{endpoint_url}/fhir/v4/Encounter/931a68c2-62ca-470e-b1f5-a590577d2936"
  },
  "questionnaire": "{endpoint_url}/fhir/v4/Questionnaire/history_dermatology",
  "item": [
    {
      "linkId": "ailment",
      "answer": [
        {
          "valueCoding": {
            "code": "ailment_allergy"
          }
        }
      ]
    },
    {
      "linkId": "ailment_duration",
      "answer": [
        {
          "valueQuantity": {
            "value": 2,
            "unit": "wk"
          }
        }
      ]
    },
    {
      "linkId": "permanent_ailment",
      "answer": [
        {
          "valueBoolean": false
        }
      ]
    },
    {
      "linkId": "ailment_activity",
      "answer": [
        {
          "valueBoolean": false
        }
      ]
    },
    {
      "linkId": "past_investigations",
      "answer": [
        {
          "valueCoding": {
            "code": "past_investigations_allergy_test"
          }
        }
      ]
    }
  ]
}

This endpoint retrieves a specific questionnaire response.

HTTP Request

GET /fhir/v4/QuestionnaireResponse/<ID>

URL Parameters

Parameter Description
ID The ID of the questionnaire response to retrieve

Errors

GET /fhir/v4/Patient/invalid_id HTTP/1.1
Authorization: Bearer {access_token}
Host: {endpoint_url}

The above request returns the following 404 response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "not_found"
}

The docare.ch API uses the following standard HTTP error codes. The JSON response contains an addititonal error key.

Code Error Meaning
400 validation_failed Invalid body/arguments or schema validation failed
400 resource_not_found FHIR referenced resource not found
401 unauthorized Authorization header missing, Bearer token invalid or expired
401 invalid_client Invalid OAuth client_id or client_secret
401 unsupported_grant_type Unsupported OAuth grant_type
401 invalid_grant Invalid/expired OAuth authorization code
403 forbidden Required permission for resource missing
404 not_found Resource not found (invalid URL)
405 method_not_allowed HTTP method not allowed for URL
5xx Server Error

Responses with a 5xx error code contain HTML instead of JSON content.