REST interface

Information for companies

Authentication

All managing organisations must authenticate themselves using a time-limited access token (OAuth Bearer Token). To do this, they are provided with the service user credentials (ID and secret) via the portal (in the ‘Data Import Settings’ tab). Using these credentials, the organisation can request a time-limited access token via the interface. The access token must then be transmitted to the incident interface as a bearer token within the authentication header during HTTP communication with the interface.

If a company manages several other companies, the access token must be created exclusively for the CareFlex ID of the managing company. All other reports relating to different CareFlex IDs are submitted using the managing company’s access token. Consequently, only one service user/service user secret combination is required to manage all companies assigned to the main CareFlex ID.

Authorisation

All companies must submit both the API token and the CareFlex ID when making a declaration.

When submitting the report, you must include the CareFlex ID (of the eligible company) and the API token (of the reporting company).

The API token can be generated in the company portal under “CRM” / “Data import settings”. There is only one API token for all entities managed by a company.

The validity of the CareFlex ID in conjunction with the API token is not checked when the message is sent, but can be verified via the feedback function once the message has been successfully imported into the portal.

Functionalities of the interface

  • Reporting HR incidents with and without master data
    REST endpoint: incident/new
    Note: Up to 100 HR incidents can be transmitted in a single REST request.
  • Empty report
    REST endpoint: incident/none
    Description: This request must be made if no HR incidents have occurred in the current month.

Communication example

Access token query

POST EP1 (see above)
with a JSON body:
{
"grant_type":"password",
"username":"<user_id (service user)>",
"password":"<user_secret (service user)>"
}
and headers:
"Content-Type: application/json"

The response contains an access token that is valid for 12 hours

{
"access_token":"P7kmfo8HXItLLOReHq65o4%§ggg45dYhSm5ODc",
"token_type":"Bearer",
"expires_in":43200,
                "created_at":1589887223
}

The access token is used as a bearer token when communicating with the interface

REST
POST EP3 (see above)
with REST headers:
“Authorization: Bearer
P7kmfo8HXItLLOReHq65o4%§ggg45dYhSm5ODc” “Content-Type: application/json;charset=UTF-8”

 

Empty message

REQUEST
{
"careflexId": "09ce3580d84bf087",
"apiToken": "maL0HMDszA2b9PKiqCAZRGh0ZDpVjmvc",
"createdAt": “2020-10-24”
}
RESPONSE
HTTP RESPONSE: 201 Created

Payload examples

Notification with and without master data

REQUEST
{
"careflexId": "09ce3580d84bf087",
"apiToken": "maL0HMDszA2b9PKiqCAZRGh0ZDpVjmvc",
"incidentList": [
{
           "externalId": "1000" ,
"type": "NEW",
"employeeId": "49239697103",
"createdAt": "2020-10-24",
"validFrom": "2020-10-24",
"employee": {
"title": "Prof. Dr.",
"firstName": "Thomas",
"lastName": "Mustermann",
"birthday": "15 January 1979",
"sex": "m",
"address": {
"street": "Muster Street",
"houseNumber": 9,
                   "addressSuffix": "c/o Max Hauptmieter",
"zipCode": "01234",
"city": "Musterstadt",
"country": “DE”
},
               "job": {
"employmentSite": "Branch 1",
"employmentStatus": "T",
"startOfEmployment": "2020-04-24",
                  "personnelNumber": "string",
"management": false
},
"contact": {
"emailBusiness": "thomas.mustermann@musterfirma.de",
"mobileBusiness": "0123 12345678",
"landlineBusiness": “030 12345678”
}
}
},
{
"externalId": "1234-xx",
           "type": "SDB",
"createdAt": "2021-06-30",
"validFrom": "2021-07-01",
"employeeId": "12345678901",
           "employee": {
"firstName": "Thomas",
"lastName": “Mustermann”
}
},
{
"type": "WIK",
          "employeeId": "49239697103",
"createdAt": "2020-09-24",
"validFrom": "2020-08-24"
}
]
}

RESPONSE
{
"importId": "8d2adbc0-4d63-4cec-a8f4-445b08a3e33e",
"incidentResponseList": [
{
"rowNumber": 0,
           "incidentId": "8ba8977c-a75b-4ec0-9798-7a7f14209720",
"externalId": "1000",
"employeeId": "49239697103",
          "type": “NEW”
},
{
"rowNumber": 1,
"incidentId": "916aebfc-2feb-429b-8631-52703a195ad9",
           "externalId": "1234-xx",
"employeeId": "12345678901",
"type": “SDB”
},
{
"rowNumber": 2,
           "incidentId": "e8b77933-2a31-404c-9e23-8b547b37068f",
"externalId": null,
"employeeId": "49239697103",

          "type": “WIK”
}
]
}