Healthpages is an address book specifically designed to find healthcare actors. It contains individual caregivers and organizations as well as campuses, caregivers and departments in organizations.

All of these actors are identified using the healthcare actor ID which is guaranteed to be unique across systems, environments and in time. These healthcare actors are modelled as contacts and exposed via different service endpoints. The model of this address book is designed to match the model provided by the Belgian healthcare and eHealth services. Relevant extensions have been added on top of that model.

Remember, the older APIs are scheduled for removal on 31/12/2020.

Contact model

Diagram

Every healthcare actor is modelled as an actor, which always has an id, label, summary and a type. Depending on the type, the caregiver, department, campus and/or organization will be set. These entities form the functional definition of the contact.

The four contact properties (caregiver, campus, department or organization) are designated as either the primary entity or the secondary entity of the contact. This designation depends on the type of the contact.

The primary entity is the final destination we are trying to pinpoint and is mandatory. It is the subject we are addressing; the receiver of our communication. The secondary entity is there for transport and scoping purposes, and is optional. If there is no secondary entity, the primary serves as transport provider. These concepts are important when we discuss the filtering capabilities of the API.

Every contact type belongs to a group, either simple or complex. Simple contacts are contacts which can consist of a single entity. Complex contacts are contacts which aggregate two entities.

Table 1. Contact types and roles
Contact type Contact group Primary entity Secondary entity

CAREGIVER

Simple

caregiver

-

ORGANIZATION

Simple

organization

-

CAREGIVER_IN_ORGANIZATION

Complex

caregiver

organization

DEPARTMENT_IN_ORGANIZATION

Complex

department

organization

CAMPUS_IN_ORGANIZATION

Complex

campus

organization

Contact model properties

We start with a short overview of the different properties of the contact model.

Id

The healthcare actor id (128 character string). It uniquely identifies the contact, now and in the future. See the Contact identification section for details.

Label

The label is a textual representation of the contact, crafted in such a way that no two contacts returned by our search API will have the same label. It uniquely identifies the contact within the scope of that API. The label is not unique across all contacts. Organization contacts with the same functional id (NIHII, CBE, EHP) but different application IDs will have the same label. We guarantee that no two of those contacts with just different application IDs will be returned by the search service.

Summary

A summary is a textual representation of the contact, crafted in such a way that given a set of contacts, reasonable guarantees can be given that the summary will be unique. This is useful because it results in considerable shorter descriptions of the same contact. A typical use case would be to show the label in a search dropdown and the summary once the contact has been selected.

Type

The type of the contact being CAREGIVER, ORGANIZATION, CAREGIVER_IN_ORGANIZATION, DEPARTMENT_IN_ORGANIZATION or CAMPUS_IN_ORGANIZATION.

Integrators of our API’s should code defensively, and should be able to handle new contact types without failing. There are several ways to achieve this depending on the post processing performed on the contacts. For details, consult the HealthConnect development team.
Address

Every contact has zero or one primary address and zero, one or more alternative addresses. The primary address is returned with the contact on request. Alternative addresses are available through another endpoint. All addresses are addresses in Belgium.

Details

Every contact contains details specifying extra information of that contact.

Reachable destinations

Every contact specifies via which mechanisms it can be reached. The API currently supports POSTAL_SERVICE and EHEALTH_BOX. It is possible for a contact to have an eHealthBox yet to no want to receive messages in it. Every integrator can decide independently if he wishes to respect these flags. These flags go beyond pure technical assessments and include the contact’s preferences as well.

Integrators of our API’s should code defensively, and should be able to handle new types of destinations without failing.
Format of labels and summaries

The following tables explain how the different labels and summaries are constructed for a contact. There is one table per contact type, where for completness sake some properties are marked with a / because they do not exist for that contact type.

Table 2. Caregiver labels
Contact property Pseudo code value

label

<caregiver-quality> <firstname> <lastname>

summary

<firstname> <lastname>

caregiver.label

<caregiver-quality> <firstname> <lastname>

organization.label

/

department.label

/

campus.label

/

Table 3. Organization labels
Contact property Pseudo code value

label

<organization-name>

summary

<organization-name>

caregiver.label

/

organization.label

<organization-name>

department.label

/

campus.label

/

Table 4. Caregiver in organization labels
Contact property Pseudo code value

label

<caregiver-quality> <firstname> <lastname> (<nihii>) - <organization-name> (<identifier>)

summary

<firstname> <lastname> - <organization-name>

caregiver.label

<caregiver-quality> <firstname> <lastname>

organization.label

<organization-name>

department.label

/

campus.label

/

Table 5. Department labels
Contact property Pseudo code value

label

<department-name> - <organization-name> (<identifier>)

summary

<department-name> - <organization-name>

caregiver.label

/

organization.label

/

department.label

<department-name>

campus.label

/

Table 6. Campus labels
Contact property Pseudo code value

label

<campus-name> - <organization-name> (<identifier>)

summary

<campus-name> - <organization-name>

caregiver.label

/

organization.label

/

department.label

/

campus.label

<campus-name>

Search requests

The REST API is described using the OpenAPI specification (see API in the top menu). All technical details can be consulted there. This document will explain the filtering capabilities and how they work, followed by some example calls on how to use them for typical use cases.

Diagram

A search request must contain at least a query, and can be supplemented with a primary and/or a secondary filter. These filters (primary or secondary) match with the entity types as discussed earlier. Several combinations of these filters are possible, and some of them will always results in an empty result set. The API performs some basic sanity checks, but it is the caller’s responsibility to verify that the combination of filters is functionally sound.

Search request properties

There are a number of core properties of the different model classes that require a bit of explaining.

MaxResults

The maximum number of results to be returned by the search service.

Types

A set of acceptable contact types. This property can for instance be used to limit the search to just caregivers. There are other ways to achieve the same result, but they require more complex search requests which will always be slower and will result in less accurate search results. The more simple the search request, the more accurate and faster the search results are returned.

Query

A free text query string, typically entered by the user. If left empty, the search API returns an empty set of results, unless the primary or secondary filter is present with the ids property populated.

ReachableBy

The destinations over which the contact must be reachable. Possible values EHEALTH_BOX and POSTAL_SERVICE. A contact is reachable when constraints, for the given destination, are met and the contact did not explicitly deny reachability over this destination.

CompatibleWith

The destinations over which the contact is compatible. This differs from ReachableBy in the way that there are no checks performed on it’s validtity or wether the contact wants to be contacted over this destination. This merly indicates 'technically possible'.

We should include if the contact wants to be reachable as a constraint for the CompatibleWith. If the contact does not want it, it will never be ReachableBy? Is this usable in its current form? The goal of this CompatibleWith is to find ehealth box contacts that could be sent to ehealth if they had an etk. That was the original intent.
IncludeOutOfOffice

By default true, include contacts that are out of office into the search results. Contacts which are out of office are ranked lower in the search results. If false, do not include contacts that are out of office into the search results.

IncludePrimaryAddress

If true, the primary address of the contact will be returned. If false or omitted, the address is not returned.

ContactIds

A set of contact ids to limit the search to. This property is useful when there is no logic filtering based on primary or secondary entity. This is usually the case if we want to search in a predefined set of contacts, where there is no logical relation between the contacts.

ExcludedContactIds

A set of contact ids to exclude from the search results. This property can be used to build a multi-select contact search. When the user selects a first contact, and starts searching for a second contact, the id of the first contact can be passed along so that we do not return the already selected contact in the second search.

How does it work?

Conceptually, the search service works as followed. Given a search request, every contact in the database is matched against the request. The acceptable types, the reachability and the excluded ids are checked first to determine if a contact is taken into consideration.

All properties on the primary and secondary filter are arrays. Depending on the type of contact, either the caregiver, department or organization is the primary entity. If the primary entity has a corresponding property matching the property of the primary filter, the filter is applied. For instance, if the primary filter contains a set of custom application ids, and the contact is a CAREGIVER, there can be no match and the property on the filter is ignored for this. If that same filter is matched against an ORGANIZATION contact, the application ids property is taken into consideration and matched against the contact.

Contact identification

This section serves as a short introduction to contact identification in HealthPages. It does not cover the entirety of the subject. For full details, contact the HealthConnect team.

Each contact in our system is identified by a 128 character string id. This id is present on all contacts, and also on the caregiver and organization entities; basically all independently addressable entities. It uniquely identifies the contact, now and in the future. We guarantee that this id will not change over time.

A department and a campus do not have an id of this format, because they only exist within the scope of their parent organization. For contacts with just a primary entity, the id of the contact will be the same as that of the primary entity. Contacts with both a primary and a secondary entity will have a different id than that of its entities.

A contact can be identified in two ways in the Belgian healthcare system. The first is a functional identification known and understood by most users. An example of this is the NIHII number for a caregiver. This number is guaranteed to be unique within the scope of caregivers. Take into account organizations and the number is no longer unique.

A second example is a CBE or NIHII number for an organization. These numbers are unique as well.

On a technical level, these identifications requires more parameters, especially for organizations. The Belgian eHealth system identifies an actor using a quality and an identifier. An identifier, CBE for instance, can be linked to different qualities, resulting in different contacts. The quality is a required part of the identification.

In the context of eHealthBox, things get even more complicating for organizations. eHealthBox adds the notion of an application ID. This is a means for eHealth to issue several certificates for the same organization. The result is that the one organization identified by a CBE and a quality is reachable via different sub channels. Every channel is cryptographically isolated from each other. Although handy to isolate parts of the organization from eachother, it does complicate things for the sender.

The most important thing to remember from all of this is that for every functional identifier, there are several technical identifiers that match. All of the above complexity is managed by HealthPages and the healthcare actor id. When a user selects a contact (via for instance the search API), HealthPages will return the exact technical identifier. In our example, the healthcare actor id will identify the CBE organization, identifier and quality, as well as which application ID to use. This means that the healthcare actor id returned, is specific enough to serve as a technical identifier in all different interactions with eHealth systems. A technical identifier, being more specific than a functional one, contains all functional parts as well.

Contact datasets

Healthpages internally acts on two different datasets containing Contacts. These datasets can shrink or grow only when rebuilding the full dataset from scratch. Currently no manipulations are performed on the 'live' datasets.

Table 7. Dataset characteristics
Dataset Implementation details Shrink Grow

Full

Map with HealthcareActorId as key and Contact as value

  • RIZIV removed entries from the authentic datasource

  • Suppliers have been removed by support

  • RIZIV added entries to the authentic datasource

  • Suppliers have been created by support

Searchable

Subset of the full dataset currently indexed in Lucene

In addition to the list above:

  • Modifiers that make a contact searchable have been removed by support

In addition to the list above:

  • Modifiers that make a contact searchable have been created by support

The searchable dataset is only queried in the contactService.search(final SearchCriteria criteria) method. This method uses the Searchable dataset to obtain a list of HealthcareActorIds. Afterwards, the full dataset is queried to get Contacts based on the obtained HealthcareActorIds.

There are 3 endpoints relying on this implementation.

  • GET /api/contacts → OK, actual search endpoint with criteria

  • POST /api/contacts → OK, actual search endpoint with criteria

  • POST /api/addressees → Should we 'search' the index with a list of actorIds?

Postal addresses

We store addresses as a set of distinct properties:

  • Country

  • Postal code

  • City name

  • Street name

  • House number

  • Box number

Whenever we receive a (partial) address through our API, we perform a sanitization. In the following table we describe which fields are sanitized in what way.

Table 8. Address fields sanitization
Field Sanitization Before After

Postal Code

  1. All characters except for [alphanumeric] are stripped (including spaces)

  2. Multiple spaces are reduced to a single space (obsolete!)

  3. Result is set to uppercase, trimmed and if empty, set to null

  1. 8300.aa

  2. 8300. AA

  3. 8300

  4. %*:

  1. 8300AA

  2. 8300AA

  3. 8300

  4. null

City

  1. All characters except for letters, numbers, spaces, -' are stripped

  2. Multiple spaces are reduced to a single space

  3. Word groups separated by space or - are capitalized (first letter uppercase, following letters lowercase)

  4. Result is trimmed and if empty, set to null

  1. Knokke-Heist

  2. knokke-heist

  3. KNOKke-HEIst

  4. knokke - heist

  5. 's-gravenbrakel

  1. Knokke-Heist

  2. Knokke-Heist

  3. Knokke-Heist

  4. Knokke - Heist

  5. 's-Gravenbrakel

Street

  1. All characters except for letters, numbers, spaces and -'.() are stripped

  2. Multiple spaces are reduced to a single space

  3. Word groups separated by space, - or . are capitalized (first letter uppercase, following letters lowercase)

  4. Result is trimmed and if empty, set to null

  1. Nieuwstraat

  2. nieuwstraat

  3. Sint-gommarusstr.

  1. Nieuwstraat

  2. Nieuwstraat

  3. Sint-Gommarusstr.

House number

  1. All characters except for letters, numbers and -/ are stripped

  2. Multiple spaces are reduced to a single space (obsolete!)

  3. Result is set to lowercase, is trimmed and if empty, set to null

  1. 11a

  2. 12.B

  3. n° 13

  4. 14 / D

  1. 11a

  2. 12b

  3. n13

  4. 14/d

Box number

  1. All characters except for letters, numbers are stripped

  2. Multiple spaces are reduced to a single space (obsolete!)

  3. Result is set to lowercase, is trimmed and if empty, set to null

  1. 1.1

  2. 2B

  3. 3-4

  4. 4/D

  1. 11

  2. 2b

  3. 34

  4. 4d

Display postal address

Whenever we use this data to present a postal address on a webpage or in a document, we should take care of the formatting. The formatting as described by BPost should be carefully applied.

Example

Example input in e.g. a ReplaceAddressModifier:

  • Postal code: 8300

  • City: Knokke-Heist

  • Street: Nieuwstraat

  • House number: 12

  • Box number: 1.2

This should result in one of the following display formats
Note: house number and box number should be separated by the 'bus' (NL) or 'bte' (FR) separator

  • Nieuwstraat 12 bus 12, 8300 Knokke-Heist

  • Nieuwstraat 12 bte 12, 8300 Knokke-Heist

  • Nieuwstraat 12 bus 12
    8300 Knokke-Heist

Available organizational roles

Code

Ehealth quality

Label (english)

ADDICTION_REHABILITATION_CENTER

-

Rehabilitation center for addiction

ALL_ROUND_REHABILITATION_CENTER

-

Medical-psychosocial Rehabilitation, respiratory diseases, pediatric rehabilitation center, respite units

AMBULANCE_SERVICE

-

Ambulance service

AUDITIVE_REHABILITATION_CENTER

-

Auditive rehabilitation center

BELRAI_PROJECT

-

BelRAI project

BELRAI_SCREENING

-

BelRAI Screening project

CARDIAC_REVALIDATION

-

Cardiac revalidation

CEREBRAL_PALSY_REVALIDATION

-

Cerebral palsy revalidation

CHILD_MENTAL_DISORDER_REHABILITATION_CENTER

-

Child mental disorder rehabilitation center

CHRONIC_RESPIRATORY_AT_HOME

-

Chronic respiratory at home

DAY_CARE_CENTER_BRUSSELS_REGION

-

Day care center (Brussels region)

DAY_CARE_CENTER_DUTCH_REGION

-

Day care center (Dutch region)

DAY_CARE_CENTER_FRENCH_REGION

-

Day care center (French region)

DAY_CARE_CENTER_GERMAN_REGION

-

Day care center (German region)

EHEALTH_PLATFORM

INSTITUTION_EHP

Ehealth Platform

FORENSIC_PSYCHIATRIC_CENTER

LEGAL_PSY

Forensic psychiatric Centre

FUNCTIONAL_REVALIDATION

-

Functional revalidation

GROUP_DOCTORS

GROUP_DOCTORS

Group doctors

GUARD_POST

GUARD_POST

Guard post

HOSPITAL

HOSPITAL

Hospital

INSTITUTION

INSTITUTION

Institution

INSTITUTION_FOR_SPECIAL_DISEASES

-

Institution for special diseases

INSTITUTION_WITH_DIABETIC_AGREEMENT

-

Institution with diabetic agreement

INSTITUTION_WITH_HEART_DEFIBRILLATORS

-

Institution with heart defibrillators

INSTITUTION_WITH_NET_AGREEMENT

-

Institution with NET agreement

INSTITUTION_WITH_R30_R60_AGREEMENT

-

Institution with R30 R60 agreement

INTEGRATED_HOME_CARE_SERVICES

-

Integrated home care services

LABORATORY

LABO

Laboratory

LOCOMOTOR_REHABILITATION

-

General centers for locomotor rehabilitation

MEDICAL_HOUSE

MEDICAL_HOUSE

Medical house (flat-rate system)

MEDICAL_PEDIATRIC_CENTER

-

Medical Pediatric centers

MEMORY_CLINIC

-

Memory clinic (Dementia)

MENTAL_DISORDER_REHABILITATION_CENTER

-

Revalidatieprogramma voor ernstige psychische aandoeningen

MENTAL_HOSPITAL

HOSPITAL

Mental hospital

MILITARY_HOSPITAL

HOSPITAL

Military hospital

MOTOR_REHABILITATION_CENTER

-

Functional motoric rehabilitation

MULTI_DISCIPLINARY_EVALUATION_FOR_MOBILITY

-

Multidisciplinary assessment of functional rehabilitation agreements provided for in the nomenclature of mobility aids

MULTI_DISCIPLINARY_GUIDANCE_PALLIATIVE_CARE

PALLIATIVE_CARE

Multi disciplinary guidance palliative care

NURSING_GROUP

GROUP

Group nurses

OFFICE_BANDAGISTS

OF_BAND

Office bandagists

OFFICE_DENTISTS

OFFICE_DENTISTS

Dentist’s office

OFFICE_DOCTORS

OFFICE_DOCTORS

Doctor’s office

OFFICE_KINE

-

Kinesiotherapist’s office

OTD_PHARMACY

OTD_PHARMACY

OTD Pharmacy

OXYGEN_THERAPY_AT_HOME

-

Oxygen therapy at home

PARAMEDICAL_INTERVENTION_TEAM

-

Paramedical intervention team

PHARMACY

PHARMACY

Pharmacy

PRIVATE_ADDRESS

-

Private address

PSYCHIATRIC_CARE_HOME

PSYCH_HOUSE

Psychiatric hospital

PSYCHOLOGICAL_REVALIDATION

-

Psychological revalidation

PSYCHO_SOCIAL_REHABILITATION_CENTER

-

Psychosocial Functional Rehabilitation

REEDUCATION

REEDUCATION

Reeducation

REST_HOME_CARE_BRUSSELS_REGION

RETIREMENT

Nursing home for elderly (Brussels region)

REST_HOME_CARE_DUTCH_REGION

RETIREMENT

Nursing home for elderly (Dutch region)

REST_HOME_CARE_FRENCH_REGION

RETIREMENT

Nursing home for elderly (French region)

REST_HOME_CARE_GERMAN_REGION

RETIREMENT

Nursing home for elderly (German region)

REST_HOME_ELDERLY_BRUSSELS_REGION

RETIREMENT

Rest home for elderly (Brussels region)

REST_HOME_ELDERLY_DUTCH_REGION

RETIREMENT

Rest home for elderly (Dutch region)

REST_HOME_ELDERLY_FRENCH_REGION

RETIREMENT

Rest home for elderly (French region)

REST_HOME_ELDERLY_GERMAN_REGION

RETIREMENT

Rest home for elderly (German region)

SHELTERED_LIVING_INITIATIVE

PROT_ACC

Initiatives of sheltered live for psychiatric patients

SURVEILLANCE_COT_DEATH

-

Surveillance of cot death

VISUAL_FUNCTIONAL_REVALIDATION

-

Functional rehabilitation of visual impairment

Available organizational roles

Code

Ehealth quality

Label (english)

AMBULANCE_RESCUER

AMBULANCE_RESCUER

Ambulance rescuer

AUDICIAN

AUDICIEN

Audician

AUDIOLOGIST

AUDIOLOGIST

Audiologist

BACHELOR_IN_READAPTATION_SCIENCES

READAPTATION_BACHELOR

Readaptation (bachelor)

BACHELOR_OF_APPLIED_PSYCHOLOGY

APPLIED_PSYCH_BACHELOR

Physiologic consulent (bachelor)

BACHELOR_OF_EDUCATION

-

Education (bachelor)

BACHELOR_OF_FAMILY_SCIENCES

FAMILY_SCIENCE_BACHELOR

Family science (bachelor)

BANDAGIST

TRUSS_MAKER

Truss maker

CAREGIVER

PRACTICALNURSE

Practical nurse

COGNITIVE_BEHAVIORAL_THERAPIST_FOR_CFS

-

Cognitive behavioral therapist CFS

DENTIST

DENTIST

Dentist

DIETICIAN

DIETICIAN

Dietician

DOCTOR

DOCTOR

Doctor

ERGOTHERAPIST

OCCUPATIONAL_THERAPIST

Occupational therapist (master)

IMAGING_TECHNOLOGIST

IMAGING_TECHNOLOGIST

Imaging technologist

IMPLANTS_SUPPLIER

IMPLANTPROVIDER

Dental implant provider

LAB_TECHNOLOGIST

LAB_TECHNOLOGIST

Lab technologist

LIVER_MAT_DIAB_SELFREG

-

Liver mat diab selfreg

LOGOPEDIST

LOGOPEDIST

Speech therapist

MASTER_IN_GERONTOLOGY

GERONTOLOGY_MASTER

Gerontology (master)

MASTER_IN_ORTHOPEDAGOGICS

ORTHOPEDAGOGIST_MASTER

Remedial educationalist (master)

MASTER_IN_PSYCHOMOTOR_THERAPY

PSYCHOMOTOR_THERAPY

Psychomotor therapy (master)

MIDWIFE

MIDWIFE

Midwife

NOT_HEALTHCARE_WORKER

-

Not healthcare worker

NURSE

NURSE

Nurse

OPTICIAN

OPTICIEN

Optician

ORTHOPEDIST

ORTHOPEDIST

Orthopedist

ORTHOPTIST

ORTHOPTIST

Orthoptist

PHARMACIST

PHARMACIST

Pharmacist

PHARMACIST_ASSISTANT

PHARMACIST_ASSISTANT

Pharmacy assistant

PHARMACIST_BIOLOGIST

-

Biological pharmacist

PHYSIOTHERAPIST

PHYSIOTHERAPIST

Physiotherapist

PODOLOGIST

PODOLOGIST

Podologist

PSYCHOLOGIST

PSYCHOLOGIST

Psychologist

RVT_NURSE

-

RVT nurse

SOCIAL_ASSISTANT

SOCIAL_WORKER

Social worker

SPECIALIZED_EDUCATOR

SPECIALIZED_EDUCATOR

Specialized educator

Security

All our REST endpoints are secured using HTTP Bearer tokens. We accept tokens which are issued by either Authorization or the HealthConnect IAM. Most integrators should use the HealthConnect IAM issued token. Contact HealthConnect in case of doubt.

Authorization

For more information see https://auth.careconnect.be/docs/

HealthConnect IAM

Contact HealthConnect to receive the latest documentation.

REST principles

Our APIs are (all debates aside) restful APIs. The HTTP verbs GET, POST, PUT and DELETE are used to implement ‘CRUD’ operations on our resource endpoints.

Unless otherwise indicated, our APIs will always consume and return JSON and only JSON.

Response codes

To indicate the outcome of a request, we use the HTTP status codes. In case of an error, the body contains an extra code giving more details. The caller can use the HTTP status code for basic branching, and the code in the body for actually interpreting the result. An error code in the body will always be returned using the same HTTP status code.

Success

Successful requests return or a 200 OK, a 201 Created or a 204 No Content.

Errors

As for error codes, we follow the standard categories of 4xx Client errors and 5xx Server errors. A response with a 4xx or 5xx code will always contain a response body following a fixed template.

Table 9. Error message fields

code

A code giving more details about the actual error

Required

message

A message with some more details about the origin and cause of the error. This is done on a best effort basis. This message is user friendly.

Required

description

A more detailed description of the problem and what can be done to solve it. This messsage is developer oriented.

Optional

uniqueId

Given that id, we can find the root cause of the problem more easily in our logs. Integrators are required to pass this id when asking for details about a failed call.

Optional

stacktrace

Depending on the environment and availability, we will return a stacktrace.

Optional

Error message
{
   "code":"internal_server_error",
   "message":"An unknown error has occurred.",
   "description":"The reason and origin of this error cannot be processed automatically. Contact support to further investigate this problem. Do not forget to pass the unique id returned in the response.",
   "uniqueId":"d84d49e2fb5548a8956540f778b79f50",
   "stacktrace":"..."
}

There are three groups of errors: validation errors, client errors and server errors.

Validation errors

This kind of error is always returned with the HTTP status code 422 Unprocessable Entity. Besides the usual error fields, this error contains an extra field validationErrors. The object assigned to that field contains three extra field being:

  • The field that contains the validation error

  • The error message indicating the problem

  • The value that triggered the validation violation

Validation error message
{
   "code":"input_validation_error",
   "message":"The input contains validation errors.",
   "description":"Check the error messages contained in this response to correct your input and try again. This error is entirely related to your input. Do not retry without changing the input.",
   "uniqueId":"a6399b01e8294162be4f4f914b353a4b",
   "validationErrors":[
      {
         "field":"name",
         "value":null,
         "message":"Request is missing fields. Consult the documentation for details on how to build the request."
      },
      {
         "field":"identifier",
         "value":null,
         "message":"may not be null"
      },
      {
         "field":"lastName",
         "value":null,
         "message":"Request is missing fields. Consult the documentation for details on how to build the request."
      },
      {
         "field":"firstName",
         "value":null,
         "message":"Request is missing fields. Consult the documentation for details on how to build the request."
      }
   ]
}
TVE bring in line after adjustments
Client errors

All errors in the 4xx range are client errors. We use the following non-exhaustive list of status codes: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 415 Unsupported Media Type, 422 Unprocessable Entity, etc.

Server errors

A server error is returned as either a 500 Internal Server Error, 502 Bad Gateway or a 503 Service Unavailable.

Pagination

Some of our endpoints support pagination. This is implemented using a combination of query parameters and a predefined response body.

Every resource endpoint that supports paging, accepts a page parameter and a size parameter.

https://healthservices.corilus.be/api/credentials?page=1&size=10

In the response for that request, the actual content is wrapped in a predefined body.

{
   "pageable": {
        "page": 1,
        "size": 10
   },
   "page": {
        "totalCount": "83",
        "hasMore": "true",
        "content": [ { ... }, { ... }, ... ]
   }
}

Locale

Every request requires a locale. This locale must be set via the Accept-Language header. Acceptable values are en-BE, fr-BE and nl-BE. The results returned by our services are based on and oriented towards the given locale. For instance labels and descriptions will be set accordingly.

User-Agent

Every request requires a user agent. This user agent must be set via the User-Agent HTTP header. The user agent is used in our back-end systems for logging purposes and selecting the correct licenses to other backend systems. We highly recommend passing the name of your product as user agent as this makes functionally the most sense.

When interpreting the User-Agent HTTP Header we apply the following regular expression for validation: [A-Za-z0-9-]{3,128}/[A-Z0-9.-]{1,64} Your user agent will only be accepted if it matches this pattern!

Example of a correct User-Agents: MyProductName/3.11.7