FAQ

Handling claims

Creating claims

1. What is a request_id? Why does the method sometimes return information about a previously created claim?

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?

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?

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?

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": "AED".

5. Do I need to send the item dimensions and weight?

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?

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

7. Do I need to send 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?

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?

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.

10. How do I specify the code that the courier needs to pick up the order at the warehouse?

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?

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.

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?

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.

13. What are confirmation codes and how do they work?

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

14. What is a price 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 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?

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

16. How do I confirm a created claim?

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 and Get claim information 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 method. The search for a courier will only start after the claim is confirmed.

Tracking claims

17. How am I informed of trip status changes?

You can get information about the current trip status using the Get information on multiple claims and Changelog methods.

18. How long does it take to find a 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?

Information about the courier is available in the performer_info section returned by the Get claim information and Get information on multiple claims methods.

To get the courier's phone number, you can use the Courier's phone number 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

20. How do I cancel a claim?

To cancel a claim:

1. Use the Get claim information method to see the cancellation conditions (free or paid) in the available_cancel_state field.

2. Cancel the claim using the Cancel the claim 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.