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.io

Calamari Team developers@calamari.io

Servers

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

Absence requests

Operations

Absence type

Operations

Contract types

Operations

Current shift status

Operations

Employees

Operations

Holidays

Operations

Positions

Operations

Projects

Operations

Shifts and breaks

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:

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

Expect error codes:

INVALID_EMPLOYEE - when invalid employee id provided
INVALID_TIME - when invalid event time provided
INVALID_BREAK_TYPE - when invalid break type id provided
API_TERMINAL_NOT_AVAILABLE - no API terminal configured or the employee doesn't have access to this terminal

Bodyapplication/json

personstringrequired

Employee e-mail or login

Example: "john.white@mycompany.com"

timestringrequired

Date and time of event occurence in ISO format.

Example: "2015-11-10T08:30:00"

breakTypeinteger(int64)required

ID break type

Example: 1

curl -i -X POST \
  -u <username>:<password> \
  https://awesome-company.calamari.io/api/clockin/terminal/v1/break-start \
  -H 'Content-Type: application/json' \
  -d '{
    "person": "john.white@mycompany.com",
    "time": "2015-11-10T08:30:00",
    "breakType": 1
  }'

Responses

successful operation

Bodyapplication/json

personobject(Person)required

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:

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

Expect error codes:

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

Bodyapplication/json

personstringrequired

Employee e-mail or login

Example: "john.white@mycompany.com"

timestringrequired

Date and time of event occurence in ISO format.

Example: "2015-11-10T08:30:00"

breakTypeinteger(int64)required

ID break type

Example: 1

curl -i -X POST \
  -u <username>:<password> \
  https://awesome-company.calamari.io/api/clockin/terminal/v1/break-stop \
  -H 'Content-Type: application/json' \
  -d '{
    "person": "john.white@mycompany.com",
    "time": "2015-11-10T08:30:00",
    "breakType": 1
  }'

Responses

successful operation

Bodyapplication/json

personobject(Person)required

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:

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

Expect error codes:

INVALID_EMPLOYEE - when invalid employee id provided
INVALID_TIME - when invalid event time provided
API_TERMINAL_NOT_AVAILABLE - no API terminal configured or the employee doesn't have access to this terminal

Bodyapplication/json

personstringrequired

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

Example: "john.white@mycompany.com"

timestringrequired

Date and time of event occurence in ISO format.

Example: "2015-11-10T08:30:00"

projectIdinteger(int64)

Project id.

Example: 1

descriptionstring

Description

Example: "Example description"

curl -i -X POST \
  -u <username>:<password> \
  https://awesome-company.calamari.io/api/clockin/terminal/v1/clock-in \
  -H 'Content-Type: application/json' \
  -d '{
    "person": "john.white@mycompany.com",
    "time": "2015-11-10T08:30:00",
    "projectId": 1,
    "description": "Example description"
  }'

Responses

successful operation

Bodyapplication/json

personobject(Person)required

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:

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

Expect error codes:

INVALID_EMPLOYEE - when invalid employee id provided
INVALID_TIME - when invalid event time provided
API_TERMINAL_NOT_AVAILABLE - no API terminal configured or the employee doesn't have access to this terminal

Bodyapplication/json

personstringrequired

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

Example: "john.white@mycompany.com"

timestringrequired

Date and time of event occurence in ISO format.

Example: "2015-11-10T08:30:00"

curl -i -X POST \
  -u <username>:<password> \
  https://awesome-company.calamari.io/api/clockin/terminal/v1/clock-out \
  -H 'Content-Type: application/json' \
  -d '{
    "person": "john.white@mycompany.com",
    "time": "2015-11-10T08:30:00"
  }'

Responses

successful operation

Bodyapplication/json

personobject(Person)required

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.

curl -i -X POST \
  -u <username>:<password> \
  https://awesome-company.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:

INVALID_EMPLOYEE - when invalid employee id provided

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://awesome-company.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:

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

Expect error codes:

INVALID_EMPLOYEE - when invalid employee id provided
INVALID_TIME - when invalid event time provided
API_TERMINAL_NOT_AVAILABLE - no API terminal configured or the employee doesn't have access to this terminal

Bodyapplication/json

personstringrequired

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

Example: "john.white@mycompany.com"

timestringrequired

Date and time of event occurence in ISO format.

Example: "2015-11-10T08:30:00"

projectIdinteger(int64)

Project id.

Example: 1

descriptionstring

Description

Example: "Example description"

curl -i -X POST \
  -u <username>:<password> \
  https://awesome-company.calamari.io/api/clockin/terminal/v1/punch-clock \
  -H 'Content-Type: application/json' \
  -d '{
    "person": "john.white@mycompany.com",
    "time": "2015-11-10T08:30:00",
    "projectId": 1,
    "description": "Example description"
  }'

Responses

successful operation

Bodyapplication/json

personobject(Person)required

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"
}

Teams

Operations

Timesheet entries

Operations

Working Week

Operations

People (Beta)

Endpoints related to managing people records.

Operations

Calamari Public API (v1)

Absence requests

Absence type

Contract types

Current shift status

Employees

Holidays

Positions

Projects

Shifts and breaks

Start employee break.

Request

Responses

Was this helpful?

Stop employee break.

Request

Responses

Was this helpful?

Start employees shift.

Request

Responses

Was this helpful?

Finish employees shift.

Request

Responses

Was this helpful?

Get break types.

Request

Responses

Was this helpful?

Get break types for one person.

Request

Responses

Was this helpful?

Start or stop employee shift

Request

Responses

Was this helpful?

Teams

Timesheet entries

Working Week

People (Beta)