Skip to content

Calamari Public API (v1)

API for Calamari, your HR tool

Languages
Servers
https://{tenantName}.calamari.io/api
Operations

Absence Requests API

Operations

Current Shift Status API

Operations
Operations

Shifts and Breaks API

Operations

Timesheet entries API

Operations
Operations
Operations
Operations
Operations
Operations
Operations

Endpoints related to managing people records.

Operations

Request

You can fetch a list of all people. You can optionally specify a limit to control the number of results returned, and an offset to skip a specified number of entries from the start.

Security
basicAuth
Query
contractTypesArray of strings(uuid)

Comma-separated list of contract type UUIDs used to filter people by contract types.

Example: contractTypes=41d2e841-7f1f-4545-be09-8a17606f0228,31d2e841-7f1f-4545-be09-8a17606f0228
positionsArray of integers

Comma-separated list of position IDs used to filter people by positions.

Example: positions=1,2,3,4
teamsArray of integers

Comma-separated list of team IDs used to filter people by team membership.

Example: teams=1,2,3,7,8
archivedboolean

Filter by archived status. Set to true to return only archived people, or false to return only active people.

Example: archived=true
projectionstring

Defines the projection strategy used for the response.

  • FULL (default): returns all available fields.
  • BASIC: returns a minimal subset of fields.
  • CUSTOM: returns only the fields specified in the fields parameter. When CUSTOM is used, the fields parameter is required.

Note: Regardless of projection type, the response always includes id, legacyId and archived fields.

Enum"FULL""BASIC""CUSTOM"
Example: projection=CUSTOM
fieldsstring

Comma-separated list of field names to include in the response. Only applicable when projection=CUSTOM.

Note: Regardless of the list, the fields id, legacyId and archived are always returned.

Example: fields=firstName,lastName,email
limitinteger>= 1

The maximum number of items to return. Must be greater than or equal to 1. Default is 100.

Default 100
Example: limit=50
offsetinteger>= 0

The number of items to skip before returning the results. Must be greater than or equal to 0. Default is 0.

Default 0
Example: offset=10
sortArray of strings

Sorting criteria in the format field,ASC or field,DESC. Can be repeated to apply multi-level sorting.

Example: sort=id,DESC&sort=name,ASC
nullOrderingstring

Specifies how NULL values are sorted. Options: NULLS_FIRST or NULLS_LAST. Default is NULLS_FIRST.

Default "NULLS_FIRST"
Enum"NULLS_FIRST""NULLS_LAST"
Example: nullOrdering=NULLS_LAST
curl -i -X GET \
  -u <username>:<password> \
  'https://{tenantname}.calamari.io/api/people/v2?contractTypes=41d2e841-7f1f-4545-be09-8a17606f0228%2C31d2e841-7f1f-4545-be09-8a17606f0228&positions=1%2C2%2C3%2C4&teams=1%2C2%2C3%2C7%2C8&archived=true&projection=CUSTOM&fields=firstName%2ClastName%2Cemail&limit=50&offset=10&sort=id%2CDESC%2Cname%2CASC&nullOrdering=NULLS_LAST'

Responses

The request was successful. A list of people matching the specified criteria is returned.

Bodyapplication/json
dataArray of objects(SinglePersonResponseSchema)required

Collection of items.

data[].​idstring(uuid)required

Unique identifier (UUID format).

Example: "52601c08-b7e5-4c60-a57f-2b1d74942543"
data[].​legacyIdinteger(int64)

Legacy numerical identifier.

Example: 1337
data[].​firstNamestring or null

The first name of the person.

Any of:

The first name of the person.

string
data[].​middleNamestring or null

The middle name of the person.

Any of:

The middle name of the person.

string
data[].​lastNamestring or null

The last name of the person.

Any of:

The last name of the person.

string
data[].​emailstring or null

Primary business email address.

Any of:

Primary business email address.

string(email)
data[].​rolesArray of strings or null

System roles assigned to this person.

Any of:

System roles assigned to this person.

data[].​archivedboolean or null
data[].​archivedDatestring or null

Archiving timestamp in ISO-8601 format.

Any of:

Archiving timestamp in ISO-8601 format.

string(date-time)
data[].​positionobject or null

Current position held by the person.

Any of:

Current position held by the person.

data[].​birthdatestring or null
Any of:
string(date)
data[].​businessContactobject or null
Any of:
data[].​personalContactobject or null
Any of:
data[].​addressobject or null
Any of:
data[].​sexstring or null(sex-optional-schema)

Sex.

Enum"MALE""FEMALE""OTHER"null
data[].​maritalStatusstring or null(martial-status-optional-schema)

Martial status.

Enum"SINGLE""MARRIED""WIDOWED""SEPARATED""DIVORCED""DOMESTIC_PARTNERSHIP""COMMON_LAW""OTHER""NOT_SET"null
data[].​hireDatestring or null
Any of:
string(date)
data[].​probationEndDatestring or null
Any of:
string(date)
data[].​terminationDatestring or null
Any of:
string(date)
data[].​seniorityBeforeHireinteger or null
Any of:
integer
data[].​externalNumberstring or null
Any of:
string
data[].​symfoniaGuidstring or null
Any of:
string(uuid)
data[].​customNotestring or null
Any of:
string
data[].​emergencyContactobject or null
Any of:
data[].​approvalFlowobject or null
Any of:
data[].​contractTypeobject or null
Any of:
data[].​holidaysCalendarobject or null
Any of:
data[].​workScheduleobject or null
Any of:
data[].​teamsArray of objects or null
Any of:
data[].​directManagerobject or null
Any of:
data[].​bankAccountNumberstring or null
Any of:
string
data[].​shirtSizestring or null
Any of:
string
data[].​contractorDetailsobject or null
Any of:
data[].​childrenArray of objects or null
data[].​customFieldsArray of objects or null
Any of:
data[].​timeZonestring or null
Any of:
string
metaobjectrequired

Collection of items.

meta.​limitinteger(int64)>= 1

Current limit

Example: 1
meta.​offsetinteger(int64)>= 1

Current offset

Example: 10
meta.​totalinteger(int64)>= 0

Total items

Example: 100
Response
application/json
{ "data": [ {} ], "meta": { "limit": 0, "offset": 0, "total": 0 } }

Request

This endpoint allows you to add a new person to the Calamari. The request must include essential details such as first name, last name, e-mail address, approval process, work schedule, and holidays calendar.

Security
basicAuth
Bodyapplication/jsonrequired
firstNamestring[ 1 .. 255 ] charactersrequired

Person's first name.

Example: "John"
middleNamestring or null

Person's middle name (Core HR module required).

Any of:

Person's middle name (Core HR module required).

[ 1 .. 255 ] characters
string[ 1 .. 255 ] characters
lastNamestring[ 1 .. 255 ] charactersrequired

Person's last name.

Example: "Doe"
emailstring(email)[ 1 .. 255 ] charactersrequired

Valid email address.

Example: "john.doe@example.com"
approvalProcessstring or integer[ 1 .. 255 ] charactersrequired

Approval process name or identifier.

Any of:

Approval process name or identifier.

[ 1 .. 255 ] characters
string[ 1 .. 255 ] characters
workSchedulestring or integerrequired

Work schedule name or identifier.

Any of:

Work schedule name or identifier.

[ 1 .. 255 ] characters
string[ 1 .. 255 ] characters
holidaysCalendarstring or integerrequired

Holidays calendar name or identifier.

Any of:

Holidays calendar name or identifier.

[ 1 .. 255 ] characters
string[ 1 .. 255 ] characters
contractTypestring or null[ 1 .. 255 ] characters

Contract type name or identifier.

Any of:

Contract type name or identifier.

[ 1 .. 255 ] characters
string[ 1 .. 255 ] characters
hireDatestring or null

Hire date in ISO 8601 format.

Any of:

Hire date in ISO 8601 format.

string(date)
birthdatestring or null

Birthdate in ISO 8601 format (Core HR module required).

Any of:

Birthdate in ISO 8601 format (Core HR module required).

string(date)
sexstring or null(sex-schema)

Person's sex.

Enum"MALE""FEMALE""OTHER"null
Example: "MALE"
positionstring or integer or null

Job position/title name or identifier.

Any of:

Job position/title name or identifier.

[ 1 .. 255 ] characters
string[ 1 .. 255 ] characters
teams(Array of strings or integers) or null

List of team names or identifiers the person belongs to.

Example: ["Accountants",3]
Any of:

List of team names or identifiers the person belongs to.

maritalStatusstring or null(martial-status-schema)

Describes a person's relationship with a significant other.

Enum"SINGLE""MARRIED""WIDOWED""SEPARATED""DIVORCED""DOMESTIC_PARTNERSHIP""COMMON_LAW""OTHER"null
Example: "MARRIED"
terminationDatestring or null

Termination date if applicable (ISO 8601 format).

Any of:

Termination date if applicable (ISO 8601 format).

string(date)
directManagerstring or null[ 1 .. 255 ] characters

Unique e-mail address or UUID of the direct manager.

Any of:

Unique e-mail address or UUID of the direct manager.

[ 1 .. 255 ] characters
string(email)[ 1 .. 255 ] characters
probationEndDatestring or null

End date of probation period (ISO 8601 format).

Any of:

End date of probation period (ISO 8601 format).

string(date)
externalNumberstring or null

External reference number for the person.

Any of:

External reference number for the person.

[ 1 .. 255 ] characters
string[ 1 .. 255 ] characters
symfoniaGuidstring or null

GUID from Symfonia system (Time Off module required).

Any of:

GUID from Symfonia system (Time Off module required).

string(uuid)
customNotestring or null

Custom note or additional information

Any of:

Custom note or additional information

[ 1 .. 1024 ] characters
string[ 1 .. 1024 ] characters
businessContactobject or null

Business contact information (Core HR module required).

Any of:

Business contact information (Core HR module required).

personalContactobject or null

Personal contact information (Core HR module required).

Any of:

Personal contact information (Core HR module required).

seniorityBeforeHireinteger or null

Seniority in months before the hire date.

Any of:

Seniority in months before the hire date.

<= 1200 characters
integer(int64)<= 1200 characters
addressobject or null

Person's home address (Core HR module required).

Any of:

Person's home address (Core HR module required).

emergencyContactobject or null

Emergency contact details (Core HR module required).

Any of:

Emergency contact details (Core HR module required).

bankAccountNumberstring or null

Person's bank account number (Core HR module required).

Any of:

Person's bank account number (Core HR module required).

[ 1 .. 255 ] characters
string[ 1 .. 255 ] characters
contractorDetailsobject or null

Contractor-related details (Core HR module required).

Any of:

Contractor-related details (Core HR module required).

shirtSizestring or null

Shirt size (Core HR module required).

Any of:

Shirt size (Core HR module required).

string
Enum"XS""S""M""L""XL""2XL""3XL""4XL"
childrenArray of objects

List of persons' children (Core HR module required).

customFieldsArray of objects

Custom attributes assigned to the person (Core HR module required). One of text, multiline text, date, single-choice list, multiple choice list, numerical, boolean.

curl -i -X POST \
  -u <username>:<password> \
  'https://{tenantname}.calamari.io/api/people/v2' \
  -H 'Content-Type: application/json' \
  -d '{
    "firstName": "John",
    "middleName": "Paul",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "approvalProcess": "Basic Approval Flow",
    "workSchedule": "Full-time - 40h",
    "holidaysCalendar": "Default",
    "contractType": "B2B",
    "hireDate": "2025-01-15",
    "birthdate": "1990-06-25",
    "sex": "MALE",
    "position": "Senior Accountant",
    "teams": [
      "Accountants",
      3
    ],
    "maritalStatus": "SINGLE",
    "terminationDate": "2026-12-31",
    "directManager": "patricia.kite@example.com",
    "probationEndDate": "2025-07-01",
    "externalNumber": "EMP-98765",
    "symfoniaGuid": "52601c08-b7e5-4c60-a57f-2b1d74942543",
    "customNote": "Works remotely on Fridays.",
    "businessContact": {
      "phone": "+1-555-1234"
    },
    "personalContact": {
      "phone": "+1-555-5678",
      "email": "john.doe.personal@example.com"
    },
    "seniorityBeforeHire": 24,
    "address": {
      "street": "Main Street",
      "number": "123",
      "city": "New York",
      "provinceState": "NY",
      "postalCode": "10001",
      "country": "USA"
    },
    "emergencyContact": {
      "name": "Jane Doe",
      "relationship": "Spouse",
      "phone": "+1-555-9999"
    },
    "bankAccountNumber": "US12345678901234567890",
    "contractorDetails": {
      "taxNumber": "123-45-6789",
      "companyName": "Tech Solutions Inc.",
      "companyAddress": "456 Business St, San Francisco, CA, USA"
    },
    "shirtSize": "M",
    "children": [
      {
        "firstName": "Emily",
        "lastName": "Doe",
        "birthdate": "2015-09-10",
        "sex": "MALE",
        "parent": "Kathryn Doe"
      }
    ],
    "customFields": [
      {
        "name": "Skills/Languages spoken/Speaks fluently",
        "value": "English"
      }
    ]
  }'

Responses

Person created successfully.

Bodyapplication/json
idstring(uuid)required
Example: "2c11e9ec-77d2-49fe-81aa-fab21f7b5aed"
legacyIdintegerrequired
Example: 1001
Response
application/json
{ "id": "2c11e9ec-77d2-49fe-81aa-fab21f7b5aed", "legacyId": 1001 }

Request

This endpoint allows you to partially update a person in Calamari. You can send any number of fields in the request body. Only the fields included in the request will be updated. If a field is set to null, its value will be removed (if removal is allowed). Fields that are not included in the request will remain unchanged, even if they exist in the system. This means you can send both updated and unchanged fields, but only those explicitly provided in the request will be processed.

Security
basicAuth
Path
idstring(person-identifier-param-schema)required

The person identifier. Supports:

24dc4a05-ef40-4c30-9b95-554bf3be8741 (UUID)
id:12345 (legacy numeric ID)
number:AO-00710 (external number)
email:example@local.com (email address)

Reserved characters in path segments
Any reserved or unsafe character—literal (#, /, ?, space) or percent-encoded (%23, %2F, %3F, %20, etc.)—will be blocked or truncated by the server at that character and everything after it.

Recommendation
• Use only unreserved characters in path identifiers (no #, /, ?, spaces).
• If an identifier may contain reserved characters, pass it as a query parameter or in the request body instead.

Any of:

The person identifier. Supports:

24dc4a05-ef40-4c30-9b95-554bf3be8741 (UUID)
id:12345 (legacy numeric ID)
number:AO-00710 (external number)
email:example@local.com (email address)

Reserved characters in path segments
Any reserved or unsafe character—literal (#, /, ?, space) or percent-encoded (%23, %2F, %3F, %20, etc.)—will be blocked or truncated by the server at that character and everything after it.

Recommendation
• Use only unreserved characters in path identifiers (no #, /, ?, spaces).
• If an identifier may contain reserved characters, pass it as a query parameter or in the request body instead.

string(uuid)
Bodyapplication/jsonrequired
emailstring(email)[ 1 .. 255 ] characters

Valid email address.

Example: "john.doe@example.com"
firstNamestring[ 1 .. 255 ] characters

Person's first name.

Example: "John"
middleNamestring or null

Person's middle name (Core HR module required).

Any of:

Person's middle name (Core HR module required).

[ 1 .. 255 ] characters
string[ 1 .. 255 ] characters
lastNamestring[ 1 .. 255 ] characters

Person's last name.

Example: "Doe"
approvalProcessstring or integer[ 1 .. 255 ] characters

Approval process name or identifier.

Any of:

Approval process name or identifier.

[ 1 .. 255 ] characters
string[ 1 .. 255 ] characters
workSchedulestring or integer

Work schedule name or identifier.

Any of:

Work schedule name or identifier.

[ 1 .. 255 ] characters
string[ 1 .. 255 ] characters
holidaysCalendarstring or integer

Holidays calendar name or identifier.

Any of:

Holidays calendar name or identifier.

[ 1 .. 255 ] characters
string[ 1 .. 255 ] characters
contractTypestring or null[ 1 .. 255 ] characters

Contract type name or identifier.

Any of:

Contract type name or identifier.

[ 1 .. 255 ] characters
string[ 1 .. 255 ] characters
hireDatestring or null

Hire date in ISO 8601 format.

Any of:

Hire date in ISO 8601 format.

string(date)
birthdatestring or null

Birthdate in ISO 8601 format (Core HR module required).

Any of:

Birthdate in ISO 8601 format (Core HR module required).

string(date)
sexstring or null(sex-schema)

Person's sex.

Enum"MALE""FEMALE""OTHER"null
Example: "MALE"
positionstring or integer or null

Job position/title name or identifier.

Any of:

Job position/title name or identifier.

[ 1 .. 255 ] characters
string[ 1 .. 255 ] characters
teams(Array of strings or integers) or null

List of team names or identifiers the person belongs to.

Example: ["Accountants",3]
Any of:

List of team names or identifiers the person belongs to.

maritalStatusstring or null(martial-status-schema)

Describes a person's relationship with a significant other.

Enum"SINGLE""MARRIED""WIDOWED""SEPARATED""DIVORCED""DOMESTIC_PARTNERSHIP""COMMON_LAW""OTHER"null
Example: "MARRIED"
terminationDatestring or null
Any of:
string(date)
directManagerstring or null[ 1 .. 255 ] characters

Identifier of the direct manager.

Any of:

Identifier of the direct manager.

[ 1 .. 255 ] characters
string(uuid)[ 1 .. 255 ] characters
probationEndDatestring or null

End date of probation period (ISO 8601 format).

Any of:

End date of probation period (ISO 8601 format).

string(date)
externalNumberstring or null

External reference number for the person.

Any of:

External reference number for the person.

[ 1 .. 255 ] characters
string[ 1 .. 255 ] characters
symfoniaGuidstring or null

GUID from Symfonia system.

Any of:

GUID from Symfonia system.

string(uuid)
customNotestring or null

Custom note or additional information

Any of:

Custom note or additional information

[ 1 .. 1024 ] characters
string[ 1 .. 1024 ] characters
businessContactobject or null

Business contact information (Core HR module required).

Any of:

Business contact information (Core HR module required).

personalContactobject or null

Personal contact information (Core HR module required).

Any of:

Personal contact information (Core HR module required).

seniorityBeforeHireinteger or null

Seniority in months before the hire date.

Any of:

Seniority in months before the hire date.

<= 1200 characters
integer(int64)<= 1200 characters
addressobject or null

Person's home address (Core HR module required).

Any of:

Person's home address (Core HR module required).

emergencyContactobject or null

Emergency contact details (Core HR module required).

Any of:

Emergency contact details (Core HR module required).

bankAccountNumberstring or null

Person's bank account number (Core HR module required).

Any of:

Person's bank account number (Core HR module required).

[ 1 .. 255 ] characters
string[ 1 .. 255 ] characters
contractorDetailsobject or null

Contractor-related details (Core HR module required).

Any of:

Contractor-related details (Core HR module required).

shirtSizestring or null

Shirt size (Core HR module required).

Any of:

Shirt size (Core HR module required).

string
Enum"XS""S""M""L""XL""2XL""3XL""4XL"
childrenArray of objects

List of persons' children (Core HR module required).

Note: Include all active children. The excluded item will be removed.

customFieldsArray of objects

Custom attributes assigned to the person (Core HR module required).

curl -i -X PATCH \
  -u <username>:<password> \
  'https://{tenantname}.calamari.io/api/people/v2/{id}' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "john.doe@example.com",
    "firstName": "John",
    "middleName": "Paul",
    "lastName": "Doe",
    "approvalProcess": "name:Basic Approval Flow",
    "workSchedule": "name:Full-time - 40h",
    "holidaysCalendar": "name:Default",
    "contractType": "name:B2B",
    "hireDate": "2025-01-15",
    "birthdate": "1990-06-25",
    "sex": "MALE",
    "position": "Senior Accountant",
    "teams": [
      "Accountants",
      3
    ],
    "maritalStatus": "SINGLE",
    "terminationDate": "2026-12-31",
    "directManager": "38715bd3-7ad5-4372-bcff-41a3c933af68",
    "probationEndDate": "2025-07-01",
    "externalNumber": "EMP-98765",
    "symfoniaGuid": "52601c08-b7e5-4c60-a57f-2b1d74942543",
    "customNote": "Works remotely on Fridays.",
    "businessContact": {
      "phone": "+1-555-1234"
    },
    "personalContact": {
      "phone": "+1-555-5678",
      "email": "john.doe.personal@example.com"
    },
    "seniorityBeforeHire": 24,
    "address": {
      "street": "Main Street",
      "number": "123",
      "city": "New York",
      "provinceState": "NY",
      "postalCode": "10001",
      "country": "USA"
    },
    "emergencyContact": {
      "name": "Jane Doe",
      "relationship": "Spouse",
      "phone": "+1-555-9999"
    },
    "bankAccountNumber": "US12345678901234567890",
    "contractorDetails": {
      "taxNumber": "123-45-6789",
      "companyName": "Tech Solutions Inc.",
      "companyAddress": "456 Business St, San Francisco, CA, USA"
    },
    "shirtSize": "M",
    "children": [
      {
        "firstName": "Emily",
        "lastName": "Doe",
        "birthdate": "2015-09-10",
        "sex": "MALE",
        "parent": "Kathryn Doe"
      }
    ],
    "customFields": [
      {
        "name": "Skills/Languages spoken/Speaks fluently",
        "value": "English"
      }
    ]
  }'

Responses

Person updated successfully.

Response
No content

Request

This endpoint allows you to archive a person in Calamari.

Security
basicAuth
Path
idstring(person-identifier-param-schema)required

The person identifier. Supports:

24dc4a05-ef40-4c30-9b95-554bf3be8741 (UUID)
id:12345 (legacy numeric ID)
number:AO-00710 (external number)
email:example@local.com (email address)

Reserved characters in path segments
Any reserved or unsafe character—literal (#, /, ?, space) or percent-encoded (%23, %2F, %3F, %20, etc.)—will be blocked or truncated by the server at that character and everything after it.

Recommendation
• Use only unreserved characters in path identifiers (no #, /, ?, spaces).
• If an identifier may contain reserved characters, pass it as a query parameter or in the request body instead.

Any of:

The person identifier. Supports:

24dc4a05-ef40-4c30-9b95-554bf3be8741 (UUID)
id:12345 (legacy numeric ID)
number:AO-00710 (external number)
email:example@local.com (email address)

Reserved characters in path segments
Any reserved or unsafe character—literal (#, /, ?, space) or percent-encoded (%23, %2F, %3F, %20, etc.)—will be blocked or truncated by the server at that character and everything after it.

Recommendation
• Use only unreserved characters in path identifiers (no #, /, ?, spaces).
• If an identifier may contain reserved characters, pass it as a query parameter or in the request body instead.

string(uuid)
curl -i -X POST \
  -u <username>:<password> \
  'https://{tenantname}.calamari.io/api/people/v2/{id}/archive'

Responses

Person archived successfully.

Response
No content

Request

This endpoint allows you to send an invitation email to Calamari.

Security
basicAuth
Path
idstring(person-identifier-param-schema)required

The person identifier. Supports:

24dc4a05-ef40-4c30-9b95-554bf3be8741 (UUID)
id:12345 (legacy numeric ID)
number:AO-00710 (external number)
email:example@local.com (email address)

Reserved characters in path segments
Any reserved or unsafe character—literal (#, /, ?, space) or percent-encoded (%23, %2F, %3F, %20, etc.)—will be blocked or truncated by the server at that character and everything after it.

Recommendation
• Use only unreserved characters in path identifiers (no #, /, ?, spaces).
• If an identifier may contain reserved characters, pass it as a query parameter or in the request body instead.

Any of:

The person identifier. Supports:

24dc4a05-ef40-4c30-9b95-554bf3be8741 (UUID)
id:12345 (legacy numeric ID)
number:AO-00710 (external number)
email:example@local.com (email address)

Reserved characters in path segments
Any reserved or unsafe character—literal (#, /, ?, space) or percent-encoded (%23, %2F, %3F, %20, etc.)—will be blocked or truncated by the server at that character and everything after it.

Recommendation
• Use only unreserved characters in path identifiers (no #, /, ?, spaces).
• If an identifier may contain reserved characters, pass it as a query parameter or in the request body instead.

string(uuid)
curl -i -X POST \
  -u <username>:<password> \
  'https://{tenantname}.calamari.io/api/people/v2/{id}/invite'

Responses

Person invited successfully.

Response
No content