NAV Navbar
shell
  • DEPRECATED
  • Introduction
  • Employees
  • Teams
  • Departments
  • Sickness absense
  • Errors
  • DEPRECATED

    This is the OLD API for Musskema.dk - please use Musskema.dk API v3.

    Introduction

    Welcome to the Musskema.dk API v2 documentation. To access the API you need to have a company on Musskema.dk 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 Musskema.dk.

    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 Musskema.dk 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 Musskema.dk ID and external ID on everything. You can change that by a simple param on the URL.

    https://api.secure2.musskema.dk/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.secure2.musskema.dk/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 Musskema.dk 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:

    Then there are a few addons:

    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.secure2.musskema.dk/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.secure2.musskema.dk/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.secure2.musskema.dk/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.secure2.musskema.dk/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.secure2.musskema.dk/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.secure2.musskema.dk/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 Musskema.dk.

    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.secure2.musskema.dk/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.secure2.musskema.dk/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.secure2.musskema.dk/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 Musskema.dk.

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

    HTTP Request

    https://api.secure2.musskema.dk/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 Musskema.dk ID but if you have set ext_id as key that will be returned for all these values.

    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.secure2.musskema.dk/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.secure2.musskema.dk/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.secure2.musskema.dk/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.secure2.musskema.dk/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.secure2.musskema.dk/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.secure2.musskema.dk/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.secure2.musskema.dk/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.secure2.musskema.dk/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.secure2.musskema.dk/v2/core/teams/123'
    

    HTTP Request

    DELETE https://api.secure2.musskema.dk/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 Musskema.dk. 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 Musskema.dk 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.secure2.musskema.dk/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.secure2.musskema.dk/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.secure2.musskema.dk/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.secure2.musskema.dk/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.secure2.musskema.dk/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.secure2.musskema.dk/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.secure2.musskema.dk/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.secure2.musskema.dk/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.secure2.musskema.dk/v2/core/departments/123'
    

    HTTP Request

    DELETE https://api.secure2.musskema.dk/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.secure2.musskema.dk/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.secure2.musskema.dk/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.secure2.musskema.dk/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.secure2.musskema.dk/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.secure2.musskema.dk/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.secure2.musskema.dk/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.