Skip to content

Calamari Public API (v1)

API for Calamari, your HR tool

Download OpenAPI description
calamari-public-openapi.json
calamari-public-openapi.yaml
Overview
URL

https://developers.calamari.dev

Calamari Team

developers@calamari.io

Languages
Servers

https://{tenantName}.calamari.io/api/

Absence type

Absence Types API

Operations

Absence requests

Absence Requests API

Operations

Current shift status

Current Shift Status API

Operations

Projects

Projects API

Operations

Shifts and breaks

Shifts and Breaks API

Operations

Start employee break.

Request

Start employee break.

Client application should send request immediately when event occurs. If there is any problem with connection or access to API event should be queued in clients side and then sent in order of occurence.

Before you can use this method, please:

  1. Configure 'API Terminal' in Calamari Clockin configuration panel
  2. Make sure API access is enabled


Expect error codes:
  1. INVALID_EMPLOYEE - when invalid employee id provided
  2. INVALID_TIME - when invalid event time provided
  3. INVALID_BREAK_TYPE - when invalid break type id provided
  4. API_TERMINAL_NOT_AVAILABLE - no API terminal configured or the employee doesn't have access to this terminal

Security
basicAuth
Bodyapplication/json
personstringrequired

Employee e-mail or login

Example: "john.white@mycompany.com"
timestring(date-time)required

Date and time of event occurence in ISO format.

breakTypeinteger(int64)required

ID break type

Example: 1
curl -i -X POST \
  -u <username>:<password> \
  'https://{tenantname}.calamari.io/api/clockin/terminal/v1/break-start' \
  -H 'Content-Type: application/json' \
  -d '{
    "person": "john.white@mycompany.com",
    "time": "2019-08-24T14:15:22Z",
    "breakType": 1
  }'

Responses

successful operation

Bodyapplication/json
personobject(Person)required

Employee description

person.​firstNamestringrequired

Employee first name

Example: "John"
person.​lastNamestringrequired

Employee first name

Example: "White"
breakStatusstringrequired

Employee break status after request

Enum"STARTED""FINISHED"
Response
application/json
{
  "person": {
    "firstName": "John",
    "lastName": "White"
  },
  "breakStatus": "STARTED"
}

Stop employee break.

Request

Stop employee break.

Client application should send request immediately when event occurs. If there is any problem with connection or access to API event should be queued in clients side and then sent in order of occurence.

Before you can use this method, please:

  1. Configure 'API Terminal' in Calamari Clockin configuration panel
  2. Make sure API access is enabled


Expect error codes:
  1. INVALID_EMPLOYEE - when invalid employee id provided
  2. INVALID_TIME - when invalid event time provided
  3. INVALID_BREAK_TYPE - when invalid break type id provided. You should use get-break-types method to find properly break type ID
  4. API_TERMINAL_NOT_AVAILABLE - no API terminal configured or the employee doesn't have access to this terminal

Security
basicAuth
Bodyapplication/json
personstringrequired

Employee e-mail or login

Example: "john.white@mycompany.com"
timestring(date-time)required

Date and time of event occurence in ISO format.

breakTypeinteger(int64)required

ID break type

Example: 1
curl -i -X POST \
  -u <username>:<password> \
  'https://{tenantname}.calamari.io/api/clockin/terminal/v1/break-stop' \
  -H 'Content-Type: application/json' \
  -d '{
    "person": "john.white@mycompany.com",
    "time": "2019-08-24T14:15:22Z",
    "breakType": 1
  }'

Responses

successful operation

Bodyapplication/json
personobject(Person)required

Employee description

person.​firstNamestringrequired

Employee first name

Example: "John"
person.​lastNamestringrequired

Employee first name

Example: "White"
breakStatusstringrequired

Employee break status after request

Enum"STARTED""FINISHED"
Response
application/json
{
  "person": {
    "firstName": "John",
    "lastName": "White"
  },
  "breakStatus": "STARTED"
}

Start employees shift.

Request

Start employee shift. If the employee shift has already been started via web browser, mobile app or any other terminal, the request is ignored and the method returns status 200.

Client application should send request immediately when event occurs. If there is any problem with connection or access to API event should be queued in clients side and then sent in order of occurence.

Before you can use this method, please:

  1. Configure 'API Terminal' in Calamari Clockin configuration panel
  2. Make sure API access is enabled


Expect error codes:
  1. INVALID_EMPLOYEE - when invalid employee id provided
  2. INVALID_TIME - when invalid event time provided
  3. API_TERMINAL_NOT_AVAILABLE - no API terminal configured or the employee doesn't have access to this terminal

Security
basicAuth
Bodyapplication/json
personstringrequired

Employee identifier. You can use e-mail or external identifier in format (externalNumber:ABC123)

Example: "john.white@mycompany.com"
timestring(date-time)required

Date and time of event occurence in ISO format.

projectIdinteger(int64)

Project id.

Example: 1
descriptionstring

Description

Example: "Example description"
curl -i -X POST \
  -u <username>:<password> \
  'https://{tenantname}.calamari.io/api/clockin/terminal/v1/clock-in' \
  -H 'Content-Type: application/json' \
  -d '{
    "person": "john.white@mycompany.com",
    "time": "2019-08-24T14:15:22Z",
    "projectId": 1,
    "description": "Example description"
  }'

Responses

successful operation

Bodyapplication/json
personobject(Person)required

Employee description

person.​firstNamestringrequired

Employee first name

Example: "John"
person.​lastNamestringrequired

Employee first name

Example: "White"
shiftStatusstringrequired

Employee shift status after request

Enum"STARTED""FINISHED"
Response
application/json
{
  "person": {
    "firstName": "John",
    "lastName": "White"
  },
  "shiftStatus": "STARTED"
}

Finish employees shift.

Request

Stop employee shift. If employee shift is not started in moment of request the request is ignored.

Client application should send request immediately when event occurs. If there is any problem with connection or access to API event should be queued in clients side and then sent in order of occurence.

Before you can use this method, please:

  1. Configure 'API Terminal' in Calamari Clockin configuration panel
  2. Make sure API access is enabled


Expect error codes:
  1. INVALID_EMPLOYEE - when invalid employee id provided
  2. INVALID_TIME - when invalid event time provided
  3. API_TERMINAL_NOT_AVAILABLE - no API terminal configured or the employee doesn't have access to this terminal

Security
basicAuth
Bodyapplication/json
personstringrequired

Employee identifier. You can use e-mail or external identifier in format (externalNumber:ABC123)

Example: "john.white@mycompany.com"
timestring(date-time)required

Date and time of event occurence in ISO format.

curl -i -X POST \
  -u <username>:<password> \
  'https://{tenantname}.calamari.io/api/clockin/terminal/v1/clock-out' \
  -H 'Content-Type: application/json' \
  -d '{
    "person": "john.white@mycompany.com",
    "time": "2019-08-24T14:15:22Z"
  }'

Responses

successful operation

Bodyapplication/json
personobject(Person)required

Employee description

person.​firstNamestringrequired

Employee first name

Example: "John"
person.​lastNamestringrequired

Employee first name

Example: "White"
shiftStatusstringrequired

Employee shift status after request

Enum"STARTED""FINISHED"
Response
application/json
{
  "person": {
    "firstName": "John",
    "lastName": "White"
  },
  "shiftStatus": "STARTED"
}

Get break types.

Request

Get break types.

Security
basicAuth
curl -i -X POST \
  -u <username>:<password> \
  'https://{tenantname}.calamari.io/api/clockin/terminal/v1/get-break-types'

Responses

successful operation

Bodyapplication/jsonArray [
idinteger(int64)required

Break type id

namestringrequired

Break type name

Example: "Break name"
]
Response
application/json
[
  {
    "id": 0,
    "name": "Break name"
  }
]

Get break types for one person.

Request

Get break types for one person.

Expect error codes:

  1. INVALID_EMPLOYEE - when invalid employee id provided

Security
basicAuth
Bodyapplication/json
personstringrequired

Employee identifier. You can use e-mail or external identifier in format (externalNumber:ABC123)

Example: "john.white@mycompany.com"
curl -i -X POST \
  -u <username>:<password> \
  'https://{tenantname}.calamari.io/api/clockin/terminal/v1/get-break-types-for-person' \
  -H 'Content-Type: application/json' \
  -d '{
    "person": "john.white@mycompany.com"
  }'

Responses

successful operation

Bodyapplication/jsonArray [
idinteger(int64)required

Break type id

namestringrequired

Break type name

Example: "Break name"
]
Response
application/json
[
  {
    "id": 0,
    "name": "Break name"
  }
]

Start or stop employee shift

Request

Method indicates employee go through company's doors. Starts shift if it's not started or stops it otherwise.

Client application should send request immediately when event occurs. If there is any problem with connection or access to API event should be queued in clients side and then sent in order of occurence.

Before you can use this method, please:

  1. Configure 'API Terminal' in Calamari Clockin configuration panel
  2. Make sure API access is enabled


Expect error codes:
  1. INVALID_EMPLOYEE - when invalid employee id provided
  2. INVALID_TIME - when invalid event time provided
  3. API_TERMINAL_NOT_AVAILABLE - no API terminal configured or the employee doesn't have access to this terminal

Security
basicAuth
Bodyapplication/json
personstringrequired

Employee identifier. You can use e-mail or external identifier in format (externalNumber:ABC123)

Example: "john.white@mycompany.com"
timestring(date-time)required

Date and time of event occurence in ISO format.

projectIdinteger(int64)

Project id.

Example: 1
descriptionstring

Description

Example: "Example description"
curl -i -X POST \
  -u <username>:<password> \
  'https://{tenantname}.calamari.io/api/clockin/terminal/v1/punch-clock' \
  -H 'Content-Type: application/json' \
  -d '{
    "person": "john.white@mycompany.com",
    "time": "2019-08-24T14:15:22Z",
    "projectId": 1,
    "description": "Example description"
  }'

Responses

successful operation

Bodyapplication/json
personobject(Person)required

Employee description

person.​firstNamestringrequired

Employee first name

Example: "John"
person.​lastNamestringrequired

Employee first name

Example: "White"
shiftStatusstringrequired

Employee shift status after request

Enum"STARTED""FINISHED"
Response
application/json
{
  "person": {
    "firstName": "John",
    "lastName": "White"
  },
  "shiftStatus": "STARTED"
}

Timesheet entries

Timesheet entries API

Operations

Working Week

Working Week API

Operations

Contract types

Contract Types API

Operations

Employees

Employees API

Operations

Holidays

Holidays API

Operations

Positions

Positions API

Operations

Teams

Teams API

Operations

People

Endpoints related to managing people records.

Operations