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

Absence type

Operations

Contract types

Operations

Current shift status

Operations

Employees

Operations

Mark employee as archived.

Request

Mark employee as archived.

Bodyapplication/json
employeestringrequired

Employee e-mail or login

Example: "john.white@mycompany.com"
curl -i -X POST \
  -u <username>:<password> \
  https://awesome-company.calamari.io/api/employees/v1/archive \
  -H 'Content-Type: application/json' \
  -d '{
    "employee": "john.white@mycompany.com"
  }'

Responses

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

Body*/*
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"

Create employee.

Request

Create employee.

Expect error codes:

  1. INVALID_FIRST_NAME - when first name is not provided or is invalid
  2. INVALID_LAST_NAME - when last name is not provided or is invalid
  3. INVALID_EMAIL - when email name is not provided or is invalid
  4. INVALID_WORKING_WEEK - when working week is not provided or is invalid
  5. INVALID_ACCEPTANCE_FLOW - when acceptance flow is not provided or is invalid
  6. INVALID_HOLIDAYS_CALENDAR - when holidays calendar is not provided or is invalid
  7. INVALID_SEX - when sex is not provided or is invalid
  8. INVALID_MARTIAL_STATUS - when martial status is not provided or is invalid
  9. INVALID_WORKING_WEEK - when working week is not provided or is invalid
  10. INVALID_TEAM - when one of provided teams is invalid
  11. INVALID_POSITION - when one of provided positions is invalid
  12. INVALID_CONTRACT_TYPE - when contract type is invalid
  13. INVALID_DIRECT_MANAGER - when invalid direct manager id is provided
  14. LICENCE_MAX_USERS_EXCEEDED - when you reach the maximum number of seats within your subscription

Bodyapplication/json
firstNamestringrequired

Employee first name

Example: "John"
lastNamestringrequired

Employee last name

Example: "Williams"
emailstringrequired

Employee email

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

Working week name or identifier

Example: "Working week name"
approvalFlowstringrequired

Approval flow name or identifier

Example: "Flow name"
positionstring

Position name or identifier.

Example: "Developer"
teamsArray of strings

List of teams names or identifiers. Example: ["Developers Team"]

holidaysCalendarstringrequired

Holidays calendar name or identifier

Example: "Primary calendar"
sexstringrequired

Sex

Enum"MALE""FEMALE""OTHER""NOT_SET"
maritalStatusstringrequired

Martial status

Enum"SINGLE""MARRIED""WIDOWED""SEPARATED""DIVORCED""NOT_SET"
adminbooleanrequired

Is the employee is an admin?

contractTypestring

Contract type name or identifier

Example: "Contract type"
externalNumberstring

External number

Example: "A12Y"
directManagerstring

Direct manager e-mail or login

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

Birth date in ISO format

Example: "2017-02-20"
hireDatestring(date)

Hire date in ISO format

Example: "2017-02-20"
businessPhonestring

Business phone

Example: "876234928"
homePhonestring

Home phone

Example: "283018271"
personalEmailstring

Personal email

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

Address street

Example: "Buckfast Street"
addressNumberstring

Address building/flat number

Example: "2/20"
addressCitystring

Address city

Example: "Warsaw"
addressPostalCodestring

Address postal code

Example: "12-333"
addressProvinceStatestring

Address province/state

Example: "Main Province"
addressCountrystring

Address country

Example: "Poland"
emergencyContactNamestring

Emergency contact name

Example: "Contact name"
emergencyContactRelationshipstring

Emergency contact relationship

Example: "Contact relationship"
emergencyContactPhonestring

Emergency contact phone

Example: "198263098"
probationEndDatestring(date)

Probation end date in ISO format

Example: "2017-02-20"
plannedFiringstring(date)

Planned firing in ISO format

Example: "2017-02-20"
seniorityBeforeHireYearsinteger(int32)

Seniority before hire - years

seniorityBeforeHireMonthsinteger(int32)

Seniority before hire - months

childrenCountinteger(int32)

Number of children

youngestChildBirthDatestring(date)

The youngest child birth date in ISO format

Example: "2017-02-20"
customNotestring

Custom note

Example: "Optional custom note about employee"
curl -i -X POST \
  -u <username>:<password> \
  https://awesome-company.calamari.io/api/employees/v1/create \
  -H 'Content-Type: application/json' \
  -d '{
    "firstName": "John",
    "lastName": "Williams",
    "email": "john.white@mycompany.com",
    "workingWeek": "Working week name",
    "approvalFlow": "Flow name",
    "position": "Developer",
    "teams": [
      "string"
    ],
    "holidaysCalendar": "Primary calendar",
    "sex": "MALE",
    "maritalStatus": "SINGLE",
    "admin": true,
    "contractType": "Contract type",
    "externalNumber": "A12Y",
    "directManager": "john.white@mycompany.com",
    "birthDate": "2017-02-20",
    "hireDate": "2017-02-20",
    "businessPhone": "876234928",
    "homePhone": "283018271",
    "personalEmail": "john.white@mycompany.com",
    "addressStreet": "Buckfast Street",
    "addressNumber": "2/20",
    "addressCity": "Warsaw",
    "addressPostalCode": "12-333",
    "addressProvinceState": "Main Province",
    "addressCountry": "Poland",
    "emergencyContactName": "Contact name",
    "emergencyContactRelationship": "Contact relationship",
    "emergencyContactPhone": "198263098",
    "probationEndDate": "2017-02-20",
    "plannedFiring": "2017-02-20",
    "seniorityBeforeHireYears": 0,
    "seniorityBeforeHireMonths": 0,
    "childrenCount": 0,
    "youngestChildBirthDate": "2017-02-20",
    "customNote": "Optional custom note about employee"
  }'

Responses

successful operation

Bodyapplication/json
idinteger(int64)required

Id of create employee

Response
application/json
{
  "id": 0
}

Edit employee.

Request

Edit employee.

Expect error codes:

  1. INVALID_EMPLOYEE - when invalid employee id provided
  2. INVALID_FIRST_NAME - when first name is not provided or is invalid
  3. INVALID_LAST_NAME - when last name is not provided or is invalid
  4. INVALID_EMAIL - when email is not provided or is invalid
  5. INVALID_WORKING_WEEK - when provided working week is invalid
  6. INVALID_ACCEPTANCE_FLOW - when provided acceptance flow is is invalid
  7. INVALID_HOLIDAYS_CALENDAR - when provided holidays calendar is invalid
  8. INVALID_SEX - when provided sex is invalid
  9. INVALID_MARITAL_STATUS - when provided marital status is invalid
  10. INVALID_WORKING_WEEK - when provided working week is invalid
  11. INVALID_TEAM - when one of provided teams is invalid
  12. INVALID_POSITION - when one of provided positions is invalid
  13. INVALID_CONTRACT_TYPE - when contract type is invalid
  14. INVALID_PERSONAL_EMAIL - when personal email is invalid
  15. INVALID_DIRECT_MANAGER - when invalid direct manager is provided

Bodyapplication/json
employeestringrequired

Employee e-mail or login

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

Employee first name to update.

Example: "John"
lastNamestring

Employee last name to update.

Example: "Williams"
emailstring

Employee email to update.

Example: "john.williams@domain.com"
workingWeekstring

Working week name or identifier to update.

Example: "Working week name"
approvalFlowstring

Approval flow name or identifier to update.

Example: "Main Approval Flow"
positionstring

Position name or identifier to update.

Example: "Developer"
teamsArray of strings

List of teams names or identifiers to update.

Example: ["4","10"]
holidaysCalendarstring

Holidays calendar name or identifier to update.

Example: "Primary calendar"
sexstring

Sex

maritalStatusstring

Marital status to update

adminboolean

Is the employee is an admin?

contractTypestring

Contract type name or identifier.

Example: "Full time"
externalNumberstring

External number.

Example: "A27D"
directManagerstring

Direct manager e-mail or login.

Example: "mark.smith@domain.com"
birthDatestring

Birth date to update in ISO format

Example: "2017-02-20"
hireDatestring

Hire date to update in ISO format

Example: "2017-02-20"
businessPhonestring

Business phone to update.

Example: "982027621"
homePhonestring

Home phone to update.

Example: "982027621"
personalEmailstring

Personal email to update. Example:

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

Address street to update

Example: "New Street"
addressNumberstring

Address building/flat number to update

Example: "2/12"
addressCitystring

Address city to update

Example: "Warsaw"
addressPostalCodestring

Address postal code to update

Example: "28-283"
addressProvinceStatestring

Address province/state to update

Example: "Main province"
addressCountrystring

Address country to update

Example: "Poland"
emergencyContactNamestring

Emergency contact name to update

Example: "Contact name"
emergencyContactRelationshipstring

Emergency contact relationship to update

Example: "Contact relationship"
emergencyContactPhonestring

Emergency contact phone to update

Example: "928196340"
probationEndDatestring

Probation end date to update in ISO format

Example: "2017-02-20"
plannedFiringstring

Planned firing to update in ISO format

Example: "2017-02-20"
seniorityBeforeHireYearsinteger(int32)

Seniority before hire to update- years

seniorityBeforeHireMonthsinteger(int32)

Seniority before hire to update- months

childrenCountinteger(int32)

Number of children to update

youngestChildBirthDatestring

The youngest child birth date to update in ISO format

Example: "2017-02-20"
customNotestring

Custom note to update

Example: "Custom note about employee"
curl -i -X POST \
  -u <username>:<password> \
  https://awesome-company.calamari.io/api/employees/v1/edit \
  -H 'Content-Type: application/json' \
  -d '{
    "employee": "john.white@mycompany.com",
    "firstName": "John",
    "lastName": "Williams",
    "email": "john.williams@domain.com",
    "workingWeek": "Working week name",
    "approvalFlow": "Main Approval Flow",
    "position": "Developer",
    "teams": [
      "4",
      "10"
    ],
    "holidaysCalendar": "Primary calendar",
    "sex": "string",
    "maritalStatus": "string",
    "admin": true,
    "contractType": "Full time",
    "externalNumber": "A27D",
    "directManager": "mark.smith@domain.com",
    "birthDate": "2017-02-20",
    "hireDate": "2017-02-20",
    "businessPhone": "982027621",
    "homePhone": "982027621",
    "personalEmail": "john.white@mycompany.com",
    "addressStreet": "New Street",
    "addressNumber": "2/12",
    "addressCity": "Warsaw",
    "addressPostalCode": "28-283",
    "addressProvinceState": "Main province",
    "addressCountry": "Poland",
    "emergencyContactName": "Contact name",
    "emergencyContactRelationship": "Contact relationship",
    "emergencyContactPhone": "928196340",
    "probationEndDate": "2017-02-20",
    "plannedFiring": "2017-02-20",
    "seniorityBeforeHireYears": 0,
    "seniorityBeforeHireMonths": 0,
    "childrenCount": 0,
    "youngestChildBirthDate": "2017-02-20",
    "customNote": "Custom note about employee"
  }'

Responses

successful operation

Bodyapplication/json
idinteger(int64)required

Id of create employee

Response
application/json
{
  "id": 0
}

Invite employee.

Request

Invite employee

Bodyapplication/json
employeestringrequired

Employee e-mail or login

Example: "john.white@mycompany.com"
curl -i -X POST \
  -u <username>:<password> \
  https://awesome-company.calamari.io/api/employees/v1/invite \
  -H 'Content-Type: application/json' \
  -d '{
    "employee": "john.white@mycompany.com"
  }'

Responses

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

Body*/*
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"

Get all non archived employees.

Request

If you want to find archived employees, please use search method.

Bodyapplication/json
pageinteger(int32)

Page number

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

Responses

successful operation

Bodyapplication/json
employeesArray of objects(EmployeeFullOut)required

List of employees

employees[].​idinteger(int64)required

Employee id number

employees[].​firstNamestringrequired

Employee first name

Example: "John"
employees[].​lastNamestringrequired

Employee last name

Example: "Smith"
employees[].​emailstringrequired

Employee email

Example: "john.smith@domain.com"
employees[].​externalNumberstringrequired

External employee number

Example: "AYU23"
employees[].​workingWeekobject(SimpleWorkingWeek)required
employees[].​workingWeek.​idinteger(int64)required

Working week id

employees[].​workingWeek.​namestringrequired

Working week name

Example: "Full time"
employees[].​approvalFlowobject(SimpleAcceptanceFlow)required
employees[].​approvalFlow.​idinteger(int64)required

Approval flow id

employees[].​approvalFlow.​namestringrequired

Approval flow name

Example: "Default Approval Flow"
employees[].​positionobject(SimplePosition)required
employees[].​position.​idinteger(int64)required

Position id

employees[].​position.​namestringrequired

Position name

Example: "Developer"
employees[].​teamsArray of objects(SimpleTeam)required

Teams

employees[].​teams[].​idinteger(int64)required

Team id

employees[].​teams[].​namestringrequired

Team name

Example: "Main Team"
employees[].​adminbooleanrequired

Is the employee is an admin?

employees[].​contractTypeobject(SimpleContractType)required
employees[].​contractType.​idinteger(int64)required

Contract type id

employees[].​contractType.​namestringrequired

Contract type name

Example: "Contract type"
employees[].​languagestringrequired

Employee language

Example: "EN"
employees[].​timezonestringrequired

Employee timezone

Example: "Europe/Warsaw"
employees[].​directManagerobject(SimpleEmployee)required
employees[].​directManager.​idinteger(int64)required

Employee id

employees[].​directManager.​emailstringrequired

Employee email

Example: "john.white@domain.com"
employees[].​birthDatestring(date)required

Birth date

Example: "2017-02-20"
employees[].​hireDatestring(date)required

Hire date

Example: "2017-02-20"
employees[].​businessPhonestringrequired

Business phone

Example: "827032162"
employees[].​homePhonestringrequired

Home phone

Example: "826021237"
employees[].​personalEmailstringrequired

Personal email

Example: "john.smith@personalDomain.com"
employees[].​addressStreetstringrequired

Address street

Example: "Small Street"
employees[].​addressNumberstringrequired

Address building/flat number

Example: "2/12"
employees[].​addressCitystringrequired

Address city

Example: "Warsaw"
employees[].​addressPostalCodestringrequired

Address postal code

Example: "15-322"
employees[].​addressProvinceStatestringrequired

Address province/state.

Example: "Main province"
employees[].​addressCountrystringrequired

Address country

Example: "Poland"
employees[].​emergencyContactNamestringrequired

Emergency contact name

Example: "Contact name"
employees[].​emergencyContactRelationshipstringrequired

Emergency contact relationship

Example: "Contact relationship"
employees[].​emergencyContactPhonestringrequired

Emergency contact phone

Example: "820321876"
employees[].​holidaysCalendarobject(GetHolidayCalendarOut)required
employees[].​holidaysCalendar.​idinteger(int64)required

Holiday calendar id

employees[].​holidaysCalendar.​namestringrequired

Holiday calendar name

Example: "Primary calendar"
employees[].​maritalStatusstringrequired

Martial status

Enum"SINGLE""MARRIED""WIDOWED""SEPARATED""DIVORCED""NOT_SET"
employees[].​probationEndDatestring(date)required

Probation end date

Example: "2017-02-20"
employees[].​plannedFiringstring(date)required

Planned firing

Example: "2017-02-20"
employees[].​seniorityBeforeHireYearsinteger(int32)required

Seniority before hire - years

employees[].​seniorityBeforeHireMonthsinteger(int32)required

Seniority before hire - months

employees[].​childrenCountinteger(int32)required

Number of children

employees[].​youngestChildBirthDatestring(date)required

The youngest child birth date

Example: "2017-02-20"
employees[].​customNotestringrequired

Custom note

Example: "Optional custom note"
employees[].​sexstringrequired

Sex

Enum"MALE""FEMALE""OTHER""NOT_SET"
employees[].​archivedbooleanrequired

Is employee archived?

currentPageinteger(int32)required

Current page

totalPagesinteger(int32)required

Total pages

Response
application/json
{
  "employees": [
    { … }
  ],
  "currentPage": 0,
  "totalPages": 0
}

Get all employees.

Request

Get all employees.

Bodyapplication/json
employeestring

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

Example: "john.white@mycompany.com"
contractTypesArray of strings

Contract type name or identifier

positionsArray of strings

List of Position names or identifiers.

teamsArray of strings

List of teams names or identifiers

withArchivedboolean

Should return also archived employees?

curl -i -X POST \
  -u <username>:<password> \
  https://awesome-company.calamari.io/api/employees/v1/search \
  -H 'Content-Type: application/json' \
  -d '{
    "employee": "john.white@mycompany.com",
    "contractTypes": [
      "string"
    ],
    "positions": [
      "string"
    ],
    "teams": [
      "string"
    ],
    "withArchived": true
  }'

Responses

successful operation

Bodyapplication/json
employeesArray of objects(EmployeeFullOut)required

List of employees

employees[].​idinteger(int64)required

Employee id number

employees[].​firstNamestringrequired

Employee first name

Example: "John"
employees[].​lastNamestringrequired

Employee last name

Example: "Smith"
employees[].​emailstringrequired

Employee email

Example: "john.smith@domain.com"
employees[].​externalNumberstringrequired

External employee number

Example: "AYU23"
employees[].​workingWeekobject(SimpleWorkingWeek)required
employees[].​workingWeek.​idinteger(int64)required

Working week id

employees[].​workingWeek.​namestringrequired

Working week name

Example: "Full time"
employees[].​approvalFlowobject(SimpleAcceptanceFlow)required
employees[].​approvalFlow.​idinteger(int64)required

Approval flow id

employees[].​approvalFlow.​namestringrequired

Approval flow name

Example: "Default Approval Flow"
employees[].​positionobject(SimplePosition)required
employees[].​position.​idinteger(int64)required

Position id

employees[].​position.​namestringrequired

Position name

Example: "Developer"
employees[].​teamsArray of objects(SimpleTeam)required

Teams

employees[].​teams[].​idinteger(int64)required

Team id

employees[].​teams[].​namestringrequired

Team name

Example: "Main Team"
employees[].​adminbooleanrequired

Is the employee is an admin?

employees[].​contractTypeobject(SimpleContractType)required
employees[].​contractType.​idinteger(int64)required

Contract type id

employees[].​contractType.​namestringrequired

Contract type name

Example: "Contract type"
employees[].​languagestringrequired

Employee language

Example: "EN"
employees[].​timezonestringrequired

Employee timezone

Example: "Europe/Warsaw"
employees[].​directManagerobject(SimpleEmployee)required
employees[].​directManager.​idinteger(int64)required

Employee id

employees[].​directManager.​emailstringrequired

Employee email

Example: "john.white@domain.com"
employees[].​birthDatestring(date)required

Birth date

Example: "2017-02-20"
employees[].​hireDatestring(date)required

Hire date

Example: "2017-02-20"
employees[].​businessPhonestringrequired

Business phone

Example: "827032162"
employees[].​homePhonestringrequired

Home phone

Example: "826021237"
employees[].​personalEmailstringrequired

Personal email

Example: "john.smith@personalDomain.com"
employees[].​addressStreetstringrequired

Address street

Example: "Small Street"
employees[].​addressNumberstringrequired

Address building/flat number

Example: "2/12"
employees[].​addressCitystringrequired

Address city

Example: "Warsaw"
employees[].​addressPostalCodestringrequired

Address postal code

Example: "15-322"
employees[].​addressProvinceStatestringrequired

Address province/state.

Example: "Main province"
employees[].​addressCountrystringrequired

Address country

Example: "Poland"
employees[].​emergencyContactNamestringrequired

Emergency contact name

Example: "Contact name"
employees[].​emergencyContactRelationshipstringrequired

Emergency contact relationship

Example: "Contact relationship"
employees[].​emergencyContactPhonestringrequired

Emergency contact phone

Example: "820321876"
employees[].​holidaysCalendarobject(GetHolidayCalendarOut)required
employees[].​holidaysCalendar.​idinteger(int64)required

Holiday calendar id

employees[].​holidaysCalendar.​namestringrequired

Holiday calendar name

Example: "Primary calendar"
employees[].​maritalStatusstringrequired

Martial status

Enum"SINGLE""MARRIED""WIDOWED""SEPARATED""DIVORCED""NOT_SET"
employees[].​probationEndDatestring(date)required

Probation end date

Example: "2017-02-20"
employees[].​plannedFiringstring(date)required

Planned firing

Example: "2017-02-20"
employees[].​seniorityBeforeHireYearsinteger(int32)required

Seniority before hire - years

employees[].​seniorityBeforeHireMonthsinteger(int32)required

Seniority before hire - months

employees[].​childrenCountinteger(int32)required

Number of children

employees[].​youngestChildBirthDatestring(date)required

The youngest child birth date

Example: "2017-02-20"
employees[].​customNotestringrequired

Custom note

Example: "Optional custom note"
employees[].​sexstringrequired

Sex

Enum"MALE""FEMALE""OTHER""NOT_SET"
employees[].​archivedbooleanrequired

Is employee archived?

currentPageinteger(int32)required

Current page

totalPagesinteger(int32)required

Total pages

Response
application/json
{
  "employees": [
    { … }
  ],
  "currentPage": 0,
  "totalPages": 0
}

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