Custom route fields

To consider route information that is not covered by the standard fields, you can create custom fields custom_fields.

Attention.

This feature is only available in the API.

To add and delete fields, contact support. You can also ask which custom fields have already been added.

When working with custom fields, note the following:

You can only apply fields to a route that have been added in the company settings.
The user determines the field format and content on their own.
No more than 10 fields can be added for one company.
The maximum length of the field, including the name and value, is 255 characters.
If you delete a field, it will remain in routes that have already been created.
If you edit a route, only the fields in the request will be saved. All other fields will be deleted from the route.

Custom fields are displayed:

In the Map section.

Example
In the courier card.

Example
In the Courier performance report.

Example

Creating a route

To create a route with custom fields:

Contact support and tell them the names of the fields to add. For example, route_type and route_priority.
Send a POST request to the routes resource. Go to the custom_fields array element. Enter the name in the key field and the value in the value field. In the sample request below, we'll enter the value intercity for route_type and 0 for route_priority.

Query

cURL

curl -H "Content-Type: application/json" -H "Authorization: Auth your-token" -X POST -d @<File_path_in_UTF-8_encoding> https://courier.yandex.ru/api/v1/companies/<your-company-id>/routes
Copied to clipboard

File

{
    "courier_number": "Courier 1",
    "date": "2022-05-12",
    "number": "add-custom-fields",
    "depot_number": "111",
    "route_start": "8:00:00",
    "route_finish": "19:00:00",
    "custom_fields": [
        {
            "key": "route_type",
            "value": "intercity"
        },
        {
            "key": "route_priority",
            "value": "0"
        }
    ]
}
Copied to clipboard

Result

{
    "id": <route-id>,
    "company_id": <your-company-id>,
    "courier_id": <courier-id>,
    "car_id": null,
    "custom_fields": [
        {
            "key": "route_type",
            "value": "intercity"
        },
        {
            "key": "route_priority",
            "value": "0"
        }
    ],
    "depot_id": <depot-id>,
    "number": "add-custom-fields",
    "date": "2022-05-12",
    "imei": null,
    "rented_courier_id": null,
    "courier_violated_route": false,
    "routing_mode": "driving",
    "tracking_start_h": null,
    "route_start": "08:00:00",
    "route_finish": "19:00:00",
    "imei_str": null
}
Copied to clipboard

Editing a route

To change custom field values, send a PATCH request to the routes resource. For example, you can leave only the route_priority field with the value 1 in the route.

Query

cURL

curl -H "Content-Type: application/json" -H "Authorization: Auth your-token" -X PATCH -d @<File_path_in_UTF-8_encoding> https://courier.yandex.ru/api/v1/companies/<your-company-id>/routes/<route-id>
Copied to clipboard

File

{
    "courier_number": "Courier 1",
    "date": "2022-05-12",
    "number": "add-custom-fields",
    "depot_number": "111",
    "route_start": "8:00:00",
    "route_finish": "19:00:00",
    "custom_fields": [
        {
            "key": "route_priority",
            "value": "1"
        }
    ]
}
Copied to clipboard

Result

{
    "id": <route-id>,
    "company_id": <your-company-id>,
    "courier_id": <courier-id>,
    "car_id": null,
    "custom_fields": [
        {
            "key": "route_priority",
            "value": "1"
        }
    ],
    "depot_id": <depot-id>,
    "number": "add-custom-fields",
    "date": "2022-05-12",
    "imei": null,
    "rented_courier_id": null,
    "courier_violated_route": false,
    "routing_mode": "driving",
    "tracking_start_h": null,
    "route_start": "08:00:00",
    "route_finish": "19:00:00",
    "imei_str": null
}
Copied to clipboard

Getting a route

To get routes with custom field values, send a GET request to the routes resource.

Query

cURL

curl -H "Content-Type: application/json" -H "Authorization: Auth your-token" -X GET -d @<File_path_in_UTF-8_encoding> https://courier.yandex.ru/api/v1/companies/<your-company-id>/routes
Copied to clipboard

Result

[
    {
        "id": <route-id>,
        "company_id": <your-company-id>,
        "courier_id": <courier-id>,
        "car_id": null,
        "custom_fields": [
            {
                "key": "route_priority",
                "value": "1"
            }
        ],
        "depot_id": <depot-id>,
        "number": "add-custom-fields",
        "date": "2022-05-12",
        "imei": null,
        "rented_courier_id": null,
        "courier_violated_route": false,
        "routing_mode": "driving",
        "tracking_start_h": null,
        "route_start": "08:00:00",
        "route_finish": "19:00:00",
        "imei_str": null
    }
]
Copied to clipboard

Contact support