Introduction

Welcome to the Evovia API v3 documentation. To access the API you need to have a company on Evovia and have the API access token for that company.

The API allows you to maintain employees, teams, departments and sickness absense data so you can have your ERP, HR or whatever other tool sync its data to Evovia.

What the API can do

You can use the API in 2 ways:

creating and updating users and employees - this is the minimum
create organisation structure and place employees in teams - this is optional, without this organisation is created from within Musskame.dk

Then there are a few addons:

create and delete sickness absense - if your employees are registred as sick in another system you can have the status transfered to Evovia to start a sickness absense dialog
WPA organisation - the workplace assesment is using a organisational structure of its own, it is possible to enable access to this structure from API, to manage departments and teams in WPA. The API endpoints are the same as for creating the main organisation.

One-way sync

We have simplified the world a bit by only allowing one-way syncronisation. When you enable API sync for a part of Evovia that part will no longer be available to users on the site. If you setup syncronisation of employees then employees will no longer be able to change name, username or other profile data.

Unique ID's

All resources in Evovia requires you to supply an ID. This should make it easier to integrate to Evovia as you can use your own ID number/string to identify resources. Everywhere you see ID in this documentation it refers to a value you have supplied.

As the section header suggests it should be an unique ID within the data-type. There can not be two users with same ID, but you could have both user and a team with same ID.

JSON data and headers

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: 10238497'
 -H 'access_token: 01298347edf923874a'
 -d '{"user":{"name":"Jane Doe","gender":"f","birthday":"1989-09-13","email":"jane@mail.tld","username":"user_1_name","id":"78765"}}'
 -X POST 'https://api.secure.evovia.com/v3/core/users'

all data returned from API is in Unicode UTF-8 encoded JSON. We expect to receive data in same format and encoding.
all resources expect data to be wrapped in an outer structure, named after the resource you are creating/updating.
all requests should have accept and content-type headers set to application/json.

See example on right side of page, for both headers and data.

Authentication

JWT (JSON web token)

Example of authentication with JWT:

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'JWT: eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NTA1NjI2OTcsIm5iZiI6MTU1MDU2MjY5MiwiY29tcGFueV9pZCI6IjEwMDAwMSJ9.FvEyb9ZAKPVsI2OUd91UzlYlrnecuhQqCd-_dVRK79w'
 -X GET 'https://api.secure.evovia.com/v3/core/departments'

We have choosen JWT for authentication. There are lots of open source libraries for many languages, so it should be fairly easy to implement. With JWT we do not expose the pre-shared API access token in a header, and we get expiration on request tokens thus reducing the risk of replay attacks.

Example of JWT payload:

{
  "exp": 1550562697,
  "nbf": 1550562692,
  "company_id": 100001
}

There are a number of features in JWT, we have choosen to use the following:

Algorithm for signature is HS256.
Both exp and nbf are required, and there can be no more than 15 seconds between.
The secret to sign the JWT token is the API access token you got from our support team.

In the JWT payload you should send company_id = your company ID on Evovia.

Try to paste the token from the example on jwt.io and see the contents of the token.

Old plaintext header authentication

# With shell, you can just pass the correct header with each request
curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: 10238497'
 -H 'access_token: 01298347edf923874a'
 -X GET 'https://api.secure.evovia.com/v3/core/departments'

Make sure to replace 01298347edf923874a with your API key and 10238497 with your company id.

Authentication is done by HTTP headers. You must supply both company_id and access_token headers. This feature is still enabled, for backward compatibility, but it is strongly encouraged to use JWT authentication header.

IP whitelist

On top of authentication it is possible to lock down the API to a select number of IPv4 adresses. Contact our support team if you wish to enable this feature.

Changelog

2019-02-19: Added option to enhance security by using JWT for authentication. Added IP whitelist option.
2019-01-16: It is now possible to set system language when creating employee. Default is switched from English to Danish. Sheet language now defaults to company primary language.

Users and employees

Splitting users and employees

Data for employee, consisting of an employment and data for user behind employee:

[{
  "id": "1234e",
  "employement": "Programmer",
  "user": {
    "id": "987u",
    "username": "jh987",
    "name": "Jens Hansen",
    "email": "geek@programmer.it",
    "gender": "m",
    "birthday": "1979-09-11"
  }
},{
  "id": "5678e",
  "employement": "Geek",
  "user": {
    "id": "987u",
    "username": "jh987",
    "name": "Jens Hansen",
    "email": "geek@programmer.it",
    "gender": "m",
    "birthday": "1979-09-11"
  }
}]

Everybody in a company is an employee - no matter your privileges or permissions you are first and foremost an employee.

Employees are not users! That might sound strange, but some people have multiple employments within the same organisation - each of those is an employee, but all of a persons employments are connected to the same user to only have one username and password.

Example data -> see right side

Employee Jens Hansen with ID 1234e can be placed in a team. The other employee with ID 5678e is the same physical person - the same user - and can now be placed in another team.

Employee is the handle to data

The employee is the entity that receives permissions to do things in the system, and is also where conversational data is kept. Delete an employee and the person will no longer have access to data!

Some organisations will remove an employee and create him again when moving the employee to a new department. That is a bit dangerous if you just copy that procedure to Evovia. Doing so will remove all data from the employee. If you are going to move an employee, and at the same time give him a new ID, you should do exactly that in Evovia. Then the employee will still have access to his data.

Some people ask about confidentiality between leader and employee when moving employees between teams, or changing leader on a team. We'll handle that for you! So you can safely move employees without risk of someone seing things they should not.

- Users

Create user

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -d '{"user":{"name":"Jane Doe","gender":"f","birthday":"1989-09-13","email":"jane@mail.tld","username":"user_1_name","id":"78765"}}'
 -X POST 'https://api.secure.evovia.com/v3/core/users'

HTTP 201 Created - with complete data of new user:

{
  "name": "Jane Doe",
  "gender": "f",
  "birthday": "1989-09-13",
  "email": "jane@mail.tld",
  "username": "user_1_name",
  "id": "78765"
}

Data in user JSON structure

Field	Value	Required
name	Name of user	Yes
gender	f/m (female/male)	No
birthday	YYYY-MM-DD	No
email	Valid e-mail address	Yes
username	Unique username	Yes
id	Your ID for user	Yes

Update user

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -d '{"user":{"name":"Jane Fonda"}}'
 -X PATCH 'https://api.secure.evovia.com/v3/core/users/78765'

HTTP 200 OK - with complete data of updated user:

{
  "name": "Jane Fonda",
  "gender": "f",
  "birthday": "1989-09-13",
  "email": "jane@mail.tld",
  "username": "user_1_name",
  "id": "78765"
}

Data in user JSON structure

You only need to supply the values you wish to update.

Field	Value	Required
name	Name of user	No
gender	f/m (female/male)	No
birthday	YYYY-MM-DD	No
email	Valid e-mail address	No
username	Unique username	No
id	Your ID for user	No

Delete user

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -X DELETE 'https://api.secure.evovia.com/v3/core/users/78765'

HTTP 200 OK

It is not possible to delete a user that still has active employees attached
Deleting a user is permanent, there is no undo. If you change you mind you need to recreate the user.

Show user

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -X GET 'https://api.secure.evovia.com/v3/core/users/78765'

HTTP 200 OK - with complete data of the user:

{
  "name": "Jane Fonda",
  "gender": "f",
  "birthday": "1989-09-13",
  "email": "jane@mail.tld",
  "username": "user_1_name",
  "id": "78765"
}

Show user list

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -X GET 'https://api.secure.evovia.com/v3/core/users'

HTTP 200 OK - with array of users:

[{
  "name": "Jane Fonda",
  "gender": "f",
  "birthday": "1989-09-13",
  "email": "jane@mail.tld",
  "username": "user_1_name",
  "id": "78765"
}]

List is paginated

- Employees

Create employee

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -d '{"employee":{"employment":"Geek","id":"4711"}}'
 -X POST 'https://api.secure.evovia.com/v3/core/users/78765/employees'

HTTP 200 OK - with complete data of employee:

{
  "employment": "Geek",
  "id": "4711",
  "user": {
    "name": "Jane Fonda",
    "gender": "f",
    "birthday": "1989-09-13",
    "email": "jane@mail.tld",
    "username": "user_1_name",
    "id": "78765"
  }
}

Creating an employee is on an endpoint under users as this will always require a user.

Data in employee JSON structure

Field	Value	Required
employment	Title of employment	No
system_language	User interface language (en or da), defaults to Danish	No
id	Your ID for employee	Yes

Update employee

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -d '{"employee":{"employment":"Programmer"}}'
 -X PATCH 'https://api.secure.evovia.com/v3/core/employees/4711'

HTTP 200 OK - with complete data of updated employee:

{
  "employment": "Programmer",
  "id": "4711",
  "user": {
    "name": "Jane Fonda",
    "gender": "f",
    "birthday": "1989-09-13",
    "email": "jane@mail.tld",
    "username": "user_1_name",
    "id": "78765"
  }
}

Data in employee JSON structure

Field	Value	Required
employment	Title of employment	No
id	Your ID for employee	No

Show employee

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -X GET 'https://api.secure.evovia.com/v3/core/employees/4711'

HTTP 200 OK - with complete data of employee:

{
  "employment": "Programmer",
  "id": "4711",
  "user": {
    "name": "Jane Fonda",
    "gender": "f",
    "birthday": "1989-09-13",
    "email": "jane@mail.tld",
    "username": "user_1_name",
    "id": "78765"
  }
}

Show employee list

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -X GET 'https://api.secure.evovia.com/v3/core/employees/4711'

HTTP 200 OK - with array of employees:

[{
  "employment": "Programmer",
  "id": "4711",
  "user": {
    "name": "Jane Fonda",
    "gender": "f",
    "birthday": "1989-09-13",
    "email": "jane@mail.tld",
    "username": "user_1_name",
    "id": "78765"
  }
}]

List is paginated

Delete (fire) employee

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -X DELETE 'https://api.secure.evovia.com/v3/core/employees/4711'

HTTP 200 OK

As all conversational data is attached to an employee, this will only do a softdelete and mark the employee as fired. This way you will be able to rehire the user, if you have made a mistake.

You can not delete the owner of the topmost department in the organisation.

Undelete (rehire) employee

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -X PATCH 'https://api.secure.evovia.com/v3/core/users/78765/employees/4711'

HTTP 200 OK

Rehiring an employee is on an endpoint under users as this will always require a user.

you can not rehire an employee if you have created a new employee with same ID
when you rehire you set the ID of the user you wish to attach the employee to, useful for when you have also deleted the old user employee was attached to

Departments, teams and dialogs

Build your organisation

The organisation in Evovia consists of a tree of departments with team as the leafs. Departments holds nothing but managers, employees are working from the teams.

Teams are handles to data

As mentioned employees is the handle to data, so deleting an employee will remove data even though the user is still in Evovia. In the same way the team is the handle the leader has to data between him and the employee. If you delete the team all dialog data on that team will be inaccessible to the leader.

Owner / responsible person on team and departments

On teams and departments it is possible to set an owner, but in the response and when fetching teams and departments you will see a responsible person. The reason for this is quite simple - owner is optional, and if you do not supply one it is the closest owner (going up in the organisation) who will be responsible for the team or department.

- Teams

Create team

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -d '{"team":{"name":"The A Team","owner":"4711","id":"A11111"}}'
 -X POST 'https://api.secure.evovia.com/v3/core/departments/D9/teams'

HTTP 201 Created - with complete data of new team, including responsible_employee and department:

{
  "name": "The A Team",
  "id": "A11111",
  "responsible_employee": {
    "employment": "Programmer",
    "id": "4711",
    ...
  },
  "employees": [],
  "department": {
    "name": "The Firm",
    "id": "9987",
    ...
  }
}

Creating a team is on an endpoint under departments as this will always require a department.

Field	Value	Required
name	Name of team	Yes
owner	ID for employee who owns the team	No
id	Your ID for team	Yes

Read about owner and responsible employee

Update team

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -d '{"team":{"name":"The A1 Team","id":"A1"}}'
 -X PATCH 'https://api.secure.evovia.com/v3/core/teams/A11111'

HTTP 200 OK - with complete data of updated team, including responsible_employee, employees and department:

{
  "name": "The A1 Team",
  "id": "A1",
  "responsible_employee": {
    "employment": "Programmer",
    "id": "4711",
    ...
  },
  "employees": [
    {
      "employment": "Geek",
      "id": "4321",
      ...
    },
    {
      "employment": "Another Geek",
      "id": "1234",
      ...
    }
  ],
  "department": {
    "name": "The Firm",
    "id": "9987",
    ...
  }
}

Field	Value	Required
name	Name of team	No
owner	ID for employee who owns the team	No
id	Your ID for team	No

Read about owner and responsible employee

Delete team

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -X DELETE 'https://api.secure.evovia.com/v3/core/teams/A11111'

HTTP 200 OK

Move team

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -X PATCH 'https://api.secure.evovia.com/v3/core/departments/D11/teams/A11111'

HTTP 200 OK

Moves team to chosen department.

Show team

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -X GET 'https://api.secure.evovia.com/v3/core/teams/A11111'

HTTP 200 OK - with complete data of team, including responsible_employee, employees and department:

{
  "name": "The A Team",
  "id": "A1",
  "responsible_employee": {
    "employment": "Programmer",
    "id": "4711",
    ...
  },
  "employees": [
    {
      "employment": "Geek",
      "id": "4321",
      ...
    },
    {
      "employment": "Another Geek",
      "id": "1234",
      ...
    }
  ],
  "department": {
    "name": "The Firm",
    "id": "9987",
    ...
  }
}

Show team list

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -X GET 'https://api.secure.evovia.com/v3/core/teams'

HTTP 200 OK - array with teams:

[{
  "name": "The A Team",
  "id": "A1",
  "responsible_employee": {
    "employment": "Programmer",
    "id": "4711",
    ...
  },
  "employees": [
    {
      "employment": "Geek",
      "id": "4321",
      ...
    },
    {
      "employment": "Another Geek",
      "id": "1234",
      ...
    }
  ],
  "department": {
    "name": "The Firm",
    "id": "9987",
    ...
  }
}]

List is paginated

- Employees in team

As mentioned both in here and here there are som rules about employees and teams and how it all relates to data, so please read that.

Add employee to team

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -X POST 'https://api.secure.evovia.com/v3/core/teams/A11111/employees/4711'

HTTP 200 OK - with complete team data:

{
  "name": "The A Team",
  "id": "A11111",
  "responsible_employee": {
    "employment": "Leader",
    "id": "00001",
    ...
  },
  "employees": [
    {
      "employment": "Programmer",
      "id": "4711",
      ...
    }
  ],
  "department": {
    "name": "The Firm",
    "id": "9987",
    ...
  }
}

Remove employee from team

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -X DELETE 'https://api.secure.evovia.com/v3/core/teams/A11111/employees/4711'

HTTP 200 OK - with complete team data:

{
  "name": "The A Team",
  "id": "A11111",
  "responsible_employee": {
    "employment": "Leader",
    "id": "00001",
    ...
  },
  "employees": [],
  "department": {
    "name": "The Firm",
    "id": "9987",
    ...
  }
}

- Departments

Create department

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -d '{"department":{"name":"Basement crew","owner":"4711","id":"D987"}}'
 -X POST 'https://api.secure.evovia.com/v3/core/departments/D9/departments'

HTTP 201 Created - with complete data of new department, including responsible_employee:

{
  "name": "Basement crew",
  "id": "D987",
  "responsible_employee": {
    "employment": "Programmer",
    "id": "4711",
    ...
  },
  "parent_id": "D9"
}

Creating a department is on an endpoint under another department as this will always require a parent department.

Field	Value	Required
name	Name of department	Yes
owner	ID for employee who owns department	No
id	Your ID for department	Yes

Read about owner and responsible employee

Update department

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -d '{"department":{"name":"Basement department"}}'
 -X PATCH 'https://api.secure.evovia.com/v3/core/departments/D987'

HTTP 200 OK - with complete data of updated department, including responsible_employee:

{
  "name": "Basement department",
  "id": "D987",
  "responsible_employee": {
    "employment": "Programmer",
    "id": "4711",
    ...
  },
  "parent_id": "D9"
}

Field	Value	Required
name	Name of department	No
owner	ID for employee who owns department	No
id	Your ID for department	No

Read about owner and responsible employee

Delete department

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -X DELETE 'https://api.secure.evovia.com/v3/core/departments/D987'

HTTP 200 OK

Move department

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -X PATCH 'https://api.secure.evovia.com/v3/core/departments/D11/departments/D987'

HTTP 200 OK

Moves department {id} below department {department_id}. You can not move a department below it self.

Show department

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -X GET 'https://api.secure.evovia.com/v3/core/departments/D987'

HTTP 200 OK - with complete data of department, including responsible_employee:

{
  "name": "Basement department",
  "id": "D987",
  "responsible_employee": {
    "employment": "Programmer",
    "id": "4711",
    ...
  },
  "parent_id": "D9"
}

Show department list

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -X GET 'https://api.secure.evovia.com/v3/core/departments'

HTTP 200 OK - with array of departments:

[{
  "name": "Basement department",
  "id": "D987",
  "responsible_employee": {
    "employment": "Programmer",
    "id": "4711",
    ...
  },
  "parent_id": "D9"
}]

List is paginated

- Delegations

Delegations is the same for both teams and departments, so this chapter covers two endpoints. URL varies and reponse shows either team or department that delegation has been created on.

Responsibilities available on teams

Core/WPA	Responsibility name	Grants access to
Core	dialog_access_cv	Access to teams CV data
Core	dialog_access_onboarding	Access to onboarding dialog for team
Core	dialog_access_siab	Access to sickness absence dialog for team
Core	dialog_access_edp	Access to employee development dialog for team
WPA	dialog_access_wpa	Access to workplace assessment dialog for team

Responsibilities available on departments

Core/WPA	Responsibility name	Grants access to
Core	manage_organisation_department	Access to organisation editor for department
Core	configuration	Access to configuration for this department
Core	department_task_report_siab	Ability to read tasks for employees in department
Core	department_task_report_edp	Ability to read tasks for employees in department
WPA	department_task_report_wpa	Ability to read tasks for employees in department

any of these will also give access to statistics for this department.
any of these will also give access to organisation editor for department (when you have API enabled that is a read only access)
all of these is for the chosen department and all departments below

Create delegation

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -d '{"delegation":{"responsibility":"dialog_access_edp","employee_id":"4711"}}'
 -X POST 'https://api.secure.evovia.com/v3/core/departments/D9/delegations'

HTTP 201 Created - with data for new delegation:

{
  "id": "1234567890",
  "responsibility": "dialog_access_edp",
  "employee": {
    "employment": "Programmer",
    "id": "4711",
    ...
  },
  "department|team": {
    "name": "The Firm",
    "id": "D9",
    ...
  }
}

Field	Value	Required
responsibility	A responsibility name valid for either team or department	Yes
employee_id	Your ID for employee to delegate responsibility to	Yes

Destroy delegation

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -X DELETE 'https://api.secure.evovia.com/v3/core/departments/D9/delegations/1234567890'

HTTP 200 OK

Show delegation list

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -X DELETE 'https://api.secure.evovia.com/v3/core/departments/D9/delegations/1234567890'

HTTP 200 OK - with array of delegations for team or department:

[{
  "id": "1234567890",
  "responsibility": "dialog_access_edp",
  "employee": {
    "employment": "Programmer",
    "id": "4711",
    ...
  },
  "department|team": {
    "name": "The Firm",
    "id": "D9",
    ...
  }
}]

Sickness absense

This is a bit of a special endpoint. There are a lot of logic in Evovia around sickness absence, so to help you we have made just one endpoint for registering sickness absence. You will not need to worry about keeping track of periods in you end, we will detect overlapping periods and decide if you data should update existing or create new absence period.

Not everything can be handled, so a few rules to start with:

employee must be in team to be reported sick
if you supply a date range that overlaps multiple existing periods you will get an error

Report employee sick and fit

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -d '{"employee_id":"708","start_date":"2016-12-24"}'
 -X POST 'https://api.secure.evovia.com/v3/siab/dialogs'

If there are no errors data for absence will be returned.

HTTP header tells if you have created a new absence (201) or just updated an existing (200)

{
  "id": "9876",
  "start_date": "2016-12-24",
  "end_date": "9999-12-31",
  "employee": {
    "id": "708",
    "employment": null,
    "user": {
      "name": "Jane Doe",
      "gender": null,
      "birthday": null,
      "email": "jane@mail.tld",
      "username": "user_1_name",
      "id": "78765"
    }
  }
}

Attributes in JSON data

Name	Required	Description
employee_id	yes	ID of employee to report sick.
start_date	yes	Date employee is reported sick. Format: YYYY-MM-DD.
end_date	no	Last day employee is sick. Format: YYYY-MM-DD.

End date is optional, if you leave out end date the employee is considered sick from start date and for ever after.

Start and end dates and all the rules

Reporting same employee sick with new dates

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -d '{"employee_id":"708","start_date":"2016-12-21","end_date":"2017-01-01"}'
 -X POST 'https://api.secure.evovia.com/v3/siab/dialogs'

Results in simply updating the existing absence (HTTP 200 OK)

{
  "id": "9876",
  "start_date": "2016-12-21",
  "end_date": "2017-01-01",
  "employee": {
    "id": "708",
    "employment": null,
    "user": {
      "name": "Jane Doe",
      "gender": null,
      "birthday": null,
      "email": "jane@mail.tld",
      "username": "user_1_name",
      "id": "78765"
    }
  }
}

If you create a new absence period that overlaps a period on the employee
- end date will be updated if you have supplied one
- start date will be updated if (either A or B below)
- A: it is before the start date on absence that it overlaps (expanding the period)
- B: you have supplied the exact same end date as the absence it overlaps (then contracting the period)
If you create a new absence period on the day after employee has been reported fit this is also considered an overlap, and will simply just extend that absence period.
If you create a new absence in the past (determined by either the employee having been sick after that period, or it is more than 2 month ago) - the absence will be silenced and no conversation will take place in Evovia.
If you create a absence that overlaps a period where end date is in the past, then the dates will be updated but since the absence is in the past it will be silenced and no notifications and conversations will be generated in Evovia.

Pagination

In HTTP headers you will see both total count and page size

Total: 40
Per-Page: 25

All list endpoints will paginate the content with default 25 entities per page.

further pages can be access with ?page={page_num} query param
limit can be raised to max 1000 per page with ?per_page={number}

Errors

Example of detailed error response:

{
  "message": "Failed", 
  "errors": [
    {
      "resource": "MUS::User", 
      "field": "username", 
      "error": "is already taken"
    }
  ]
}

We try to return a usefull HTTP status code, and together with that often a JSON response with details about the error.

Error Code	Meaning
400	Bad Request -- Just plain wrong request, could not find a way to handle that.
401	Unauthorized -- Your API key is wrong.
404	Not Found -- The requested data could not be found.
422	Unprocessable entity -- The data you gave us was not valid, please se details in JSON.
500	Internal Server Error -- Please check that you at least tried to supply company_id or access_token headers.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.