DEPRECATED

This is the OLD API for Evovia - please use Evovia API v3.

Introduction

Welcome to the Evovia API v2 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.

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

Default response for an employee

{
  "name": "Jane Doe",
  "id": "123",
  "email": "jd@mail.tld",
  "ext_id": "ABC1",
  "username": "jd",
  "gender": "f",
  "birthday": "1979-09-11"
}

Response with key_field=ext_id

{
  "name": "Jane Doe",
  "id": "ABC1",
  "email": "jd@mail.tld",
  "username": "jd",
  "gender": "f",
  "birthday": "1979-09-11"
}

Everything has a external ID (ext_id) field that is for you to use. This way you can attach your identifier to the data when creating it - making it easier when you need to find it again and update it.

Default data from API includes both Evovia ID and external ID on everything. You can change that by a simple param on the URL.

https://api.secure.evovia.com/v2/teams?key_field=ext_id

This will remove the ext_id from the data and use the value from ext_id in the returned id field.

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/v2/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.

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.

What the API can do

You can use the API in 2 ways:

creating and updating 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

Employees

A few notes about employees, users and usernames

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.

Even when an employee is deleted the username is reserved for that employee. 14 days after the employee has been deleted he can no longer be rehired and his username is released.

Get all employees

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/v2/core/employees'

The above command returns JSON structured like this:

[
  {
    "id": "123",
    "name": "ABC",
    "email": "e@mail.tld",
    "ext_id": "ABC1",
    "gender": null,
    "birthday": null,
    "employment": null
  },
  {
    "id": "123B",
    "name": "DEF",
    "email": "e@post.tld",
    "ext_id": "ZXC32",
    "gender": "m",
    "birthday": "1979-09-11",
    "employment": null
  }
]

This endpoint retrieves all employees - 25 employees at a time

HTTP Request

GET https://api.secure.evovia.com/v2/core/employees

Query Parameters

Parameter	Default	Description
page	1	Request more employees

Get a specific 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/v2/core/employees/123B'

The above command returns JSON structured like this:

{
  "id": "123B",
  "name": "DEF",
  "email": "e@post.tld",
  "ext_id": "ZXC32",
  "gender": "m",
  "birthday": "1979-09-11"
}

This endpoint retrieves a specific employee

HTTP Request

GET https://api.secure.evovia.com/v2/core/employees/<ID>

URL Parameters

Parameter	Description
ID	The ID of the employee - either Musskem.dk ID or your own ID (ext_id)

Create an employee

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json'
 -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -d '{"employee":{"email":"e@mail.tld","username":"agent","name":"James Bond","ext_id":"123"}}'
 -X POST 'https://api.secure.evovia.com/v2/core/employees'

Example of JSON data to create an employee

{
  "employee": {
    "email":"e@mail.tld",
    "username":"agent",
    "name":"James Bond",
    "ext_id":"123"
  }
}

Example of reponse from creating employee:

{
  "id": "123645AB321",
  "email":"e@mail.tld",
  "username":"agent",
  "name":"James Bond",
  "ext_id":"123",
  "gender": null,
  "birthday": null,
  "employment": null
}

This endpoint will create a new employee, but also has the ability to create a second employment for a person or rehire a sacked employee.

HTTP Request

POST https://api.secure.evovia.com/v2/core/employees

Attributes in JSON data

Name	Required	Description
email	yes	String with valid e-mail.
username	yes	String with username - will default to e-mail if not supplied.
name	yes	String with full name of employee.
gender	no	String with one letter: (m)ale or (f)emale.
birthday	no	String with date in format YYYY-MM-DD.
ext_id	no	Your ID number for the employee.
employment	no	String with title/name of employment. Required when adding a second employment!

Rehiring a sacked employee

If you've fired an employee by mistake and need to rehire him again you simply create the employee once more, with exactly the same name, e-mail, username and ext_id.

Adding a second employment

Add second employment to employee created above:

{
  "employee": {
    "email":"e@mail.tld",
    "username":"agent",
    "name":"James Bond",
    "employment":"Secret identity",
    "ext_id":"234"
  }
}

Sometimes a person has multiple employments in the same organisation. This is handle by having multiple employees in Evovia.

To help simplify the life of persons with multiple employments all employments are connected to the same user. Creating a second employment requires you to create employee with exactly the same name, e-mail and username AND supplying an employment name for this.

Response

If everyting is good we will respond with 201 - Created and set a location header pointing to the newly created employee. Alongside that will be a JSON response with the newly created employees data.

Update an employee

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -d '{"employee":{"username":"agent","name":"James Bond","ext_id":"1234987"}}'
 -X POST 'https://api.secure.evovia.com/v2/core/employees/321'

Example of JSON data to update an employee

{
  "employee": {
    "email":"new@mail.tld"
  }
}

Example of reponse from updating employee:

{
  "id": "123645AB321",
  "email":"new@mail.tld"
  "username":"agent",
  "name":"James Bond",
  "ext_id":"123",
  "gender": null,
  "birthday": null,
  "employment": null
}

HTTP Request

PUT https://api.secure.evovia.com/v2/core/employees/<ID>

Attributes in JSON data

Name	Required	Description
email	no	String with valid e-mail.
username	no	String with username - will default to e-mail if not supplied.
name	no	String with full name of employee.
gender	no	String with one letter: (m)ale or (f)emale.
birthday	no	String with date in format YYYY-MM-DD.
ext_id	no	Your ID number for the employee.
employment	no	String with title/name of employment.

Delete an 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/v2/core/employees/321'

If this employee has multiple employments he will still be able to log in to the other employment. If it was the only one the person does no longer have access to Evovia.

Did you fire the employee by mistake you can rehire him.

HTTP Request

https://api.secure.evovia.com/v2/core/employees/<ID>

URL Parameters

Parameter	Description
ID	The ID of the employee - either Musskem.dk ID or your own ID (ext_id)

Teams

About teams and ID's

Teams is where the real work happens. They are the leaf on the organisation and the place employees are attached. They are the groups used for many types of dialogs and where leader is connected to employees.

ID fields

Team has a lot of relations, they are returned as ID's. Default is Evovia ID but if you have set ext_id as key that will be returned for all these values.

department
employees
responsible_employee

About employees in teams

An employee can ONLY be in one team, if you insert the same employee in more teams he will just be moved to the last team you insert him into.

Get all teams

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/v2/core/teams'

The above command returns JSON structured like this:

[
  {
    "id": "234",
    "department": "12332",
    "name": "ABC",
    "employees": [
      "123",
      "321"
    ],
    "ext_id": "101",
    "responsible_employee": "321"
  },
  {
    "id": "90",
    "name": "ABCD",
    "employees": [
      "321",
      "543"
    ],
    "responsible_employee": "9908",
  }
]

This endpoint retrieves all teams - 25 teams at a time.

HTTP Request

GET https://api.secure.evovia.com/v2/core/teams

Query Parameters

Parameter	Default	Description
page	1	Request more teams

Get a specific 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/v2/core/teams/234'
``

> The above command returns JSON structured like this:

```json
{
  "id": "234",
  "department": "12332",
  "name": "ABC",
  "employees": [
    "123",
    "321"
  ],
  "ext_id": "203",
  "responsible_employee": "321"
}

HTTP Request

GET https://api.secure.evovia.com/v2/core/teams/<ID>

URL Parameters

Parameter	Description
ID	The ID of the team - either Musskem.dk ID or your own ID (ext_id)

Create a team

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -d '{"team":{"name":"ABC","department":"12332","employees":["123","321"],"responsible_employee":"321","ext_id":"101"}}'
 -X POST 'https://api.secure.evovia.com/v2/core/teams'

Example of JSON data for creating team:

{
  "team": {
    "department": "12332",
    "name": "ABC",
    "employees": [
      "123",
      "321"
    ],
    "ext_id": "101",
    "responsible_employee": "321"
  }
}

Responds with data on newly created team:

{
  "id": "234",
  "department": "12332",
  "name": "ABC",
  "employees": [
    "123",
    "321"
  ],
  "ext_id": "101",
  "responsible_employee": "321"
}

HTTP Request

POST https://api.secure.evovia.com/v2/core/teams

Attributes in JSON data

Name	Required	Description
department	yes	ID of department where team is to be placed.
name	no	String with full name of team.
ext_id	no	Your ID number for the team.
employees	no	ID of employees to be put into this team. Employees can only be in one team at a time.
responsible_employee	no	ID of leader for this team.

Response

If everyting works out the response will be with HTTP header 201 - Created, along with a location header pointing to the new team. Full JSON data on newly created team is also present.

Update a specific team

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -d '{"team":{"name":"ABC","department":"12332","employees":["123","321"]}}'
 -X PUT 'https://api.secure.evovia.com/v2/core/teams/123'

Example of JSON data for updating team:

{
  "team": {
    "department": "3210",
    "name": "ABCDEF",
  }
}

Responds with new complete data for team:

{
  "id": "234",
  "department": "3210",
  "name": "ABCDEF",
  "employees": [
    "123",
    "321"
  ],
  "ext_id": "101",
  "responsible_employee": "321"
}

HTTP Request

PUT https://api.secure.evovia.com/v2/core/teams<ID>

Attributes in JSON data

Name	Required	Description
department	yes	ID of department where team is to be placed.
name	no	String with full name of team.
ext_id	no	Your ID number for the team.
employees	no	ID of employees to be put into this team. Employees can only be in one team at a time.
responsible_employee	no	ID of leader for this team.

Moving a team to a new department

With update you can also change the department to move the team to a new location in organisation. All employees will follow the team to its new location.

Updating list of employees

The list of employees is a full list - so if you want to add an employee to the team you must supply a full list with both new and old team members. If you wish to remove all members from team you must supply an empty list.

Delete a team

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

HTTP Request

DELETE https://api.secure.evovia.com/v2/core/teams<ID>

URL Parameters

Parameter	Description
ID	The ID of the team - either Musskem.dk ID or your own ID (ext_id)

Departments

Departments are the building blocks for your companys organisation in Evovia. Managers are set as responsible for departments, gaining access to configuration and reports for that branch of the organisation tree.

Everytime you create or update a department you set its parent department - building the organisation from top to bottom.

ID fields

Department has relations to other departments and to managers, they are returned as ID's. Default is Evovia ID but if you have set ext_id as key that will be returned for all these values.

Get all departments

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/v2/core/departments'

The above command returns JSON structured like this:

[ { "id": "123", "name": "ABC" "ext_id": "007", "parent_department": "99875", "responsible_employee": "1231" }, { "id": "123B", "name": "DEF" "ext_id": "008", "parent_department": "123", "responsible_employee": "1231" } ]

This endpoint retrieves all departments - 25 departments at a time.

HTTP Request

GET https://api.secure.evovia.com/v2/core/departments

Query Parameters

Parameter	Default	Description
page	1	Request more departments

Get a specific 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/v2/core/departments/123789'

The above command returns JSON structured like this:

{
  "name": "Department name",
  "id": "123789",
  "ext_id": "007",
  "parent_department": "99875",
  "responsible_employee": "1231"
}

HTTP Request

GET https://api.secure.evovia.com/v2/core/departments/<ID>

URL Parameters

Parameter	Description
ID	The ID of the department - either Musskem.dk ID or your own ID (ext_id)

Create a department

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'company_id: <CID>'
 -H 'access_token: <TOKEN>'
 -d '{"department":{"name":"New department","parent_department":"1234G43Z","ext_id":"007"}}'
 -X GET 'https://api.secure.evovia.com/v2/core/departments'

Example of JSON data for creating department:

{
  "department": {
    "parent_department": "12332",
    "name": "ABC",
    "ext_id": "101",
    "responsible_employee": "321"
  }
}

Responds with data on newly created department:

{
  "id": "234",
  "name": "ABC",
  "ext_id": "101",
  "parent_department": "12332",
  "responsible_employee": "321"
}

HTTP Request

POST https://api.secure.evovia.com/v2/core/departments

Attributes in JSON data

Name	Required	Description
name	no	String with full name of department.
parent_department	yes	ID of department where department is to be placed.
responsible_employee	no	ID of manager for this department.
ext_id	no	Your ID number for the department.

Response

If everyting works out the response will be with HTTP header 201 - Created, along with a location header pointing to the new department. Full JSON data on newly created department is also present.

Update a department

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'company_id: CID'
 -H 'access_token: token'
 -d '{"department":{"name":"Updated department"}}'
 -X PUT 'https://api.secure.evovia.com/v2/core/departments/123789'```

> Example of JSON data for updating department:

```json
{
  "department": {
    "name": "ABCDEF",
  }
}

Responds with new complete data for department:

{
  "id": "234",
  "name": "ABCDEF",
  "ext_id": "101",
  "parent_department": "12332",
  "responsible_employee": "321"
}

HTTP Request

PUT https://api.secure.evovia.com/v2/core/departments<ID>

Attributes in JSON data

Name	Required	Description
name	no	String with full name of department.
parent_department	yes	ID of department where department is to be placed.
responsible_employee	no	ID of manager for this department.
ext_id	no	Your ID number for the department.

Delete a department

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

HTTP Request

DELETE https://api.secure.evovia.com/v2/core/departments<ID>

URL Parameters

Parameter	Description
ID	The ID of the department - either Musskem.dk ID or your own ID (ext_id)

Sickness absense

When an employee is calling in sick you start a sickness absense, which will prompt the leader to talk to the employee.

Automating this with the API is only really usefull if you already have a system for managing sickness absense.

Get all sick employees

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/v2/siab/dialogs'

The above command returns JSON structured like this:

[
  {
    "id": "123",
    "name": "ABC",
    "date": "2018-01-03",

  },
  {
    "id": "123B",
    "name": "DEF",
    "date": "2018-02-03",
  }
]

This gives you all sick employees, their employee ID and the date they were reported sick.

HTTP Request

GET https://api.secure.evovia.com/v2/siab/dialogs

Report employee sick

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'company_id: CID'
 -H 'access_token: token'
 -d '{"employee":"708","date":"2016-12-24"}'
 -X POST 'https://api.secure.evovia.com/v2/siab/dialogs'

Attributes in JSON data

Name	Required	Description
employee	yes	ID of employee to report sick.
date	yes	Date employee is reported sick. Format: YYYY-MM-DD.

Response

HTTP header 201 - Created.

Update sick date

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'company_id: CID'
 -H 'access_token: token'
 -d '{"date":"2019-12-24"}'
 -X PATCH 'https://api.secure.evovia.com/v2/siab/dialogs/708'

Example of JSON data to update first day of sickleave

{
  "date": "2019-12-24"
}

The above command returns JSON structured like this:

{
  "id": "708",
  "name": "ABC",
  "date": "2019-12-24",
}

HTTP Request

GET https://api.secure.evovia.com/v2/siab/dialogs/<EMPLOYEE_ID>

URL Parameters

Parameter	Description
ID	The ID of the employee - either Musskem.dk ID or your own ID (ext_id)

Report employee fit

curl -v -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'company_id: CID'
 -H 'access_token: token'
 -d '{"employee":"708","date":"2016-12-24"}'
 -X DELETE 'https://api.secure.evovia.com/v2/siab/dialogs'

Attributes in JSON data

Name	Required	Description
employee	yes	ID of employee to report fit.
date	yes	Last day of employees sick leave. Format: YYYY-MM-DD.

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.

DEPRECATED

Introduction

One-way sync

Unique ID's

Authentication

Build your organisation

What the API can do

Employees

A few notes about employees, users and usernames

Get all employees

HTTP Request

Query Parameters

Get a specific employee

HTTP Request

URL Parameters

Create an employee

HTTP Request

Attributes in JSON data

Rehiring a sacked employee

Adding a second employment

Response

Update an employee

HTTP Request

Attributes in JSON data

Delete an employee

HTTP Request

URL Parameters

Teams

About teams and ID's

ID fields

About employees in teams

Get all teams

HTTP Request

Query Parameters

Get a specific team

HTTP Request

URL Parameters

Create a team

HTTP Request

Attributes in JSON data

Response

Update a specific team

HTTP Request

Attributes in JSON data

Moving a team to a new department

Updating list of employees

Delete a team

HTTP Request

URL Parameters

Departments

Structure of the organisation and ID's to related data

ID fields

Get all departments

HTTP Request

Query Parameters

Get a specific department

HTTP Request

URL Parameters

Create a department

HTTP Request

Attributes in JSON data

Response

Update a department

HTTP Request

Attributes in JSON data

Delete a department

HTTP Request

URL Parameters

Sickness absense

Get all sick employees

HTTP Request

Report employee sick

Attributes in JSON data

Response

Update sick date

HTTP Request

URL Parameters

Report employee fit

Attributes in JSON data

Errors