POST /v1/chatbot/initialize/illnessCheck

Clients have to decide whether a symptom check or an illness check shall be started.

Use this request to start a Symptom Check.

The checkId received as response for this request will be used to identify the ongoing check.

Request

Request header additional fields

Parameter name	Parameter type	Parameter description
`language`	ClientLanguage	Language of the check

Request body parameters

Parameter name	Parameter type	Parameter description
patient	Patient?	FHIR Patient resource used for check initialization
observations	Observation[]?	FHIR Observation resources used for check initialization
`tags`	string[]?	Optional partner-provided tags for differentiating checks in reporting. The array may contain at most 64 tags. Each tag may contain only English letters, numbers, and `_`, and must be 1 to 64 characters long. Do not include secrets, secret identifiers, personal data, or stable patient identifiers in tags.

About Patient & Observation

resourceType is not listed as a part of the FHIR documentation of Patient & Observation resources, however, resourceType is always defined with a given default value (name of the resource) in the JSON schema definitions.
The gender field of a Patient can have 4 values according to the FHIR documentation: male, female, other, and unknown. Currently, the API only supports male and female. In case of other and unknown, the API responds with UNSUPPORTED_GENDER error.
Although the status field is required in an Observation resource according to the FHIR documentation, the API does not use it.
When the client provides a list of observations as input for further Symptom Check, the API matches these observations to XUND symptoms via UMLS codes. If even just one of the provided observation’s UMLS codes cannot be mapped to a symptom, the API ignores the drops request and responds with INVALID_UMLS_CODE error.

Request Example:

Initial data check with Patient data and the list of input observations. Symptoms are identified with UMLS codes from the Content Library .

JSON

{
    "patient": {
        "resourceType": "Patient",
        "gender": "male",
        "birthDate": "1985-10-16"
    },
    "observations": [
        {
            "resourceType": "Observation",
            "code": {
                "coding": [
                    {
                        "code": "C0043037" // This property is mandatory for check initialization in case of Symptom Check. This is the UMLS code of the symptom
                    }
                ]
            }
        },
        {
            "resourceType": "Observation",
            "code": {
                "coding": [
                    {
                        "code": "C0242429" // This property is mandatory for check initialization in case of Symptom Check. This is the UMLS code of the symptom
                    }
                ]
            }
        }
    ],
    "tags": [
        "partner_1",
        "campaign_2026"
    ]
}

Response

Response body structure

Property name	Property type	Property description
`checkId`	string	Unique identifier of the check

Example

checkID will be generated as a result of a successful check initialization

JSON

{
  "checkId": "5e93d7a1-f240-43b5-8937-33419ea9cb6a"
}