API for developers

Your leave data, in every system that needs it

A REST API that returns JSON. Send leave requests to payroll, sync absences with your ERP or feed them into BI reports, without exports by hand.

Request an API key Download the OpenAPI spec

The API is included in the Standard and Enterprise plans. Pricing →

Version: 2.1.0
Base URL: https://timeoff.guru/to/{instance}/xsp/resources/api
Authentication: TimeOffApiKey: …
Format: REST · JSON · GET

What teams build with it

Payroll
Pull the month’s approved leave before the payroll run, with days, hours and leave type.
leaveRequestByMonth →
Daily sync
Once a day, pick up the requests that were approved, cancelled or changed, and update your ERP or access control.
leaveRequestsInProgress →
Reports and BI
Combine leave types, organizations and requests with your other HR data in Power BI or another tool.
leaveTypes →

Quick start

Get an API key
Your TIMEOFF.GURU administrator issues the key. Keep it on your server and never put it in a browser or a mobile app.
Send it in a header
Every request carries the key in the TimeOffApiKey header. All methods are GET and return JSON.
Make your first call
Replace {instance} with your instance name and try the leave requests for a month.

bash

curl "https://timeoff.guru/to/{instance}/xsp/resources/api/leaves/leaveRequestByMonth?year=2026&month=10" \
  -H "TimeOffApiKey: YOUR_API_KEY"

Reference

Configuration

Organizations and leave types set up in your instance.

List organizations

GET/configuration/organizations

Returns the organizations in your instance: name, full name, company ID (Bulstat), address, city and country.

Parameters

No parameters.

Responses

200Success
401The API key is missing or invalid

Example request

curl "https://timeoff.guru/to/{instance}/xsp/resources/api/configuration/organizations" \
  -H "TimeOffApiKey: YOUR_API_KEY"

Response structureValues show the data type.

{
  "organizations": [
    {
      "country": "string",
      "unid": "string",
      "address": "string",
      "deleted": "string",
      "city": "string",
      "name": "string",
      "fullName": "string",
      "bulstat": "string"
    }
  ],
  "success": true
}

List leave types

GET/configuration/leaveTypes

Returns the configured leave types: name in Bulgarian and English, short name, whether the leave is paid, whether it is deducted from the balance, whether it is active and whether it needs an attachment.

Parameters

Name	Type	Description
`organizationId`optional	string	Organization ID. Needed only if your instance has more than one configuration.

Responses

200Success
401The API key is missing or invalid

Example request

curl "https://timeoff.guru/to/{instance}/xsp/resources/api/configuration/leaveTypes" \
  -H "TimeOffApiKey: YOUR_API_KEY"

Response structureValues show the data type.

{
  "leaveTypes": [
    {
      "id": 0,
      "uuid": "string",
      "name": {
        "default": "string",
        "bg": "string",
        "en": "string"
      },
      "shortName": "string",
      "notes": {
        "default": "string",
        "bg": "string",
        "en": "string"
      },
      "paid": true,
      "deduct": true,
      "active": true,
      "attachFile": true,
      "kind": "string"
    }
  ],
  "success": true
}

Reference

Leaves

Leave requests, planned leaves and the changes in them.

Get a leave request

GET/leaves/leaveRequestByUnid

Returns one leave request: dates, leave type, days or hours, status, approver and the full status history (who did what and when).

Parameters

Name	Type	Description
`unid`required	string	Unique ID (UNID) of the leave request.

Responses

200Success
401The API key is missing or invalid
404Not found

Example request

curl "https://timeoff.guru/to/{instance}/xsp/resources/api/leaves/leaveRequestByUnid?unid=REQUEST_UNID" \
  -H "TimeOffApiKey: YOUR_API_KEY"

Response structureValues show the data type.

{
  "requestInfo": {
    "date": "string",
    "periodMode": "string",
    "unid": "string",
    "usedYears": {
      "year": {
        "days": 0,
        "hours": 0
      }
    },
    "endDate": "string",
    "kind": "string",
    "substitutes": {},
    "statusLog": [
      {
        "date": "string",
        "reason": "string",
        "approveComment": "string",
        "effectiveEmployee": {
          "id": null,
          "name": null
        },
        "employee": {
          "id": null,
          "name": null
        },
        "status": "string"
      }
    ],
    "approvedBy": {
      "employee_id": "string"
    },
    "description": "string",
    "dates": [
      "string"
    ],
    "type": "string",
    "hoursRange": "string",
    "requestor": "string",
    "email": "string",
    "employeeNumber": "string",
    "rejectReason": "string",
    "leaveType": "string",
    "days": 0,
    "typeId": 0,
    "startDate": "string",
    "hoursAmount": 0,
    "status": "string"
  },
  "success": true
}

Leave requests of an employee

GET/leaves/leaveRequestsByEmployee

Returns all leave requests created by the employee.

Parameters

Name	Type	Description
`employeeId`required	string	Employee ID.

Responses

200Success
401The API key is missing or invalid

Example request

curl "https://timeoff.guru/to/{instance}/xsp/resources/api/leaves/leaveRequestsByEmployee?employeeId=EMPLOYEE_ID" \
  -H "TimeOffApiKey: YOUR_API_KEY"

Response structureValues show the data type.

{
  "requests": [
    {
      "date": "string",
      "periodMode": "string",
      "unid": "string",
      "usedYears": {
        "year": {
          "days": null,
          "hours": null
        }
      },
      "endDate": "string",
      "kind": "string",
      "substitutes": {},
      "statusLog": [
        {
          "date": null,
          "reason": null,
          "approveComment": null,
          "effectiveEmployee": null,
          "employee": null,
          "status": null
        }
      ],
      "approvedBy": {
        "employee_id": "string"
      },
      "description": "string",
      "dates": [
        "string"
      ],
      "type": "string",
      "hoursRange": "string",
      "requestor": "string",
      "email": "string",
      "employeeNumber": "string",
      "rejectReason": "string",
      "leaveType": "string",
      "days": 0,
      "typeId": 0,
      "startDate": "string",
      "hoursAmount": 0,
      "status": "string"
    }
  ],
  "success": true
}

Leave requests for a month

GET/leaves/leaveRequestByMonth

Returns the leave requests in the given month. Requests in status Rejected, Canceled or Current are not included. A good fit for the monthly payroll run.

Parameters

Name	Type	Description
`year`required	number	Year of the leave period.
`month`required	number	Month of the leave period.

Responses

200Success
401The API key is missing or invalid

Example request

curl "https://timeoff.guru/to/{instance}/xsp/resources/api/leaves/leaveRequestByMonth?year=2026&month=10" \
  -H "TimeOffApiKey: YOUR_API_KEY"

Response structureValues show the data type.

{
  "requests": [
    {
      "date": "string",
      "periodMode": "string",
      "unid": "string",
      "usedYears": {
        "year": {
          "days": null,
          "hours": null
        }
      },
      "endDate": "string",
      "kind": "string",
      "substitutes": {},
      "statusLog": [
        {
          "date": null,
          "reason": null,
          "approveComment": null,
          "effectiveEmployee": null,
          "employee": null,
          "status": null
        }
      ],
      "approvedBy": {
        "employee_id": "string"
      },
      "description": "string",
      "dates": [
        "string"
      ],
      "type": "string",
      "hoursRange": "string",
      "requestor": "string",
      "email": "string",
      "employeeNumber": "string",
      "rejectReason": "string",
      "leaveType": "string",
      "days": 0,
      "typeId": 0,
      "startDate": "string",
      "hoursAmount": 0,
      "status": "string"
    }
  ],
  "success": true
}

All leave requests for a month

GET/leaves/allLeaveRequestByMonth

Like the previous method, but returns requests in every status.

Parameters

Name	Type	Description
`year`required	number	Year of the leave period.
`month`required	number	Month of the leave period.

Responses

200Success
401The API key is missing or invalid

Example request

curl "https://timeoff.guru/to/{instance}/xsp/resources/api/leaves/allLeaveRequestByMonth?year=2026&month=10" \
  -H "TimeOffApiKey: YOUR_API_KEY"

Response structureValues show the data type.

{
  "requests": [
    {
      "date": "string",
      "periodMode": "string",
      "unid": "string",
      "usedYears": {
        "year": {
          "days": null,
          "hours": null
        }
      },
      "endDate": "string",
      "kind": "string",
      "substitutes": {},
      "statusLog": [
        {
          "date": null,
          "reason": null,
          "approveComment": null,
          "effectiveEmployee": null,
          "employee": null,
          "status": null
        }
      ],
      "approvedBy": {
        "employee_id": "string"
      },
      "description": "string",
      "dates": [
        "string"
      ],
      "type": "string",
      "hoursRange": "string",
      "requestor": "string",
      "email": "string",
      "employeeNumber": "string",
      "rejectReason": "string",
      "leaveType": "string",
      "days": 0,
      "typeId": 0,
      "startDate": "string",
      "hoursAmount": 0,
      "status": "string"
    }
  ],
  "success": true
}

Planned leaves of an employee

GET/leaves/plannedLeaves

Returns the leaves the employee has planned: start and end date, number of days and the list of dates.

Parameters

Name	Type	Description
`employeeId`required	string	Employee ID.

Responses

200Success
401The API key is missing or invalid

Example request

curl "https://timeoff.guru/to/{instance}/xsp/resources/api/leaves/plannedLeaves?employeeId=EMPLOYEE_ID" \
  -H "TimeOffApiKey: YOUR_API_KEY"

Response structureValues show the data type.

{
  "planned": [
    {
      "endDate": "string",
      "days": 0,
      "dates": [
        "string"
      ],
      "startDate": "string"
    }
  ],
  "success": true
}

Changes in leave requests

GET/leaves/leaveRequestsInProgress

Returns leave requests grouped by what is happening to them: accepted, current, cancelled, modified and archived. Covers the current day by default. A good fit for a daily sync with payroll, ERP or access control.

Parameters

Name	Type	Description
`daysBack`optional	number	How many days back to look. Applies only to cancelled, modified and archived requests.
`exclude`optional	string	Groups to leave out: accepted, current, cancelled, modified, archived. To exclude several, concatenate them.

Responses

200Success
401The API key is missing or invalid

Example request

curl "https://timeoff.guru/to/{instance}/xsp/resources/api/leaves/leaveRequestsInProgress" \
  -H "TimeOffApiKey: YOUR_API_KEY"

Response structureValues show the data type.

{
  "acceptedRequests": [
    {
      "date": "string",
      "periodMode": "string",
      "unid": "string",
      "endDate": "string",
      "kind": "string",
      "substitutes": {},
      "approvedBy": {},
      "description": "string",
      "employeeId": "string",
      "dates": [
        "string"
      ],
      "type": "string",
      "requestor": "string",
      "hoursRange": "string",
      "rejectReason": "string",
      "leaveType": "string",
      "days": 0,
      "typeId": 0,
      "email": "string",
      "startDate": "string",
      "hoursAmount": 0,
      "status": "string"
    }
  ],
  "currentRequests": [
    {
      "date": "string",
      "periodMode": "string",
      "unid": "string",
      "endDate": "string",
      "kind": "string",
      "substitutes": {},
      "approvedBy": {},
      "description": "string",
      "employeeId": "string",
      "dates": [
        "string"
      ],
      "type": "string",
      "requestor": "string",
      "hoursRange": "string",
      "rejectReason": "string",
      "leaveType": "string",
      "days": 0,
      "typeId": 0,
      "email": "string",
      "startDate": "string",
      "hoursAmount": 0,
      "status": "string"
    }
  ],
  "cancelledRequests": [
    {
      "date": "string",
      "periodMode": "string",
      "unid": "string",
      "endDate": "string",
      "kind": "string",
      "substitutes": {},
      "approvedBy": {},
      "description": "string",
      "employeeId": "string",
      "dates": [
        "string"
      ],
      "type": "string",
      "requestor": "string",
      "hoursRange": "string",
      "rejectReason": "string",
      "leaveType": "string",
      "days": 0,
      "typeId": 0,
      "email": "string",
      "startDate": "string",
      "hoursAmount": 0,
      "status": "string"
    }
  ],
  "modifiedRequests": [
    {
      "date": "string",
      "periodMode": "string",
      "unid": "string",
      "endDate": "string",
      "kind": "string",
      "substitutes": {},
      "approvedBy": {},
      "description": "string",
      "employeeId": "string",
      "dates": [
        "string"
      ],
      "type": "string",
      "requestor": "string",
      "hoursRange": "string",
      "rejectReason": "string",
      "leaveType": "string",
      "days": 0,
      "typeId": 0,
      "email": "string",
      "startDate": "string",
      "hoursAmount": 0,
      "status": "string"
    }
  ],
  "archivedRequests": [
    {
      "date": "string",
      "periodMode": "string",
      "unid": "string",
      "endDate": "string",
      "kind": "string",
      "substitutes": {},
      "approvedBy": {},
      "description": "string",
      "employeeId": "string",
      "dates": [
        "string"
      ],
      "type": "string",
      "requestor": "string",
      "hoursRange": "string",
      "rejectReason": "string",
      "leaveType": "string",
      "days": 0,
      "typeId": 0,
      "email": "string",
      "startDate": "string",
      "hoursAmount": 0,
      "status": "string"
    }
  ],
  "success": true
}

Reference

Employees

Employee details and compensations.

Get an employee

GET/employees/employeeById

Returns the name, organization, department and working hours of an employee.

Parameters

Name	Type	Description
`employeeId`required	string	Employee ID.

Responses

200Success
401The API key is missing or invalid
403The employees API is not enabled in your instance
404Not found

Example request

curl "https://timeoff.guru/to/{instance}/xsp/resources/api/employees/employeeById?employeeId=EMPLOYEE_ID" \
  -H "TimeOffApiKey: YOUR_API_KEY"

Response structureValues show the data type.

{
  "employee": {
    "organization": "string",
    "name": "string",
    "id": "string",
    "department": "string",
    "workingHours": 0
  },
  "success": true
}

Compensations of an employee

GET/employees/compensationsByEmployee

Returns the compensations recorded for the employee: date, description, days and status.

Parameters

Name	Type	Description
`employeeId`required	string	Employee ID.

Responses

200Success
401The API key is missing or invalid
403The employees API is not enabled in your instance

Example request

curl "https://timeoff.guru/to/{instance}/xsp/resources/api/employees/compensationsByEmployee?employeeId=EMPLOYEE_ID" \
  -H "TimeOffApiKey: YOUR_API_KEY"

Response structureValues show the data type.

{
  "compensations": [
    {
      "date": "string",
      "unid": "string",
      "description": "string",
      "days": 0,
      "status": "string"
    }
  ],
  "success": true
}

Response codes

Every response has a success field. Check the HTTP status first:

200Success
401The API key is missing or invalid
403The employees API is not enabled in your instance
404Not found

Need help with an integration?

Tell us which system you want to connect, and we will help you pick the right methods and data.

Write to support

TIMEOFF.GURU API 2.1.0 · Licence: Apache 2.0

Your leave data, in every system that needs it

What teams build with it

Payroll

Daily sync

Reports and BI

Quick start

Get an API key

Send it in a header

Make your first call

Configuration

Parameters

Responses

Parameters

Responses

Leaves

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Employees

Parameters

Responses

Parameters

Responses

Response codes

Need help with an integration?