Skip to main content

Shifts

A shift is a period for planning agent work, for example a day or night shift. You can specify start and end time, shift recurrence, and lists of tasks and agents. Shifts can overlap: multiple shifts with agents (including the same agents) can run at the same time. For more information about shifts, see the Shifts section of the Administrator guide.

Getting the list of shifts​

You can get a list of shifts for a specified period with their data: ID, name, creation and update date and time, time zone, full-day flag, start date and time, and end date and time.

To get the list of shifts, send a GET request to /v1/shifts with the following parameters:

  • from - period start date and time in RFC 3339 format.
  • to - period end date and time in RFC 3339 format.
  • limit - maximum number of shifts in the response, from 1 to 100.

Request example:

curl --request GET \
   --url 'https://geoflow.2gis.ru/public/api/v1/shifts?from=2026-09-15T00:00:00Z&to=2026-09-17T00:00:00Z&limit=10' \
   --header 'Authorization: Bearer <token>'

Response example:

response.json
{
    "items": [
        {
            "id": "75692d4b-8da0-442e-a5a2-1c6ef561c7ad",
            "name": "Shift-1789456582",
            "start_at": "2026-09-15T07:16:25Z",
            "end_at": "2026-09-15T15:16:22Z",
            "timezone": "Asia/Novosibirsk",
            "full_day": false,
            "created_at": "2026-09-15T07:16:22.03358Z",
            "updated_at": "2026-09-15T07:16:34.400014Z"
        },
        {
            "id": "014c49db-76c5-43c4-9cd6-e7578b1dc573",
            "name": "Shift-1789456710",
            "start_at": "2026-09-15T07:18:32Z",
            "end_at": "2026-09-15T15:18:29Z",
            "timezone": "Asia/Novosibirsk",
            "full_day": false,
            "created_at": "2026-09-15T07:18:29.289052Z",
            "updated_at": "2026-09-15T07:18:41.726039Z"
        },
        {
            "id": "e820bf1f-9edd-4b76-a423-62b700efa92a",
            "name": "Shift-1789456828",
            "start_at": "2026-09-15T07:20:30Z",
            "end_at": "2026-09-15T15:20:27Z",
            "timezone": "Asia/Novosibirsk",
            "full_day": false,
            "created_at": "2026-09-15T07:20:27.251107Z",
            "updated_at": "2026-09-15T07:20:39.597549Z"
        },
        {
            "id": "a494744d-44b8-41ac-a3a9-80d37299b398",
            "name": "Shift-1789566599",
            "start_at": "2026-09-16T13:50:01Z",
            "end_at": "2026-09-16T21:49:58Z",
            "timezone": "Asia/Novosibirsk",
            "full_day": false,
            "created_at": "2026-09-16T13:49:58.004265Z",
            "updated_at": "2026-09-16T13:50:01.591082Z"
        }
    ],
    "cursor": {}
}

Getting a shift by ID​

You can get shift data by its ID: name, creation and update date and time, time zone, start date and time, end date and time, and whether the shift lasts the entire day.

To get shift data, send a GET request to /v1/shifts/{id}, where {id} is the shift ID.

Request example:

curl --request GET \
   --url 'https://geoflow.2gis.ru/public/api/v1/shifts/26307c36-6aad-47d5-8e8b-0425f96f9b27' \
   --header 'Authorization: Bearer <token>'

Response example:

response.json
{
    "id": "26307c36-6aad-47d5-8e8b-0425f96f9b27",
    "name": "Morning shift",
    "start_at": "2026-09-18T10:00:00Z",
    "end_at": "2026-09-18T18:00:00Z",
    "timezone": "Europe/Moscow",
    "full_day": false,
    "created_at": "2026-09-17T09:32:53.603679Z",
    "updated_at": "2026-09-17T09:32:53.603679Z"
}

Creating a shift​

To create a shift, send a POST request to /v1/shifts with the following parameters:

  • name (mandatory parameter) - shift name.
  • timezone (mandatory parameter) - time zone in IANA format (for example, Europe/Moscow).
  • start_at - shift start date and time in RFC 3339 format.
  • end_at - shift end date and time in RFC 3339 format.
  • full_day - flag indicating that the shift lasts 24 hours (matches the All day checkbox in the administrator web panel).

Request example:

curl --request POST \
   --url 'https://geoflow.2gis.ru/public/api/v1/shifts' \
   --header 'Authorization: Bearer <token>' \
   --header 'Content-Type: application/json' \
   --data '{
      "name": "Morning shift",
      "timezone": "Europe/Moscow",
      "start_at": "2026-09-18T10:00:00Z",
      "end_at": "2026-09-18T18:00:00Z",
      "full_day": false
   }'

Response example:

response.json
{
    "id": "26307c36-6aad-47d5-8e8b-0425f96f9b27",
    "name": "Morning shift",
    "start_at": "2026-09-18T10:00:00Z",
    "end_at": "2026-09-18T18:00:00Z",
    "timezone": "Europe/Moscow",
    "full_day": false,
    "created_at": "2026-09-17T09:32:53.603679Z",
    "updated_at": "2026-09-17T09:32:53.603679Z"
}

Updating a shift​

To update shift data, send a PUT request to /v1/shifts/{id}, where {id} is the shift ID, and pass new data in the request body.

Request example:

curl --request PUT \
   --url 'https://geoflow.2gis.ru/public/api/v1/shifts/26307c36-6aad-47d5-8e8b-0425f96f9b27' \
   --header 'Authorization: Bearer <token>' \
   --header 'Content-Type: application/json' \
   --data '{
      "name": "Day shift",
      "timezone": "Europe/Moscow",
      "start_at": "2026-09-20T12:00:00Z",
      "end_at": "2026-09-20T17:00:00Z",
      "full_day": false
   }'

Response example:

response.json
{
    "id": "26307c36-6aad-47d5-8e8b-0425f96f9b27",
    "name": "Day shift",
    "start_at": "2026-09-20T12:00:00Z",
    "end_at": "2026-09-20T17:00:00Z",
    "timezone": "Europe/Moscow",
    "full_day": false,
    "created_at": "2026-09-17T09:32:53.603679Z",
    "updated_at": "2026-09-17T09:41:47.02996Z"
}

Deleting a shift​

warning

You cannot restore a deleted shift.

To delete a shift, send a DELETE request to /v1/shifts/{id}, where {id} is the shift ID.

Request example:

curl --request DELETE \
   --url 'https://geoflow.2gis.ru/public/api/v1/shifts/26307c36-6aad-47d5-8e8b-0425f96f9b27' \
   --header 'Authorization: Bearer <token>'

If deletion is successful, the response status is 204 No Content.

Getting shift assignments​

You can get the list of agents added to a shift and the list of shift tasks with assigned agents.

To get shift assignments, send a GET request to /v1/shifts/{id}/assignments, where {id} is the shift ID.

Request example:

curl --request GET \
   --url 'https://geoflow.2gis.ru/public/api/v1/shifts/75692d4b-8da0-442e-a5a2-1c6ef561c7ad/assignments' \
   --header 'Authorization: Bearer <token>'

Response example:

response.json
{
    "shift_id": "75692d4b-8da0-442e-a5a2-1c6ef561c7ad",
    "agent_assignments": [
        {
            "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978"
        }
    ],
    "task_assignments": [
        {
            "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
            "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
            "created_at": "2026-09-15T07:20:39.597549Z",
            "updated_at": "2026-09-15T07:20:39.597549Z"
        }
    ]
}

Updating shift assignments​

You can update shift assignments: the list of agents and tasks.

To update shift assignments, send a POST request to /v1/shifts/{id}/assignments, where {id} is the shift ID, with the following parameters:

  • agent_ids - list of agent IDs to add to the shift.

  • task_assignments - list of task assignments:

    • task_id (mandatory parameter) - task ID.
    • agent_id - ID of the agent assigned to the task.

Request example:

curl --request POST \
   --url 'https://geoflow.2gis.ru/public/api/v1/shifts/75692d4b-8da0-442e-a5a2-1c6ef561c7ad/assignments' \
   --header 'Authorization: Bearer <token>' \
   --header 'Content-Type: application/json' \
   --data '{
      "agent_ids": [
         "82fb1fd7-9a98-4f49-81fa-2f380a8cba0e"
      ],
      "task_assignments": [
         {
            "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
            "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978"
         }
      ]
   }'

Response example:

response.json
{
   "shift_id": "75692d4b-8da0-442e-a5a2-1c6ef561c7ad",
   "agent_assignments": [
      {
         "agent_id": "82fb1fd7-9a98-4f49-81fa-2f380a8cba0e"
      },
      {
         "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978"
      }
   ],
   "task_assignments": [
      {
         "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
         "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
         "created_at": "2026-09-18T09:42:11Z",
         "updated_at": "2026-09-18T09:42:11Z"
      }
   ]
   }