Tasks
You can create tasks for agents, for example: deliver cargo, conduct inspections, etc. For more information about tasks, see the Tasks section of the Administrator guide.
Getting the list of tasks
You can get a list of tasks with their data: task ID, template ID, status, creation and update date and time, and a list of attributes.
To get the list of tasks, send a GET request to /v1/tasks with the limit parameter - the maximum number of tasks in the response (from 1 to 100).
Request example:
curl --request GET \
--url 'https://geoflow.2gis.ru/public/api/v1/tasks?limit=2' \
--header 'Authorization: Bearer <token>'
Response example:
response.json
{
"items": [
{
"id": "d86f6491-d873-4802-bdb5-ba354245d33e",
"template_id": "eaacda1f-251e-40a5-9d2d-b4cba2d462c3",
"attributes": [
{
"data": {
"attribute_id": "d227f3d3-0c17-409e-9820-8e4f713be6e6",
"type": "name",
"value": "Task 814"
}
},
{
"data": {
"attribute_id": "9aa20ffb-e130-44a4-8fdf-03ae30ba226b",
"type": "description",
"value": "Grocery"
}
},
{
"data": {
"attribute_id": "bc53e352-f052-4a40-bea6-8c5267541430",
"type": "time_windows_settings",
"value": {
"timezone": "Asia/Novosibirsk",
"time_windows": [
{
"from": "2026-08-25T05:22:00.000Z",
"to": "2026-08-25T15:22:00.000Z"
}
],
"is_hard": false
}
}
},
{
"data": {
"attribute_id": "8bc4e8b0-3409-44d5-aad9-069ed1033b5f",
"type": "phone",
"value": "+7 (999) 999-99-99"
}
}
],
"status_alias": "created",
"created_at": "2026-06-15T08:40:34.201829Z",
"updated_at": "2026-08-24T08:10:03.423399Z"
},
{
"id": "782700da-3370-444e-9cae-f13c80cf6cf2",
"template_id": "eaacda1f-251e-40a5-9d2d-b4cba2d462c3",
"attributes": [
{
"data": {
"attribute_id": "d227f3d3-0c17-409e-9820-8e4f713be6e6",
"type": "name",
"value": "Task 815"
}
},
{
"data": {
"attribute_id": "bc53e352-f052-4a40-bea6-8c5267541430",
"type": "time_windows_settings",
"value": {
"timezone": "Asia/Novosibirsk",
"time_windows": [
{
"from": "2026-08-25T05:22:00.000Z",
"to": "2026-08-25T08:55:00.000Z"
}
],
"is_hard": false
}
}
},
{
"data": {
"attribute_id": "9aa20ffb-e130-44a4-8fdf-03ae30ba226b",
"type": "description",
"value": "Grocery 2"
}
}
],
"status_alias": "created",
"created_at": "2026-06-15T08:40:34.210945Z",
"updated_at": "2026-08-24T08:10:34.501092Z"
}
],
"cursor": {}
}
Each attribute contains an ID, type, and value.
Getting a task by ID
You can get task data by ID: template ID, status, creation and update date and time, and a list of attributes.
To get task data, send a GET request to /v1/tasks/{id}, where {id} is the task ID.
Request example:
curl --request GET \
--url 'https://geoflow.2gis.ru/public/api/v1/tasks/402ed0c2-e7a5-404e-bee2-e1695ec65bb2' \
--header 'Authorization: Bearer <token>'
Response example:
response.json
{
"id": "402ed0c2-e7a5-404e-bee2-e1695ec65bb2",
"template_id": "eaacda1f-251e-40a5-9d2d-b4cba2d462c3",
"attributes": [
{
"data": {
"attribute_id": "8c8c5809-3cdf-41a3-bf19-9c47bf45aad9",
"type": "text",
"value": "Task 12136"
}
},
{
"data": {
"attribute_id": "d227f3d3-0c17-409e-9820-8e4f713be6e6",
"type": "name",
"value": "Inspection"
}
},
{
"data": {
"attribute_id": "9aa20ffb-e130-44a4-8fdf-03ae30ba226b",
"type": "description",
"value": "Grocery"
}
},
{
"data": {
"attribute_id": "bc53e352-f052-4a40-bea6-8c5267541430",
"type": "time_windows_settings",
"value": {
"timezone": "Asia/Novosibirsk",
"time_windows": [
{
"from": "2026-08-26T05:22:00.000Z",
"to": "2026-08-26T08:06:00.000Z"
}
],
"is_hard": false
}
}
},
{
"data": {
"attribute_id": "8bc4e8b0-3409-44d5-aad9-069ed1033b5f",
"type": "phone",
"value": "+7 (999) 999-99-99"
}
}
],
"status_alias": "created",
"created_at": "2026-06-15T08:40:34.216738Z",
"updated_at": "2026-08-24T08:10:53.13097Z"
}
Each attribute contains an ID, type, and value.
Creating a task
To create a task, send a POST request to /v1/tasks with the following parameters:
-
template_id(mandatory parameter) - ID of the task template. -
attributes(mandatory parameter) - list of task attributes. Eachdataobject must contain:attribute_id(mandatory parameter) - attribute ID specified in the task template.type(mandatory parameter) - attribute type specified in the task template.value- attribute value.
Request example:
curl --request POST \
--url 'https://geoflow.2gis.ru/public/api/v1/tasks' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"template_id": "eaacda1f-251e-40a5-9d2d-b4cba2d462c3",
"attributes": [
{
"data": {
"attribute_id": "d227f3d3-0c17-409e-9820-8e4f713be6e6",
"type": "name",
"value": "Task"
}
},
{
"data": {
"attribute_id": "bc53e352-f052-4a40-bea6-8c5267541430",
"type": "time_windows_settings",
"value": {
"timezone": "Europe/Moscow",
"time_windows": [
{
"from": "2026-09-20T09:00:00Z",
"to": "2026-09-20T12:00:00Z"
}
]
}
}
}
]
}'
Response example:
response.json
{
"id": "d510b69a-ce4b-4c6f-bd8b-76c1da962a84",
"template_id": "eaacda1f-251e-40a5-9d2d-b4cba2d462c3",
"attributes": [
{
"data": {
"attribute_id": "8c8c5809-3cdf-41a3-bf19-9c47bf45aad9",
"type": "text",
"value": "T-316"
}
},
{
"data": {
"attribute_id": "d227f3d3-0c17-409e-9820-8e4f713be6e6",
"type": "name",
"value": "Task"
}
},
{
"data": {
"attribute_id": "bc53e352-f052-4a40-bea6-8c5267541430",
"type": "time_windows_settings",
"value": {
"timezone": "Europe/Moscow",
"time_windows": [
{
"from": "2026-09-20T09:00:00Z",
"to": "2026-09-20T12:00:00Z"
}
],
"is_hard": false
}
}
}
],
"status_alias": "created",
"created_at": "2026-09-17T11:52:43.826551Z",
"updated_at": "2026-09-17T11:52:43.826551Z"
}
Updating a task
To update task data, send a PUT request to /v1/tasks/{id}, where {id} is the task ID, and pass new data in the request body.
Request example:
curl --request PUT \
--url 'https://geoflow.2gis.ru/public/api/v1/tasks/da6e2e9b-3152-4425-a330-abb1fca5956b' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"id": "da6e2e9b-3152-4425-a330-abb1fca5956b",
"attributes": [
{
"data": {
"attribute_id": "d227f3d3-0c17-409e-9820-8e4f713be6e6",
"type": "name",
"value": "Task 1"
}
}
]
}'
Response example:
response.json
{
"id": "da6e2e9b-3152-4425-a330-abb1fca5956b",
"template_id": "eaacda1f-251e-40a5-9d2d-b4cba2d462c3",
"attributes": [
{
"data": {
"attribute_id": "d227f3d3-0c17-409e-9820-8e4f713be6e6",
"type": "name",
"value": "Task 1"
}
}
],
"status_alias": "created",
"created_at": "2026-09-22T13:01:10.648376Z",
"updated_at": "2026-09-22T13:01:54.321587Z"
}
Updating task status
To update task status, send a PUT request to /v1/tasks/{id}/status, where {id} is the task ID, with the status_alias parameter - the new task status.
Available task statuses:
created- createdready- ready to performin_progress- in progresscompleted- completedcancelled- cancelled
Request example:
curl --request PUT \
--url 'https://geoflow.2gis.ru/public/api/v1/tasks/d510b69a-ce4b-4c6f-bd8b-76c1da962a84/status' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"status_alias": "completed"
}'
Response example:
response.json
{
"id": "d510b69a-ce4b-4c6f-bd8b-76c1da962a84",
"template_id": "eaacda1f-251e-40a5-9d2d-b4cba2d462c3",
"attributes": [
{
"data": {
"attribute_id": "8c8c5809-3cdf-41a3-bf19-9c47bf45aad9",
"type": "text",
"value": "T-316"
}
},
{
"data": {
"attribute_id": "d227f3d3-0c17-409e-9820-8e4f713be6e6",
"type": "name",
"value": "Task 1"
}
},
{
"data": {
"attribute_id": "bc53e352-f052-4a40-bea6-8c5267541430",
"type": "time_windows_settings",
"value": {
"timezone": "Europe/Moscow",
"time_windows": [
{
"from": "2026-09-20T09:00:00Z",
"to": "2026-09-20T12:00:00Z"
}
],
"is_hard": false
}
}
}
],
"status_alias": "completed",
"created_at": "2026-09-17T11:52:43.826551Z",
"updated_at": "2026-09-18T09:47:18.260846Z"
}