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
Languages
Servers
https://{tenantName}.calamari.io/api/

Absence requests

Operations

Create an absence request.

Request

Create an absence request.Expect error codes:

  1. INVALID_ABSENCE_TIME - when invalid absence time provided
  2. INVALID_ABSENCE_ALLOWANCE - when employee absence allowance is not enough
  3. INVALID_HIRE_DATE - when employee hire date is invalid
  4. REQUESTING_RULES_VIOLATED - when requesting rules violated
  5. INVALID_APPROVAL_FLOW - when approval flow is not configured
  6. INVALID_ABSENCE_TYPE - when invalid absence type provided
  7. INVALID_REASON - when invalid reason provided
  8. INVALID_SUBSTITUTE - when invalid substitute provided
  9. INVALID_COMMENT - when invalid comment provided
  10. INVALID_TIME_PART - when invalid time part provided
  11. INVALID_ATTACHMENTS_REQUIRED - when attachments are required

Bodyapplication/json
employeestringrequired

Employee e-mail or login. Absence request will be created for the chosen employee. Chosen employee will be also a creator of request.

Example: "john.white@mycompany.com"
fromPartstringrequired

Time part value for absence start. Allowed values are based on minimal duration of absence request in absence type configuration.

Enum"MORNING""AFTERNOON""END_OF_DAY and hour based(HH:mm)"
Example: "MORNING"
toPartstringrequired

Time part value for absence end. Allowed values are based on minimal duration of absence request in absence type configuration.

Enum"MORNING""AFTERNOON""END_OF_DAY and hour based(HH:mm)"
Example: "END_OF_DAY"
absenceTypeIdstringrequired

Absence type Id

Example: "PTO"
reasonstring[ 0 .. 1024 ] characters

Reason content

Example: "Home office"
substitutestring

Employee e-mail or login

Example: "john.white@mycompany.com"
commentstring[ 0 .. 1024 ] characters

Comment content

Example: "Home office"
dateFromstring(date)
dateTostring(date)
curl -i -X POST \
  -u <username>:<password> \
  https://awesome-company.calamari.io/api/leave/request/v1/create \
  -H 'Content-Type: application/json' \
  -d '{
    "employee": "john.white@mycompany.com",
    "fromPart": "MORNING",
    "toPart": "END_OF_DAY",
    "absenceTypeId": "PTO",
    "reason": "Home office",
    "substitute": "john.white@mycompany.com",
    "comment": "Home office",
    "dateFrom": "2019-08-24",
    "dateTo": "2019-08-24"
  }'

Responses

successful operation

Bodyapplication/json
idinteger(int64)required

Absence request ID

Response
application/json
{
  "id": 0
}

Create comment for chosen request.

Request

Create comment for chosen request.

Expect error codes:

  1. INVALID_EMPLOYEE - when invalid employee id provided
  2. INVALID_CONTENT - when invalid content provided
  3. INVALID_REQUEST - when invalid absence request provided

Bodyapplication/json
creatorstringrequired

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

Example: "john.white@mycompany.com"
contentstringrequired

Comment content

Example: "Home office"
absenceRequestIdinteger(int64)required

Absence request id

Example: 12
curl -i -X POST \
  -u <username>:<password> \
  https://awesome-company.calamari.io/api/leave/request/v1/create-comment \
  -H 'Content-Type: application/json' \
  -d '{
    "creator": "john.white@mycompany.com",
    "content": "Home office",
    "absenceRequestId": 12
  }'

Responses

successful operation

Bodyapplication/jsonArray [
commentatorobject(EmployeeSimpleOut)required
commentator.​firstNamestringrequired

Employee first name

Example: "John"
commentator.​lastNamestringrequired

Employee last name

Example: "Williams"
commentator.​emailstringrequired

Employee email

Example: "john.williams@domain.com"
commentator.​externalIdstring

Employee external identifier

Example: "A12Y"
contentstringrequired

Comment content

absenceRequestIdinteger(int64)required

Absence request ID

]
Response
application/json
[
  {
    "commentator": { … },
    "content": "string",
    "absenceRequestId": 0
  }
]

Find absence requests of employee in dates range.

Request

Find absence requests of employee in dates range.

Expect error codes:

  1. INVALID_EMPLOYEE - when invalid employee id provided
  2. INVALID_DATE_FROM - when invalid date from in filter provided
  3. INVALID_DATE_TO - when invalid date to in filter provided

Bodyapplication/json
employeestringrequired

Employee e-mail or login

Example: "john.white@mycompany.com"
fromstring(date)required

Start date of dates range to search request in ISO format

Example: "2017-01-10"
tostring(date)required

End date of dates range to search request in ISO format

Example: "2017-01-15"
curl -i -X POST \
  -u <username>:<password> \
  https://awesome-company.calamari.io/api/leave/request/v1/find \
  -H 'Content-Type: application/json' \
  -d '{
    "employee": "john.white@mycompany.com",
    "from": "2017-01-10",
    "to": "2017-01-15"
  }'

Responses

successful operation

Bodyapplication/jsonArray [
idinteger(int64)required

Absence request ID

fromstring(date)required

Absence start date in ISO format

Example: "2017-02-20"
tostring(date)required

Absence finish date in ISO format

Example: "2017-02-25"
absenceTypeNamestringrequired

Absence type name

Example: "Annual leave"
absenceTypeIdinteger(int64)required

Absence type ID

absenceCategorystringrequired

Absence category. TIMEOFF - regular time off. WORK - when employee is working but is not in office (eg. 'Remote working day')

Enum"TIMEOFF""WORK"
statusstringrequired

Absence request status

Enum"PENDING""PENDING_CANCELLATION""REJECTED""ACCEPTED""CANCELED""REVOKED"
entitlementAmountnumber(float)required

Entitlement amount

reasonstringrequired

Reason for absence

amountFirstDaynumber(float)required

First day amount

amountLastDaynumber(float)required

Last day amount

entitlementAmountUnitstringrequired

Entitlement amount unit

Enum"DAYS""HOURS"
createdstring(date-time)required

Date and time of absence request creation

updatedstring(date-time)required

Date and time of absence request latest update

fullDayRequestbooleanrequired

Has the absence been requested for the whole day?

startTimestringrequired

Local start date and start time of absence

Example: "2018-06-30T09:00:00.000"
endTimestringrequired

Local end date and end time of absence

Example: "2018-06-30T13:00:00.000"
timeZoneobject(DateTimeZone)required
timeZone.​idstring
timeZone.​fixedboolean
hasAttachmentsbooleanrequired

Absence has attachments

Example: true
]
Response
application/json
[
  {
    "id": 0,
    "from": "2017-02-20",
    "to": "2017-02-25",
    "absenceTypeName": "Annual leave",
    "absenceTypeId": 0,
    "absenceCategory": "TIMEOFF",
    "status": "PENDING",
    "entitlementAmount": 0.1,
    "reason": "string",
    "amountFirstDay": 0.1,
    "amountLastDay": 0.1,
    "entitlementAmountUnit": "DAYS",
    "created": "2019-08-24T14:15:22Z",
    "updated": "2019-08-24T14:15:22Z",
    "fullDayRequest": true,
    "startTime": "2018-06-30T09:00:00.000",
    "endTime": "2018-06-30T13:00:00.000",
    "timeZone": { … },
    "hasAttachments": true
  }
]

Find absence requests with advanced filtering by several parameters.

Request

Find absence requests in dates range.

If you provide more than one value in one filter attribute there is OR relation between them. For instance: if you put in a filter: {employees: ["john@mycompany.com", "kevin@mycompany.com"]} it returns all John's and all Kevin's requests.

When you fill more than one attribute in filter all conditions have to be fulfilled. There is AND relation between attributes. For instance: if you provide in filter {absenceTypes: ["PTO"], teams: ["DevTeam"]} then will be returned PTO requests of employees who are in team DevTeam.

Expect error codes:

  1. INVALID_DATE_FROM - when invalid time in filter provided
  2. INVALID_DATE_TO - when invalid time in filter provided
  3. INVALID_EMPLOYEE - when one of provided employees is invalid
  4. INVALID_ABSENCE_TYPE - when one of provided absence types is invalid
  5. INVALID_TEAM - when one of provided teams is invalid
  6. INVALID_POSITION - when one of provided positions is invalid
  7. INVALID_CONTRACT_TYPE - when one of provided contract types is invalid
  8. INVALID_CREATE_DATE_FROM - when invalid time in filter provided
  9. INVALID_CREATE_DATE_TO - when invalid time in filter provided
  10. INVALID_CREATE_UPDATE_FROM - when invalid time in filter provided
  11. INVALID_CREATE_UPDATE_TO - when invalid time in filter provided

Bodyapplication/json
fromstring(date)required

Start date of dates range to search request in ISO format

Example: "2017-01-10"
tostring(date)required

End date of dates range to search request in ISO format

Example: "2017-01-15"
absenceTypesArray of strings

List of absence types names or identifiers to search. Example: ["Annual Leave", "Remote Work", "Sick Leave"]

teamsArray of strings

List of teams names or identifiers to search. As a result there will be absence requests of employees who are members of at least one of provided teams. Example: ["First Team", "Second Team", "Third Team"]

positionsArray of strings

List of positions names or identifiers to search. As a result there will be absence requests of employees who have one of provided positions. Example: ["Developer", "Support", "Architect"]

contractTypesArray of strings

List of contract types names or identifiers to search. As a result there will be absence requests of employees who have one of contract type. Example: ["firstContract", "secondContract"]

employeesArray of strings

List of employees e-mails or logins. Example: ["john.smith@domain.com", "mark.small@domain.com"]

createdFromstring(date-time)

Filter absence requests by date of creation. As a result there will be absence requests created at the provided moment or later. Please provide the date and time in ISO 8601 format with time zone.

Example: "2017-01-23T08:00:00+01:00"
createdTostring(date-time)

Filter absence requests by date of creation. As a result there will be absence requests created before the provided moment. Please provide the date and time in ISO 8601 format with time zone.

Example: "2017-01-24T00:00:00+01:00"
updatedFromstring(date-time)

Filter absence requests by date of last update. As a result there will be absence requests updated at the provided moment or later. Please provide the date and time in ISO 8601 format with time zone.

Example: "2017-01-23T08:00:00+01:00"
updatedTostring(date-time)

Filter absence requests by date of last update. As a result there will be absence requests updated before the provided moment. Please provide the date and time in ISO 8601 format with time zone.

Example: "2017-01-24T00:00:00+01:00"
absenceStatusesArray of strings

Filter absence requests by absence statuses. As a result there will be absence requests with chosen statuses. By default return all absence requests. Allowed values: ["PENDING", "PENDING_CANCELLATION", "REJECTED", "APPROVED", "CANCELED", "REVOKED"]

Example: "[PENDING, APPROVED]"
curl -i -X POST \
  -u <username>:<password> \
  https://awesome-company.calamari.io/api/leave/request/v1/find-advanced \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "2017-01-10",
    "to": "2017-01-15",
    "absenceTypes": [
      "string"
    ],
    "teams": [
      "string"
    ],
    "positions": [
      "string"
    ],
    "contractTypes": [
      "string"
    ],
    "employees": [
      "string"
    ],
    "createdFrom": "2017-01-23T08:00:00+01:00",
    "createdTo": "2017-01-24T00:00:00+01:00",
    "updatedFrom": "2017-01-23T08:00:00+01:00",
    "updatedTo": "2017-01-24T00:00:00+01:00",
    "absenceStatuses": "[PENDING, APPROVED]"
  }'

Responses

successful operation

Bodyapplication/jsonArray [
idinteger(int64)required

Absence request ID

fromstring(date)required

Absence start date in ISO format

Example: "2017-02-20"
tostring(date)required

Absence finish date in ISO format

Example: "2017-02-25"
absenceTypeNamestringrequired

Absence type name

Example: "Annual leave"
absenceTypeIdinteger(int64)required

Absence type ID

absenceCategorystringrequired

Absence category. TIMEOFF - regular time off. WORK - when employee is working but is not in office (eg. 'Remote working day')

Enum"TIMEOFF""WORK"
statusstringrequired

Absence request status

Enum"PENDING""PENDING_CANCELLATION""REJECTED""ACCEPTED""CANCELED""REVOKED"
entitlementAmountnumber(float)required

Entitlement amount

reasonstringrequired

Reason for absence

amountFirstDaynumber(float)required

First day amount

amountLastDaynumber(float)required

Last day amount

entitlementAmountUnitstringrequired

Entitlement amount unit

Enum"DAYS""HOURS"
createdstring(date-time)required

Date and time of absence request creation

updatedstring(date-time)required

Date and time of absence request latest update

fullDayRequestbooleanrequired

Has the absence been requested for the whole day?

startTimestringrequired

Local start date and start time of absence

Example: "2018-06-30T09:00:00.000"
endTimestringrequired

Local end date and end time of absence

Example: "2018-06-30T13:00:00.000"
timeZoneobject(DateTimeZone)required
timeZone.​idstring
timeZone.​fixedboolean
hasAttachmentsbooleanrequired

Absence has attachments

Example: true
employeeEmailstring

Employee email

Example: "john.white@mycompany.com"
substituteEmailstring

Substitute email. Has null value if employee does not have substitute

Example: "john.black@mycompany.com"
]
Response
application/json
[
  {
    "id": 0,
    "from": "2017-02-20",
    "to": "2017-02-25",
    "absenceTypeName": "Annual leave",
    "absenceTypeId": 0,
    "absenceCategory": "TIMEOFF",
    "status": "PENDING",
    "entitlementAmount": 0.1,
    "reason": "string",
    "amountFirstDay": 0.1,
    "amountLastDay": 0.1,
    "entitlementAmountUnit": "DAYS",
    "created": "2019-08-24T14:15:22Z",
    "updated": "2019-08-24T14:15:22Z",
    "fullDayRequest": true,
    "startTime": "2018-06-30T09:00:00.000",
    "endTime": "2018-06-30T13:00:00.000",
    "timeZone": { … },
    "hasAttachments": true,
    "employeeEmail": "john.white@mycompany.com",
    "substituteEmail": "john.black@mycompany.com"
  }
]

Remove chosen absence request.

Request

Remove chosen absence request.

Expect error codes:

  1. INVALID_REQUEST - when invalid absence request provided

Bodyapplication/json
idinteger(int64)required

Absence request ID

curl -i -X POST \
  -u <username>:<password> \
  https://awesome-company.calamari.io/api/leave/request/v1/remove \
  -H 'Content-Type: application/json' \
  -d '{
    "id": 0
  }'

Responses

Invalid input. Reason and description is returned in json response.

Bodyapplication/json
messagestring

Human readable error explanation.

Example: "Api error"
codestring

Error code.

Example: "INVALID_JSON_PAYLOAD"
fieldstring

Which field of payload object caused error. NULL when error is not related to particular field

Example: "field"
Response
application/json
{
  "message": "Api error",
  "code": "INVALID_JSON_PAYLOAD",
  "field": "field"
}

Absence type

Operations

Contract types

Operations

Current shift status

Operations

Employees

Operations

Holidays

Operations

Positions

Operations

Projects

Operations

Shifts and breaks

Operations

Teams

Operations

Timesheet entries

Operations

Working Week

Operations

People (Beta)

Endpoints related to managing people records.

Operations