Update historical timesheet entry.

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

Timesheet entries

Timesheet entries API

Operations

Add historical timesheet entry.

Request

Add employee shift.

Expect error codes:

INVALID_EMPLOYEE - when invalid employee id provided
INVALID_SHIFT_START - when invalid start of work time provided
INVALID_SHIFT_END - when invalid finish of work time provided
SHIFT_END_BEFORE_START - when end of work time is before start
SHIFT_TO_SHORT - when shift period is shorter than one minute
INVALID_BREAK_TYPE - when invalid break type id provided. You should use get-break-types method to find proper break type ID
INVALID_BREAK_FOR_USER - when break type is not available for employee
INVALID_BREAK_START - when invalid start of break time provided
INVALID_BREAK_END - when invalid finish of break time provided
BREAK_END_BEFORE_START - when end of break time is before start
BREAK_IS_NOT_IN_SHIFT_RANGE - when break time range goes beyond work time range
BREAK_TO_SHORT - when break period is shorter than one minute
BREAKS_OVERLAP - when one break time range overlaps another
INVALID_PROJECT_TYPE - when invalid project type id provided. You should use get-projects method to find proper project type ID
INVALID_PROJECT_FOR_USER - when project type is not available for employee. You should use get-projects-for-person method to find proper project type ID
INVALID_PROJECT_TIME_ENTRY_START - when invalid start of project time entry provided
INVALID_PROJECT_TIME_ENTRY_END - when invalid finish of project time entry provided
PROJECT_TIME_ENTRY_END_BEFORE_START - when end of project time entry is before start
PROJECT_TIME_ENTRY_IS_NOT_IN_SHIFT_RANGE - when project time entry goes beyond work time range
PROJECT_TIME_ENTRY_TO_SHORT - when project time entry is shorter than one minute
PROJECT_TIME_ENTRIES_OVERLAP - when one project time entry overlaps another
SHIFT_DESCRIPTION_TOO_LONG - when description contains more than 4096 characters

Security

basicAuth

Bodyapplication/json

personstringrequired

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

Example: "john.white@mycompany.com"

shiftStartstring(date-time)required

Date and time of shift start in ISO format

shiftEndstring(date-time)required

Date and time of shift end in ISO format

breaksArray of objects(BreakDtoIn)

List of breaks.

projectsArray of objects(ProjectDtoIn)

List of projects.

descriptionstring[ 0 .. 4096 ] characters

Shift description

curl -i -X POST \
  -u <username>:<password> \
  'https://{tenantname}.calamari.io/api/clockin/timesheetentries/v1/create' \
  -H 'Content-Type: application/json' \
  -d '{
    "person": "john.white@mycompany.com",
    "shiftStart": "2019-08-24T14:15:22Z",
    "shiftEnd": "2019-08-24T14:15:22Z",
    "breaks": [
      {
        "breakType": 1,
        "breakStart": "2019-08-24T14:15:22Z",
        "breakEnd": "2019-08-24T14:15:22Z"
      }
    ],
    "projects": [
      {
        "projectType": 1,
        "projectStart": "2019-08-24T14:15:22Z",
        "projectEnd": "2019-08-24T14:15:22Z"
      }
    ],
    "description": "string"
  }'

Responses

successful operation

Bodyapplication/json

idinteger(int64)required

Timesheet entry ID

startedstring(date-time)required

Date and time of timesheet entry started

finishedstring(date-time)

Date and time of timesheet entry finished. Has null value if employee does not clock out

startedTimeZonestringrequired

Started work timzeone

Example: "Europe/Warsaw"

finishedTimeZonestring

Finished work timezone. Has null value if employee does not clock out

Example: "Europe/Warsaw"

durationinteger(int64)required

Duration of timesheet entry in seconds. Has 0 value if employee does not clock out

Example: 28800

personobject(EmployeeSimpleOut)required

Employee

person.firstNamestringrequired

Employee first name

Example: "John"

person.lastNamestringrequired

Employee last name

Example: "Williams"

person.emailstringrequired

Employee email

Example: "john.williams@domain.com"

person.externalIdstring

Employee external identifier

Example: "A12Y"

breaksArray of objects(BreakDto)required

List of breaks

breaks[].fromstring(date-time)

Date and time when break was started.

breaks[].tostring(date-time)

Date and time when break was finished. Has null value if break was not finished

breaks[].durationinteger(int64)

Duration of a break in seconds. Has null value if break was not finished.

Example: 28800

breaks[].breakTypeobject(BreakTypeOut)

Break type.

projectsArray of objects(ProjectDto)required

List of projects

projects[].fromstring(date-time)

Date and time when employee started working on project

projects[].tostring(date-time)

Date and time when employee finished working on project. Has null value if work on project was not finished

projects[].durationinteger(int64)

Duration of time spent on a project in seconds. Has null value if work on project was not finished

Example: 28800

projects[].projectobject(ProjectOut)

Project properties

closedbooleanrequired

Is shift closed?

descriptionstring

Shift description

Response

application/json

{
  "id": 0,
  "started": "2019-08-24T14:15:22Z",
  "finished": "2019-08-24T14:15:22Z",
  "startedTimeZone": "Europe/Warsaw",
  "finishedTimeZone": "Europe/Warsaw",
  "duration": 28800,
  "person": {
    "firstName": "John",
    "lastName": "Williams",
    "email": "john.williams@domain.com",
    "externalId": "A12Y"
  },
  "breaks": [
    { … }
  ],
  "projects": [
    { … }
  ],
  "closed": true,
  "description": "string"
}

Delete timesheet entry by id

Request

Delete timesheet entry by id

Security

basicAuth

Bodyapplication/json

idinteger(int64)required

curl -i -X POST \
  -u <username>:<password> \
  'https://{tenantname}.calamari.io/api/clockin/timesheetentries/v1/delete' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": 0
  }'

Responses

Removed successfully.

Response

No content

Find timesheet entries with advanced filtering by several parameters.

Request

Find timesheet entries 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 timesheet entries.

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 {contractTypes: ["Full-time"], teams: ["DevTeam"]} then timesheet entries of employees from Dev and Full-time

The query returns all matching records for the selected time range and filters, with no pagination applied.

Expect error codes:

INVALID_DATE_FROM - when invalid time in filter provided
INVALID_DATE_TO - when invalid time in filter provided
INVALID_EMPLOYEE - when one of provided employees is invalid
INVALID_TEAM - when one of provided teams is invalid
INVALID_POSITION - when one of provided positions is invalid
INVALID_CONTRACT_TYPE - when one of provided contract types is invalid

Security

basicAuth

Bodyapplication/json

fromstring(date)required

Start date of dates range to search timesheet entries in ISO format

Example: "2018-10-01"

tostring(date)required

End date of dates range to search timesheet entries in ISO format

Example: "2018-10-01"

teamsArray of strings

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

positionsArray of strings

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

contractTypesArray of strings

List of contract types names or identifiers to search. As a result there will be timesheet entries of employees who have one of contract type. Example: ["Full Time"]

employeesArray of strings

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

curl -i -X POST \
  -u <username>:<password> \
  'https://{tenantname}.calamari.io/api/clockin/timesheetentries/v1/find' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "2018-10-01",
    "to": "2018-10-01",
    "teams": [
      "string"
    ],
    "positions": [
      "string"
    ],
    "contractTypes": [
      "string"
    ],
    "employees": [
      "string"
    ]
  }'

Responses

successful operation

Bodyapplication/jsonArray [

idinteger(int64)required

Timesheet entry ID

startedstring(date-time)required

Date and time of timesheet entry started

finishedstring(date-time)

Date and time of timesheet entry finished. Has null value if employee does not clock out

startedTimeZonestringrequired

Started work timzeone

Example: "Europe/Warsaw"

finishedTimeZonestring

Finished work timezone. Has null value if employee does not clock out

Example: "Europe/Warsaw"

durationinteger(int64)required

Duration of timesheet entry in seconds. Has 0 value if employee does not clock out

Example: 28800

personobject(EmployeeSimpleOut)required

Employee

person.firstNamestringrequired

Employee first name

Example: "John"

person.lastNamestringrequired

Employee last name

Example: "Williams"

person.emailstringrequired

Employee email

Example: "john.williams@domain.com"

person.externalIdstring

Employee external identifier

Example: "A12Y"

breaksArray of objects(BreakDto)required

List of breaks

breaks[].fromstring(date-time)

Date and time when break was started.

breaks[].tostring(date-time)

Date and time when break was finished. Has null value if break was not finished

breaks[].durationinteger(int64)

Duration of a break in seconds. Has null value if break was not finished.

Example: 28800

breaks[].breakTypeobject(BreakTypeOut)

Break type.

projectsArray of objects(ProjectDto)required

List of projects

projects[].fromstring(date-time)

Date and time when employee started working on project

projects[].tostring(date-time)

Date and time when employee finished working on project. Has null value if work on project was not finished

projects[].durationinteger(int64)

Duration of time spent on a project in seconds. Has null value if work on project was not finished

Example: 28800

projects[].projectobject(ProjectOut)

Project properties

closedbooleanrequired

Is shift closed?

descriptionstring

Shift description

]

Response

application/json

[
  {
    "id": 0,
    "started": "2019-08-24T14:15:22Z",
    "finished": "2019-08-24T14:15:22Z",
    "startedTimeZone": "Europe/Warsaw",
    "finishedTimeZone": "Europe/Warsaw",
    "duration": 28800,
    "person": { … },
    "breaks": [ … ],
    "projects": [ … ],
    "closed": true,
    "description": "string"
  }
]

Find employees working time balances with advanced filtering by several parameters.

Request

Find employees working time balances 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 balances.

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 {contractTypes: ["Full-time"], teams: ["DevTeam"]} then you receive balances of employees from Dev and Full-time

Expect error codes:

INVALID_DATE_FROM - when invalid time in filter provided
INVALID_DATE_TO - when invalid time in filter provided
INVALID_EMPLOYEE - when one of provided employees is invalid
INVALID_TEAM - when one of provided teams is invalid
INVALID_POSITION - when one of provided positions is invalid
INVALID_CONTRACT_TYPE - when one of provided contract types is invalid

Security

basicAuth

Bodyapplication/json

fromstring(date)required

Start date of dates range to search request in ISO format

Example: "2020-01-10"

tostring(date)required

End date of dates range to search request in ISO format

Example: "2020-01-15"

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

curl -i -X POST \
  -u <username>:<password> \
  'https://{tenantname}.calamari.io/api/clockin/timesheetentries/v1/balance' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "2020-01-10",
    "to": "2020-01-15",
    "teams": [
      "string"
    ],
    "positions": [
      "string"
    ],
    "contractTypes": [
      "string"
    ],
    "employees": [
      "string"
    ]
  }'

Responses

successful operation

Bodyapplication/jsonArray [

personobject(EmployeeSimpleOut)required

Employee

person.firstNamestringrequired

Employee first name

Example: "John"

person.lastNamestringrequired

Employee last name

Example: "Williams"

person.emailstringrequired

Employee email

Example: "john.williams@domain.com"

person.externalIdstring

Employee external identifier

Example: "A12Y"

balanceinteger(int64)required

Working time balance in seconds

Example: -3600

]

Response

application/json

[
  {
    "person": { … },
    "balance": -3600
  }
]

Get project types.

Request

Get project types.

Security

basicAuth

curl -i -X POST \
  -u <username>:<password> \
  'https://{tenantname}.calamari.io/api/clockin/timesheetentries/v1/get-projects'

Responses

successful operation

Bodyapplication/jsonArray [

idinteger(int64)

Project id

namestring

Project name

Example: "Primary project"

]

Response

application/json

[
  {
    "id": 0,
    "name": "Primary project"
  }
]

Get project types for one person.

Request

Get project types for one person.

Expect error codes:

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/timesheetentries/v1/get-projects-for-person' \
  -H 'Content-Type: application/json' \
  -d '{
    "person": "john.white@mycompany.com"
  }'

Responses

successful operation

Bodyapplication/jsonArray [

idinteger(int64)

Project id

namestring

Project name

Example: "Primary project"

]

Response

application/json

[
  {
    "id": 0,
    "name": "Primary project"
  }
]