Create employee absences

Use this request to create records about employee absences (vacations, sick leaves, on-duty shifts, and others). Absences are displayed on user avatars and the resource chart in portfolios and projects.

POST

https://api.tracker.yandex.net/v3/gaps

Request format

Before executing the request, get access to the API.

You need Administrator rights to run this request.

To create a record about employee absences, use an HTTP request with the POST method. In the request body, specify the parameters in JSON format.

POST /v3/gaps
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth-token>
Content-Type: application/json
X-Org-ID or X-Cloud-Org-ID: <organization_ID>

{
  "gaps": [
    {
      "id": "<absence_ID>",
      "user": "<user_login>",
      "workflow": "<absence_type>",
      "from": "<start_date>",
      "to": "<end_date>",
      "fullDay": true,
      "workInAbsence": false
    }
  ]
}

Headers

Host: address of the node that provides the API.
Authorization: Authorization token about these formats:
- OAuth <OAuth_token>: For authorization using the OAuth 2.0 protocol. Learn more
- Bearer <IAM_token>: For authorization using an IAM token, if a Yandex Identity Hub organization is linked to Tracker. Learn more
X-Org-ID or X-Cloud-Org-ID: Organization ID.
- Use the X-Org-ID header if a Tracker organization is linked to Yandex 360 for Business.
- Use the X-Cloud-Org-ID header if a Tracker organization is linked to Yandex Identity Hub.
To get the organization ID, go to Administration → Organizations and copy the value from the ID field.

Request body parameters

Required parameters

Parameter	Description	Data type
gaps	Array of absence records. The maximum number of elements is 100	Array of objects

Array object fields gaps

Required parameters

Parameter	Description	Data type
user	User login or ID	String
workflow	Absence type. Possible values: `vacation`, `paid_day_off`, `illness`, `absence` (general), `trip` (business trip), `conference_trip`, `conference`, `learning`, `maternity`, `duty`. The up-to-date list is available via the `GET /v3/gaps/workflows` request	String
from	Absence start date and time in ISO 8601 format. Must be less than `to`	String
to	Absence end date and time in ISO 8601 format. Must be greater than `from`	String

Additional parameters

Parameter	Description	Data type
id	Absence ID. If not provided, it is generated automatically. The maximum length is 128 characters	String
fullDay	Full-day flag. The default value is `false`	Boolean
workInAbsence	Working during absence flag. The default value is `false`	Boolean

Example: Create two absences for different users

The HTTP POST method is used.

For the username1 user, a full-day vacation from July 1 to July 15, 2026, is created with the explicitly specified ID 68340a1f2b4c1a3d5e7f9011.

For the username2 user, a business trip from July 10 to July 20, 2026, is created, and the ID will be generated automatically.
POST /v3/gaps
Host: api.tracker.yandex.net
Authorization: OAuth y0__xAbc******
X-Org-ID: 1234******

{
 "gaps": [
   {
     "id": "68340a1f2b4c1a3d5e7f9011",
     "user": "username1",
     "workflow": "vacation",
     "from": "2026-07-01T00:00:00.000Z",
     "to": "2026-07-15T00:00:00.000Z",
     "fullDay": true,
     "workInAbsence": false
   },
   {
     "user": "username2",
     "workflow": "trip",
     "from": "2026-07-10T00:00:00.000Z",
     "to": "2026-07-20T00:00:00.000Z"
   }
 ]
}

Response format

Request executed successfully

Request executed with an error

If the request is successful, the API returns a response with code 200 OK.

The response body contains the results in JSON format. Only actually saved records are returned (outdated records are not included).

{
  "gaps": [
    {
      "id": "68340a1f2b4c1a3d5e7f9011",
      "user": {
        "self": "https://api.tracker.yandex.net/v3/users/1234567890123456",
        "uid": 1234567890123456,
        "login": "username1",
        "trackerUid": 1234567890123456,
        "passportUid": 1234567890,
        "cloudUid": "ajehs6sinuiii1234567",
        "firstName": "John",
        "lastName": "Smith",
        "display": "John Smith",
        "email": "username@example.com",
        "external": false,
        "dismissed": false,
        "firstLoginDate": "2024-04-10T10:15:47.272+0000",
        "lastLoginDate": "2026-07-23T08:11:01.861+0000",
        "sources": [
          "directory"
        ]
      },
      "workflow": "vacation",
      "from": "2026-07-01T00:00:00.000+0000",
      "to": "2026-07-15T00:00:00.000+0000",
      "fullDay": true,
      "workInAbsence": false
    },
    {
      "id": "68340a1f2b4c1a3d5e7f9012",
      "user": {
        "self": "https://api.tracker.yandex.net/v3/users/9876543210987654",
        "uid": 9876543210987654,
        "login": "username2",
        "trackerUid": 9876543210987654,
        "passportUid": 9876543210,
        "cloudUid": "ajehs6sinuiii9876543",
        "firstName": "John",
        "lastName": "Smith",
        "display": "Sam Brown",
        "email": "username@example.com",
        "external": false,
        "dismissed": false,
        "firstLoginDate": "2024-03-05T09:00:00.000+0000",
        "lastLoginDate": "2026-07-22T17:30:00.000+0000",
        "sources": [
          "directory"
        ]
      },
      "workflow": "trip",
      "from": "2026-07-10T00:00:00.000+0000",
      "to": "2026-07-20T00:00:00.000+0000",
      "fullDay": false,
      "workInAbsence": false
    }
  ]
}

Response parameters

Parameter	Description	Data type
gaps	Array of saved absence records	Array of objects

Array object fields gaps

Parameter	Description	Data type
id	Absence record ID	String
user	Object with information about the user	Object
workflow	Absence type	String
from	Absence start date and time in ISO 8601 format	String
to	Absence end date and time in ISO 8601 format	String
fullDay	Full-day flag	Boolean
workInAbsence	Working during absence flag	Boolean

Object fields user

Parameter	Description	Data type
self	Address of the API resource that contains information about the user	String
uid	Unique user ID	Number
login	User login	String
trackerUid	User ID in Tracker	Number
passportUid	Unique user account ID in Yandex ID	Number
cloudUid	Unique user ID in Yandex Identity Hub	String
firstName	User first name	String
lastName	User last name	String
display	User display name	String
email	User email address	String
external	External user flag	Boolean
dismissed	Dismissed employee flag	Boolean
firstLoginDate	Date and time of the user's first login to the system	String
lastLoginDate	Date and time of the user's last login to the system	String
sources	User data sources. Possible values: `directory` — profile obtained from the organization's corporate directory; `tracker` — user added directly to Tracker	Array of strings

If the request was not processed successfully, the API returns a response with an error code:

401: The user is not authorized. Make sure that actions described in the API access section are performed.

403: You are not authorized to perform this action. You can check what rights you have in the Tracker interface. The same rights are required to perform an action via the API and interface.

422: JSON validation error, the request is rejected.

The 422 code is returned in the following cases:

The request contains duplicate id values.
The from value is greater than or equal to to.
The user is not found.
The number of elements in the gaps array exceeds 100.

500: Internal service error. Try again later.

Was the article helpful?

Get information about users with relative pagination

Find absences