Custom route fields

If you need to track route information that doesn't fit in the standard fields, you can create custom fields custom_fields.

Warning

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 if they 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 still remain in previously created routes.
  • If you edit a route, only the fields in the request will be saved. All other fields are 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:

  1. Contact support and tell them the names of the fields to add. For example, route_type and route_priority.
  2. 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: OAuth <your-token>" -X POST -d @<File_path_in_UTF-8_encoding> https://courier.yandex.ru/api/v1/companies/<your-company-id>/routes

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"
        }
    ]
}

Result

{
    "id": <route-id>,
    "company_id": <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
}

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: OAuth <your-token>" -X PATCH -d @<File_path_in_UTF-8_encoding> https://courier.yandex.ru/api/v1/companies/<your-company-id>/routes/<route-id>

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"
        }
    ]
}

Result

{
    "id": <route-id>,
    "company_id": <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
}

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: OAuth <your-token>" -X GET -d @<File_path_in_UTF-8_encoding> https://courier.yandex.ru/api/v1/companies/<your-company-id>/routes

Result

[
    {
        "id": <route-id>,
        "company_id": <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
    }
]
Contact support
Previous
Working with graphs
Next
Order items