Skip to main content

Agents

Agents perform work tasks, are used in shift planning, and are tracked during shift monitoring. Agents can be mobile employees (for example, operators and couriers), special vehicles, etc. For more information about agents, see the Agents section of the Administrator guide.

Getting the list of agents​

You can get a list of agents with their data: agent ID, template ID, creation and update date and time, data sources of agent location, and attributes.

To get the list of agents, send a GET request to /v1/agents with the limit parameter - the maximum number of agents in the response (from 1 to 500).

Request example:

curl --request GET \
   --url 'https://geoflow.2gis.ru/public/api/v1/agents?limit=2' \
   --header 'Authorization: Bearer <token>'

Response example:

response.json
{
    "items": [
        {
            "id": "82fb1fd7-9a98-4f49-81fa-2f380a8cba0e",
            "template_id": "ab836921-2273-4f3a-b4a9-e16bc1bc2b32",
            "attributes": [
                {
                    "data": {
                        "attribute_id": "1b9c78db-a18a-48b5-a18d-9c9e226bf4f3",
                        "type": "text",
                        "value": "Agent 1"
                    }
                },
                {
                    "data": {
                        "attribute_id": "c481e304-6703-4613-acfc-396827093900",
                        "type": "transport_type",
                        "value": "driving"
                    }
                },
                {
                    "data": {
                        "attribute_id": "c8c71b26-5f28-4483-9b11-8af3dbde1646",
                        "type": "phone"
                    }
                },
                {
                    "data": {
                        "attribute_id": "3e5f4c07-ad6e-46bb-9fb9-494455730fc9",
                        "type": "email"
                    }
                },
                {
                    "data": {
                        "attribute_id": "4810aee3-fa00-424b-9447-3c4040774bc3",
                        "type": "text"
                    }
                },
                {
                    "data": {
                        "attribute_id": "c73e85cb-55e6-4034-8e1e-4082a5f7ec41",
                        "type": "number"
                    }
                },
                {
                    "data": {
                        "attribute_id": "9e355c34-b3b9-44e3-a74c-85ee92fc9a0c",
                        "type": "dictionary"
                    }
                },
                {
                    "data": {
                        "attribute_id": "4c09a015-490b-4632-b6ca-459c7425b349",
                        "type": "skill"
                    }
                },
                {
                    "data": {
                        "attribute_id": "e10f2a50-ee03-4342-924a-75c86f965a20",
                        "type": "boolean",
                        "value": false
                    }
                }
            ],
            "data_sources": [
                {
                    "type": "mobile",
                    "value": {
                        "type": "mobile",
                        "user_id": "1781787890"
                    }
                }
            ],
            "created_at": "2026-08-28T07:17:45.198058Z",
            "updated_at": "2026-09-15T10:16:01.684857Z"
        },
        {
            "id": "06999587-d9d0-4ad9-b1a5-11ab8e140b4c",
            "template_id": "ab836921-2273-4f3a-b4a9-e16bc1bc2b32",
            "attributes": [
                {
                    "data": {
                        "attribute_id": "1b9c78db-a18a-48b5-a18d-9c9e226bf4f3",
                        "type": "text",
                        "value": "Agent 2"
                    }
                },
                {
                    "data": {
                        "attribute_id": "c481e304-6703-4613-acfc-396827093900",
                        "type": "transport_type",
                        "value": "driving"
                    }
                },
                {
                    "data": {
                        "attribute_id": "c8c71b26-5f28-4483-9b11-8af3dbde1646",
                        "type": "phone"
                    }
                },
                {
                    "data": {
                        "attribute_id": "3e5f4c07-ad6e-46bb-9fb9-494455730fc9",
                        "type": "email"
                    }
                },
                {
                    "data": {
                        "attribute_id": "4810aee3-fa00-424b-9447-3c4040774bc3",
                        "type": "text"
                    }
                },
                {
                    "data": {
                        "attribute_id": "c73e85cb-55e6-4034-8e1e-4082a5f7ec41",
                        "type": "number"
                    }
                },
                {
                    "data": {
                        "attribute_id": "9e355c34-b3b9-44e3-a74c-85ee92fc9a0c",
                        "type": "dictionary"
                    }
                },
                {
                    "data": {
                        "attribute_id": "4c09a015-490b-4632-b6ca-459c7425b349",
                        "type": "skill"
                    }
                },
                {
                    "data": {
                        "attribute_id": "e10f2a50-ee03-4342-924a-75c86f965a20",
                        "type": "boolean",
                        "value": false
                    }
                }
            ],
            "data_sources": [
                {
                    "type": "mobile",
                    "value": {
                        "type": "mobile",
                        "user_id": "1234567890"
                    }
                }
            ],
            "created_at": "2026-08-28T07:18:36.883661Z",
            "updated_at": "2026-09-15T10:14:38.975109Z"
        }
    ],
    "cursor": {}
}

Each data source contains a source type and the ID of a user or a tracking device. Each attribute contains an ID, type, and value.

Getting an agent by ID​

You can get agent data by ID: template ID, creation and update date and time, data sources of agent location, and attributes.

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

Request example:

curl --request GET \
   --url 'https://geoflow.2gis.ru/public/api/v1/agents/56ca1414-3d9b-4167-9fa1-646576fe9227' \
   --header 'Authorization: Bearer <token>'

Response example:

response.json
{
    "id": "56ca1414-3d9b-4167-9fa1-646576fe9227",
    "template_id": "af5e5d63-10f0-4ea0-b520-ddb36af1a59c",
    "attributes": [
        {
            "data": {
                "attribute_id": "6653466e-1f20-485c-928e-c18b4bffedbc",
                "type": "text",
                "value": "Ivan Ivanov"
            }
        },
        {
            "data": {
                "attribute_id": "1efd0fb1-7216-4d69-8baf-4470570de40b",
                "type": "transport_type",
                "value": "walking"
            }
        }
    ],
    "data_sources": [
        {
            "type": "mobile",
            "value": {
                "type": "mobile",
                "user_id": "590cef82-d71f-48a1-8f81-3118db444b92"
            }
        }
    ],
    "created_at": "2026-09-17T13:39:03.456105Z",
    "updated_at": "2026-09-17T13:39:03.456105Z"
}

Each data source contains a source type and the ID of a user or a tracking device. Each attribute contains an ID, type, and value.

Creating an agent​

To create an agent, send a POST request to /v1/agents with the following parameters:

  • template_id (mandatory parameter) - ID of the agent template.

  • attributes - list of agent attributes. Each data object must contain:

    • attribute_id (mandatory parameter) - attribute ID specified in the agent template.
    • type (mandatory parameter) - attribute type specified in the agent template.
    • value - attribute value.

  • data_sources - list of data sources of agent location. Each value object must contain:

    • type (mandatory parameter) - data source type: mobile (mobile application) or device (tracking device).
    • user_id or device_id (mandatory parameter) - depending on the data source type: user ID in the mobile application or ID of the tracking device.

Request example:

curl --request POST \
   --url 'https://geoflow.2gis.ru/public/api/v1/agents' \
   --header 'Authorization: Bearer <token>' \
   --header 'Content-Type: application/json' \
   --data '{
      "template_id": "af5e5d63-10f0-4ea0-b520-ddb36af1a59c",
      "attributes": [
         {
            "data": {
               "attribute_id": "6653466e-1f20-485c-928e-c18b4bffedbc",
               "type": "text",
               "value": "Ivan Ivanov"
            }
         },
         {
            "data": {
               "attribute_id": "1efd0fb1-7216-4d69-8baf-4470570de40b",
               "type": "transport_type",
               "value": "walking"
            }
         }
      ],
      "data_sources": [
         {
            "type": "mobile",
            "value": {
               "type": "mobile",
               "user_id": "590cef82-d71f-48a1-8f81-3118db444b92"
            }
         }
      ]
   }'

Response example:

response.json
{
    "id": "56ca1414-3d9b-4167-9fa1-646576fe9227",
    "template_id": "af5e5d63-10f0-4ea0-b520-ddb36af1a59c",
    "attributes": [
        {
            "data": {
                "attribute_id": "6653466e-1f20-485c-928e-c18b4bffedbc",
                "type": "text",
                "value": "Ivan Ivanov"
            }
        },
        {
            "data": {
                "attribute_id": "1efd0fb1-7216-4d69-8baf-4470570de40b",
                "type": "transport_type",
                "value": "walking"
            }
        }
    ],
    "data_sources": [
        {
            "type": "mobile",
            "value": {
                "type": "mobile",
                "user_id": "590cef82-d71f-48a1-8f81-3118db444b92"
            }
        }
    ],
    "created_at": "2026-09-17T13:39:03.456105Z",
    "updated_at": "2026-09-17T13:39:03.456105Z"
}

Updating an agent​

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

Request example:

curl --request PUT \
   --url 'https://geoflow.2gis.ru/public/api/v1/agents/b70ebe82-6af7-4731-a4c7-7f2f5acc3387' \
   --header 'Authorization: Bearer <token>' \
   --header 'Content-Type: application/json' \
   --data '{
      "template_id": "af5e5d63-10f0-4ea0-b520-ddb36af1a59c",
      "attributes": [
         {
            "data": {
               "attribute_id": "6653466e-1f20-485c-928e-c18b4bffedbc",
               "type": "text",
               "value": "Ivan Petrov"
            }
         }
      ]
   }'

Response example:

response.json
{
    "id": "b70ebe82-6af7-4731-a4c7-7f2f5acc3387",
    "template_id": "af5e5d63-10f0-4ea0-b520-ddb36af1a59c",
    "attributes": [
        {
            "data": {
                "attribute_id": "6653466e-1f20-485c-928e-c18b4bffedbc",
                "type": "text",
                "value": "Ivan Petrov"
            }
        },
        {
            "data": {
                "attribute_id": "1efd0fb1-7216-4d69-8baf-4470570de40b",
                "type": "transport_type",
                "value": "walking"
            }
        }
    ],
    "data_sources": [],
    "created_at": "2026-09-17T12:18:07.608161Z",
    "updated_at": "2026-09-17T12:20:32.277239Z"
}

Deleting an agent​

warning

An agent will be removed from shifts and tasks. You cannot restore a deleted agent.

To delete an agent, send a DELETE request to /v1/agents/{id}, where {id} is the agent ID.

Request example:

curl --request DELETE \
   --url 'https://geoflow.2gis.ru/public/api/v1/agents/b70ebe82-6af7-4731-a4c7-7f2f5acc3387' \
   --header 'Authorization: Bearer <token>'

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