---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://yandex.com/support/delivery-profile/en/api/express/faq.md
  - https://yandex.com/support/delivery-profile/ru/api/express/faq.md
  - href: en/api/express/faq.md
    type: text/markdown
    title: Markdown version
  - href: ../../llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/support/delivery-profile/en/llms.txt

# FAQ

## Handling claims {#claim}

### Creating claims {#claim-create}

#### 1. What is a request_id? Why does the method sometimes return information about a previously created claim? {#claim-create-request_id}

The `request_id` is a unique claim ID or idempotency attribute used to distinguish the claim from other claims.

Each new claim must have its own `request_id` that's different from all previous claims. When an old `request_id` value is used, the method returns information about the old order regardless of the claim body. Only use an old `request_id` value when trying to create a specific claim again after server errors with `5xx` codes.

The `request_id` value can include letters, numbers, and other characters. To guarantee that values are unique, we recommend using the `uuid` format and its derivatives.

#### 2. How do I choose a service class and vehicle type? {#claim-create-client_requirements}

If you specify the cargo weight and dimensions in your claim, the system selects a suitable vehicle automatically.

You can also choose a service class and options yourself. To do this, send the appropriate values in the `client_requirements` parameter:

* **Service class** (`taxi_class`):

  * "Courier" — `courier`;

  * "Express" — `express`;

  * "Cargo" — `cargo`. For `cargo`, also specify the **Vehicle size** (`cargo_type`):

     * "Small vehicle" — `van`;

     * "Medium vehicle" — `lcv_m`;

     * "Large vehicle" — `lcv_l`.

* **Number of loaders** (`cargo_loaders`): 1 or 2 (`integer` type).

* **Additional options** (`cargo_options`):

  * "Insulated bag" — `thermobag`;

  * "Only driver courier" — `auto_courier`.

If the system determines that the items to be delivered don't fit the selected vehicle (for example, the cargo is too large or load capacity is exceeded), the response will include a warning with the `not_fit_in_car` code in addition to the `ready_for_approval` status.

**Cargo weight:**

* "Courier" (`courier`): Up to 10 kg;

* "Express" (`express`): Up to 20 kg;

* "Cargo" (`cargo`):

  * "Small vehicle": Up to 300 kg;

  * "Medium vehicle": Up to 700 kg;

  * "Large vehicle": Up to 1400 kg.

**Cargo dimensions (LxWxH format):**

* "Courier" (`courier`): Up to 0.80 m × 0.50 m × 0.50 m;

* "Express" (`express`): Up to 1.00 m × 0.60 m × 0.50 m;

* "Cargo" (`cargo`):

  * "Small vehicle": Up to 1.70 m × 0.96 m × 0.90 m;

  * "Medium vehicle": Up to 2.60 m × 1.30 m × 1.50 m;

  * "Large vehicle": Up to 3.80 m × 1.80 m × 1.80 m.

#### 3. How do I place a scheduled trip claim? {#claim-create-due}

By default, when you create a claim, the courier is claimed for the nearest time (the `due` field isn't sent). If you need to create a scheduled trip claim, send the date and time of the courier's arrival to the pickup location in the `due` field.

#### 4. Do I need to send the item price and currency that the price is specified in? {#claim-create-cost}

The `items[].cost_value` item price and `items[].cost_currency` currency fields must be filled in. You can't create a claim if they are empty. If you don't know the price, you can send `"cost_value": "0"`, `"cost_currency": "RUB"`.

#### 5. Do I need to send the item dimensions and weight? {#claim-create-size}

If the vehicle type is determined automatically (the `taxi_class` isn't set), you must send item dimensions and weight.

If the `taxi_class` field is specified, you don't have to send the item dimensions and weight. However, we still recommend describing the item dimensions and weight considering the restrictions of the `items[].size` and `items[].weight` fields to avoid an error when choosing transportation.

Dimensions are specified in meters, and weight is specified in kilograms.

#### 6. Which format should I use to send phone numbers? {#claim-create-phone}

Phone numbers should be in the following format: +79123456789.

#### 7. Do I need to send coordinates? {#claim-create-coordinates}

This is a mandatory field. You need to send correct coordinates because they're used to create route points. Note that you need to send coordinates (the `route_points[].address.coordinates[]` field) in the order [longitude, latitude] to avoid claim evaluation errors.

#### 8. What's the right way to set the order of delivery locations? {#claim-create-visit order}

The `route_points[].visit_order` field sets the sequence number of the location on the route. The location where the courier needs to to pick up the item is always number 1. The next point where the courier needs to deliver the item is number 2, and so on. The final location (item return point) is added automatically and defaults to the point of departure unless a different address is specified.

#### 9. How do I send additional information to the courier? {#claim-create-comment}

We recommend sending a comment to the courier so they can find the sender and recipient faster. Send information for the courier either in the general trip comment (`comment`) or in the point comments (`route_points[].address.comment`).

Examples of comments are available in the [documentation](https://yandex.com/support/delivery-profile/en/api/express/openapi/IntegrationV2ClaimsCreate.md).

#### 10. How do I specify the code that the courier needs to pick up the order at the warehouse? {#claim-create-warehouse-code}

You can send the code as a comment in the `source` point. The courier will only see comments to all points after being assigned the trip claim.

#### 11. How does the sender know which order the courier has arrived to pick up? How does the courier know which order at which point to hand over to the recipient? Where do I specify the internal order number? {#claim-create-order}

Each route point has its own ID `route_points[].point_id` — an arbitrarily set integer. When you fill in the item information, the values of the `items[].pickup_point` (item pickup point) and `items[].droppof_point` (item delivery point) fields match the `route_points[].point_id` values of the pickup point and delivery point.

You can send the order number in the `route_points[].external_order_id` field of the claim creation method and duplicate it in the `items[].extra_id` field. In the `items[].extra_id` field, you can specify another possible item ID.

{% note warning %}

You can only send the internal order number in the section of fields related to the array of point B (item delivery point).

{% endnote %}

If the `external_order_id` field is filled in, the courier will see the order numbers when picking up the order and can confirm them with the sender.

You can send any additional information in the general order comment and in the point comments.

#### 12. How do I specify special trip requirements? {#claim-create-cargo_options}

In the Courier service class, you can choose an insulated bag and/or a driver courier. To do this, send the `courier` value in the `client_requirements.taxi_class` parameter and the `thermobag` and/or `auto_courier` value in the `client_requirements.cargo_options` parameter.

For more information, see the [documentation](https://yandex.com/support/delivery-profile/en/api/express/openapi/IntegrationV2Tariffs.md).

#### 13. What are confirmation codes and how do they work? {#claim-create-confirmation}

A confirmation code is a courier's digital signature confirming item acceptance, handing over, or return.

**Confirmation at point A (store).** After arriving at the location, the courier sets the corresponding status in their app (the `ready_for_pickup_confirmation` API status). The courier then confirms that they have picked up the package. Then a code is automatically generated and sent to the sender by text message, in their account, or by API. The sender must confirm the code with the courier. The courier needs to enter the code in the app and can then head to the recipient.

**Confirmation at point B (at the recipient).** After arriving at the location, the courier confirms this in the app (the `ready_for_delivery_confirmation` API status). After that, a code is automatically generated and sent to the recipient by text message. The recipient must confirm the code with the courier. The courier needs to enter the code in the app and then can close the order.

**Confirmation at the return point (if the item wasn't handed over and needs to be returned)**. After the courier confirms arrival at the location (the `ready_for_return_confirmation` API status), a code is generated and sent to the customer by text message, in their account, or by API. For the item to be returned, the customer must confirm the code with the courier. The courier needs to enter the code in the app and then can cancel the order and complete the return.

The need to complete a confirmation procedure at a particular route point is determined by the value of the `route_points[].skip_confirmation` field. The default value is `false` — the confirmation procedure must be passed. You can change the value to `true` — the confirmation procedure can be skipped at this point.

### Evaluating claims {#claim-estimate}

#### 14. What is a price offer? {#claim-estimate-offer}

A price offer is the actual cost of a potential trip claim that is formed if the claim was successfully evaluated. Please note that a price offer is only valid for about 10 minutes: from when its status changes to `ready_for_approval` until it changes to `accepted`.

If a claim isn't confirmed within 10 minutes, you need to submit it for reevaluation. You can do this using the [Edit claim](https://yandex.com/support/delivery-profile/en/api/express/openapi/IntegrationV2ClaimsEdit.md) method or by creating a new claim with a new `request_id` parameter value.

Confirming a claim with an offer that has expired after 10 minutes will cause an error: the service response will be `200`, but the claim will soon change its status to `failed`. You can find out the claim status using the methods for obtaining claim information.

#### 15. What is a claim version? {#claim-estimate-version}

A claim can go through multiple versions sequentially. A newly created claim is version number 1. Each time a claim is changed using the edit claim method, its version number increases by one: 2, 3, and so on.

### Confirming claims {#claim-approve}

#### 16. How do I confirm a created claim? {#claim-approve-approve}

To confirm a created claim, it must be successfully evaluated. The evaluation process is automatic and takes a few seconds. Then the claim status changes to `ready_for_approval` and the claim is ready for confirmation. You can check the claim status using the [Changelog](https://yandex.com/support/delivery-profile/en/api/express/openapi/IntegrationV2ClaimsJournal.md) and [Get claim information](https://yandex.com/support/delivery-profile/en/api/express/openapi/IntegrationV2ClaimsInfo.md) methods.

You need to confirm a claim within 10 minutes after its status changes to `ready_for_approval`. To do this, use the [Confirm claim](https://yandex.com/support/delivery-profile/en/api/express/openapi/IntegrationV2ClaimsAccept.md) method. The search for a courier will only start after the claim is confirmed.

### Tracking claims {#claim-info}

#### 17. How am I informed of trip status changes? {#claim-info-status}

You can get information about the current trip status using the [Get information on multiple claims](https://yandex.com/support/delivery-profile/en/api/express/openapi/IntegrationV2ClaimsBulkInfo.md) and [Changelog](https://yandex.com/support/delivery-profile/en/api/express/openapi/IntegrationV2ClaimsJournal.md) methods.

#### 18. How long does it take to find a courier? {#claim-info-courier}

Finding a courier takes no more than 30 minutes when you create a claim for the nearest time.

#### 19. How do I get information about the courier? {#claim-info-driver}

Information about the courier is available in the `performer_info` section returned by the [Get claim information](https://yandex.com/support/delivery-profile/en/api/express/openapi/IntegrationV2ClaimsInfo.md) and [Get information on multiple claims](https://yandex.com/support/delivery-profile/en/api/express/openapi/IntegrationV2ClaimsBulkInfo.md) methods.

To get the courier's phone number, you can use the [Courier's phone number](https://yandex.com/support/delivery-profile/en/api/express/openapi/IntegrationV2DriverVoiceForwarding.md) method. Spoofed numbers are used to protect personal data. The spoofed phone number is valid as long as the claim is active (until its status changes to the final status).

### Canceling claims {#claim-cancel}

#### 20. How do I cancel a claim? {#claim-cancel-cancel}

To cancel a claim:

1. Use the [Terms of cancellation](https://yandex.com/support/delivery-profile/en/api/express/openapi/IntegrationV2ClaimsCancelInfo.md) method to see the cancellation conditions (free or paid) in the `cancel_state` field.

2. Cancel the claim using the [Cancel the claim](https://yandex.com/support/delivery-profile/en/api/express/openapi/IntegrationV2ClaimsCancel.md) method. The claim status will change to `canceled` if the claim was canceled before the courier arrived at the pickup point or to `cancelled_with_payment` if the courier has already confirmed arrival, but hasn't picked up the item yet.