3.3. Search claims

claim_id

string

Claim ID, received upon creation of claim

created_from

string

Start of the search period (isoformat)

created_to

string

End of the search period (isoformat)

due_from

string

Start of the search period (isoformat)

due_to

string

End of the search period (isoformat)

external_order_id

string

ID of the external order linked to the point

limit *

integer

Maximum number of claims in the response (int64)

Minimum value: 0.
Maximum value: 1000.

offset

integer

Offset (pagination) of output with claims for the specified filter (claims are sorted by creation date) (int64)

Minimum value: 0.

phone

string

Filter by phone number

state

string

Filter by claim status

1. active
2. finished
3. delayed

status

string

Claim status

1. new
2. estimating
3. estimating_failed
4. ready_for_approval
5. accepted
6. performer_lookup
7. performer_draft
8. performer_found
9. performer_not_found
10. pickup_arrived
11. ready_for_pickup_confirmation
12. pickuped
13. delivery_arrived
14. ready_for_delivery_confirmation
15. pay_waiting
16. delivered
17. delivered_finish
18. returning
19. return_arrived
20. ready_for_return_confirmation
21. returned
22. returned_finish
23. failed
24. cancelled
25. cancelled_with_payment
26. cancelled_by_taxi
27. cancelled_with_items_on_hands

cursor *

string

Cursor of the next search page

claims[] *

array

List of found claims

claims[].available_cancel_state

string

(deprecated) Identifier for possibility of paid or free cancellation. This mechanism is outdated, use the cancel_state field of the claim/cancel-info method

1. free
2. paid

claims[].callback_properties

object

Parameters for notifying the client server when the claim status changes.

The notification is a POST request to the specified URL,
to which information will be added about the date of the last change
to the claim and the order ID in the b2b cargo system in the format
'updated_ts=<ISO-8601>&claim_id=', that is, a URL in the format
'https://example.com/?my_order_id=123&' will be expanded to
'https://example.com/?my_order_id=123&updated_ts=...&claim_id=...'.

Important! Parameters are concatenated to the callback_url, which means that a
URL in the format 'https://example.com' will turn into the invalid
'https://example.comupdated_ts=...&claim_id=...'.

Only HTTP and HTTPS are supported. For HTTPS, the SSL certificate must
be issued to a known server by a certification center.

Notifications should be treated like push ahead of polling that lets you
get the status updates faster. The server expects a
200 response, and in the case of timeouts or any other response, it
will keep trying to deliver the notification for a while, then stop trying.
This means that to get the exact claim status,
the client should make a request using the v1/claims/info operation.

The client should allow that the response of the v1/claims/info operation may
contain an outdated claim status (check
the value of the updated_ts field). In this case, it is necessary to
call the operation again after waiting for 5 to 30 seconds.

claims[].callback_properties.callback_url *

string

URL that will be called when changing statuses for a claim.

This mechanism is deprecated, use the v1/claims/journal operation instead.

claims[].carrier_info

object

Information about the carrier

claims[].carrier_info.address

string

Carrier's address

claims[].carrier_info.inn

string

Carrier's INN (TIN)

claims[].carrier_info.name

string

Name of the carrier

claims[].client_requirements

object

Client's requirements specified when creating or editing claim

claims[].client_requirements.assign_robot

boolean

Should the system try to assign the order to a rover (six-wheeled robot)

claims[].client_requirements.cargo_loaders

integer

Number of loaders (int64) for the cargo class.
Acceptable values: 0, 1, 2.

Use the service class get method (v1/tariffs)
to fetch an exact list of possible values for a specific geo point

Minimum value: 0.

claims[].client_requirements.cargo_options[]

array

List of additional options in the service class.

Acceptable individual options: - auto_courier (only couriers delivering orders by car) - thermobag (courier with an insulated bag) Example of an option list: ["auto_courier"].

Use the service class get method (v1/tariffs) to fetch an exact list of possible values for a specific geo point

claims[].client_requirements.cargo_type

string

Body type (size) for the cargo class.
Acceptable values: - van ("Small van") - lcv_m ("Medium van") - lcv_l ("Large van").

Use the service class get method (v1/tariffs) to fetch an exact list of possible values for a specific geo point

claims[].client_requirements.cargo_type_int

integer

Truck type (int64)

claims[].client_requirements.pro_courier

boolean

Pro option for the Express and Courier service classes

claims[].client_requirements.taxi_class *

string

Ride class. Acceptable values: courier, express, cargo

claims[].comment

string

General comments on the order

claims[].corp_client_id

string

Corporate client ID (from OAuth token)

claims[].created_ts *

string

Date and time of creation

claims[].current_point_id

integer

The integer ID (int64) of the point generated by Delivery.
Contained in the route_points[].id. Applicable to points with the following types:

source, destination, return

claims[].due

string

Create an order for a specific time (for example, an order for tomorrow).
If this field is left blank, the system will search for the nearest time.
Get approval from your manager to use this option!

claims[].emergency_contact

object

Contact information with phone number

claims[].emergency_contact.name *

string

Name of the contact person

claims[].emergency_contact.phone *

string

Contact phone number

claims[].emergency_contact.phone_additional_code

string

Extension number to call courier

claims[].error_messages[]

array

List of error messages

claims[].error_messages[].code *

string

Machine-readable error code

claims[].error_messages[].message *

string

Human-readable localized error text

claims[].eta

integer

Expected time of execution of the order in minutes (int64)

claims[].id *

string

Claim ID, received upon creation of claim

claims[].items[] *

array

List of shipment names to be sent

claims[].items[].cost_currency *

string

Currency of the price per piece in ISO 4217 format (used for value declaration/insurance and/or payment upon receipt).
Example: RUB

claims[].items[].cost_value *

string

Price per piece in the currency set in cost_currency.
To insure the cost, pass the actual price of the cargo

claims[].items[].droppof_point *

integer

ID (int64) of the delivery point (different from the ID in the claim).

It can be an arbitrary number. It must match the value of route_points[].point_id at the destination

claims[].items[].extra_id

string

Short unique ID of the item (the order number for a claim, usually identical to external_order_id)

claims[].items[].fiscalization

object

Information on fiscalization (relevant for payment upon receipt)

claims[].items[].fiscalization.article

string

Item SKU.
Must be unique for items handed over at the point.

claims[].items[].fiscalization.excise

string

Price Decimal(19, 4)

claims[].items[].fiscalization.item_type

string

Name type: Product or service.
By default, we believe that it's 'product'

1. product
2. service

claims[].items[].fiscalization.mark

object

Identifier of whether the product is labeled
The acceptable quantity value for a labeled product is 1

claims[].items[].fiscalization.mark.code *

string

The value of the product details in the kind format

claims[].items[].fiscalization.mark.kind *

string

Labeling type.
Acceptable values:

1. compiled: Already disassembled label with identified GTIN and Serial.
   Example:

   • 444D00000000003741
2. gs1_data_matrix_base64: Product code in the GS1 Data Matrix format, subject to labeling by means of identification.
   Maximum of 200 characters.
   The product code must be passed in its entirety by encoding the string in base64 format.

claims[].items[].fiscalization.supplier_inn

string

Supplier's INN

claims[].items[].fiscalization.vat_code_str

string

VAT rate.
vat_none: No VAT.
vat0: Zero VAT rate (applies in rare cases).
vat10: 10% VAT.
vat20: 20% VAT.

claims[].items[].pickup_point *

integer

ID (int64) of the pickup point (different from the ID in the claim).

It can be an arbitrary number. It must match the value of route_points[].point_id at the pickup point

claims[].items[].quantity *

integer

Quantity of the specified item (int64)

Minimum value: 1.

claims[].items[].size

object

Item's dimensions in meters. Make sure to pass actual values in the fields.

If the dimensions are not passed, the order is considered to be

for the maximum dimensions accepted for the service class.

If the actual characteristics of the shipment exceed those allowed,
the courier has the right to refuse to carry out the order when they arrive at the point.
In this case, the pickup cost will be deducted.

Courier: up to 0.80 m × 0.50 m × 0.50 m
Express: up to 1.00 m × 0.60 m × 0.50 m
Cargo:

• Small van: up to 1.70 m × 0.96 m × 0.90 m
• Medium van: up to 2.60 m × 1.30 m × 1.50 m
• Large van: up to 3.80 m × 1.80 m × 1.80 m

claims[].items[].size.height *

number

Size in meters

claims[].items[].size.length *

number

Size in meters

claims[].items[].size.width *

number

Size in meters

claims[].items[].title *

string

Name of item unit

claims[].items[].weight

number

Unit weight in kg. Actual values should be passed in the field.

If the weight is not passed, the order is considered to be
for the maximum dimensions accepted for the service class.

If the actual characteristics of the shipment exceed those allowed,
the courier has the right to refuse to carry out the order when they arrive at the point.
In this case, the pickup cost will be deducted.

Courier: Up to 10 kg
Express: Up to 20 kg
Cargo:

• Small van: Up to 300 kg
• Medium van: Up to 700 kg
• Large van: Up to 1400 kg

claims[].matched_cars[]

array

Information about the performer (array, at the moment always 1 element)

claims[].matched_cars[].cargo_loaders

integer

Required number of loaders

Minimum value: 0.

claims[].matched_cars[].cargo_type

string

Type of truck

claims[].matched_cars[].cargo_type_int

integer

Type of truck

claims[].matched_cars[].client_taxi_class

string

Substituted class (for example, "cargo" substituted when "cars" has "cargocorp")

claims[].matched_cars[].door_to_door

boolean

Door-to-door option for the Express service class

claims[].matched_cars[].pro_courier

boolean

Pro option for the Express and Courier service classes

claims[].matched_cars[].taxi_class *

string

Ride class. Acceptable values: courier, express, cargo

claims[].optional_return

boolean

Return of products not required if order canceled.

Acceptable values:

• true (the courier keeps the item)
• false (default, the courier needs to return the item)

claims[].performer_info

object

Information about the courier

claims[].performer_info.car_color

string

Color of the vehicle

claims[].performer_info.car_color_hex

string

RGB code of the vehicle color

claims[].performer_info.car_model

string

Vehicle model

claims[].performer_info.car_number

string

Vehicle number

claims[].performer_info.courier_name *

string

Name of the courier delivering the parcel

claims[].performer_info.legal_name *

string

Information about the legal entity fulfilling the delivery

claims[].performer_info.transport_type

string

Performer's mode of transport

claims[].pricing

object

Information about price of claim

claims[].pricing.currency

string

Three-digit code of the currency used for the calculation

claims[].pricing.currency_rules

object

Currency display rules

claims[].pricing.currency_rules.code *

string

Three-digit code of the currency used for the calculation

claims[].pricing.currency_rules.sign

string

Currency symbol

claims[].pricing.currency_rules.template *

string

Template

claims[].pricing.currency_rules.text *

string

Abbreviated name of the currency

claims[].pricing.final_price

string

Price Decimal(19, 4)

claims[].pricing.final_pricing_calc_id

string

claims[].pricing.offer

object

Offer from Yandex Taxi (valid for some time).

claims[].pricing.offer.offer_id *

string

Offer identifier

claims[].pricing.offer.price *

string

Price Decimal(19, 4)

claims[].pricing.offer.price_raw *

integer

(deprecated) Offer price in the currency specified in the contract (int64)

claims[].pricing.offer.price_with_vat

string

Price Decimal(19, 4)

claims[].pricing.offer.valid_until

string

Yandex Taxi offer's time of validity. If the value is omitted, the offer's validity is unlimited

claims[].revision *

integer

Revision (int64)

claims[].route_id

string

ID of the route on which the order is delivered
If several of your orders are delivered by the same courier,
they will have the same route_id
(Only relevant for the "Same day" delivery mode)

claims[].route_points[] *

array

Information on route points

claims[].route_points[].address *

object

claims[].route_points[].address.building

string

Building

claims[].route_points[].address.building_name

string

Name of the apartment (building)

claims[].route_points[].address.city

string

City

claims[].route_points[].address.comment

string

Comments for the courier.

For point A (pickup point), use the template: "Delivery from the store <>. Inform the manager that it's a Yandex Delivery order. State the order number <> and collect the parcel. The order is for non-cash payment, the delivery must be completed without requiring delivery payment from the recipient."

For B points (destination), pass the recipient's requests or instructions via the comment field. For example, "the intercom does not work", "the barrier is closed, call 10 minutes in advance", "do not call, the baby is asleep".

claims[].route_points[].address.coordinates[] *

array

Array of two real numbers [longitude, latitude]. The order is important! Rounded coordinate values are specified.

claims[].route_points[].address.country

string

Country

claims[].route_points[].address.description

string

Geographic area that specifies shortname to global match

claims[].route_points[].address.door_code

string

Intercom code

claims[].route_points[].address.door_code_extra

string

Additional instructions on intercoms

claims[].route_points[].address.doorbell_name

string

Name on the doorbell

claims[].route_points[].address.flat

integer

Apartment (DEPRECATED) (int64)

claims[].route_points[].address.floor

integer

Floor (DEPRECATED) (int64)

claims[].route_points[].address.fullname *

string

Full name indicating the city (Moscow, Sadovnicheskaya Naberezhnaya, 82 bld. 2).
It is important to enter a locality indicating the house number but without the apartment number, entrance, or floor

claims[].route_points[].address.porch

string

Entrance (can be A)

claims[].route_points[].address.sflat

string

Apartment

claims[].route_points[].address.sfloor

string

Floor

claims[].route_points[].address.shortname

string

Address within the city as shown in Taximeter (Sadovnicheskaya Naberezhnaya, 82 bld. 2)

claims[].route_points[].address.street

string

Street

claims[].route_points[].address.uri

string

Map uri of geo object

claims[].route_points[].contact *

object

claims[].route_points[].contact.email

string

Email — required parameter for source and return points

claims[].route_points[].contact.name *

string

Name of the contact person

claims[].route_points[].contact.phone *

string

Contact phone number

claims[].route_points[].contact.phone_additional_code

string

Extension number to call courier

claims[].route_points[].expected_visit_interval

object

The time interval, returned to the client

claims[].route_points[].expected_visit_interval.from *

string

Start of the time interval

claims[].route_points[].expected_visit_interval.to *

string

End of the time interval

claims[].route_points[].external_order_cost

object

The cost of an external order linked to the point

claims[].route_points[].external_order_cost.currency *

string

claims[].route_points[].external_order_cost.currency_sign *

string

claims[].route_points[].external_order_cost.value *

string

claims[].route_points[].external_order_id

string

Order number from the client's system.
Passed for a point with the "destination" type

claims[].route_points[].id *

integer

Integer ID of the point (int64)

claims[].route_points[].leave_under_door

boolean

Leave the package at the door

claims[].route_points[].meet_outside

boolean

Someone will meet the courier on the street at the entrance

claims[].route_points[].modifier_age_check

boolean

Check documents for the purchase of alcohol/tobacco products

claims[].route_points[].no_door_call

boolean

Don't ring the doorbell

claims[].route_points[].payment_on_delivery

object

Payment parameters upon receipt

claims[].route_points[].payment_on_delivery.client_order_id

string

Order ID

claims[].route_points[].payment_on_delivery.cost

string

Price Decimal(19, 4)

claims[].route_points[].payment_on_delivery.customer

object

Client information

claims[].route_points[].payment_on_delivery.customer.email

string

User's email in the format morty@yandex.ru. If not specified, the recipient's email from the point will be used

claims[].route_points[].payment_on_delivery.customer.full_name

string

Company name for legal entities, full name for individual entrepreneurs and individuals

claims[].route_points[].payment_on_delivery.customer.inn

string

User's TIN

claims[].route_points[].payment_on_delivery.customer.phone

string

User's phone number in the format +79990001122. If not specified, the recipient's phone number from the point will be used

claims[].route_points[].payment_on_delivery.is_paid *

boolean

Order payment identifier

claims[].route_points[].payment_on_delivery.payment_method

string

Selected payment type.
card: Payment by card with a fallback to the link.
cash: Cash payment (not yet available).

1. card
2. cash

claims[].route_points[].payment_on_delivery.payment_ref_id

string

Payment ID

claims[].route_points[].pickup_code

string

Code of parcel delivery to the courier.
The courier will need to enter this code to confirm that they picked up your parcel.
For this, your employees at the pickup point must be able to give this code to the courier.
Applies to the point with type = 'source'.
Format: Exactly 6 digits
|
Product delivery code (pickup pint)

claims[].route_points[].return_comment

string

Comment to reasons for the return of the shipment

claims[].route_points[].return_reasons[]

array

Reasons for the return of the shipment

claims[].route_points[].skip_confirmation

boolean

Skip SMS confirmation at this point

Default: false (confirmation required)

claims[].route_points[].type *

string

point type:

• source: the pickup point where the courier picks up the items - destination: the destination point where the courier delivers the items - return: the point where the items are returned (added automatically and by default is the same as the pickup point, but another point can be defined too)

1. source
2. destination
3. return

claims[].route_points[].visit_order *

integer

Point visit sequence number (numbering starts from 1) (int64)

claims[].route_points[].visit_status *

string

Status of visiting this point: pending: the point has not yet been visited; arrived: the driver arrived at the point; visited: the driver delivered or picked up the shipment at the point; partial_delivery: the point was visited, but part of the shipment wasn't delivered; skipped: the point was skipped (in the case of a return when the client couldn't receive the shipment)

1. pending
2. arrived
3. visited
4. partial_delivery
5. skipped

claims[].route_points[].visited_at *

object

Information about the time of visit to the point

claims[].route_points[].visited_at.actual

string

Actual time of visit to the point.
Filled out only for visited points

claims[].route_points[].visited_at.expected

string

Expected time of visit. Can be filled out

(in some cases) only for unvisited points.

claims[].route_points[].visited_at.expected_waiting_time_sec

integer

Expected waiting time at the point (int64).

claims[].same_day_data

object

Additional information for "Same day" claims

claims[].same_day_data.delivery_interval *

object

Parcel pickup and delivery interval

claims[].same_day_data.delivery_interval.from *

string

Start of the time interval

claims[].same_day_data.delivery_interval.to *

string

End of the time interval

claims[].shipping_document

string

Accompanying documentation

claims[].skip_act

boolean

Do not show delivery receipt

claims[].skip_client_notify

boolean

Do not send SMS notifications to the sender or recipient
when the courier is on the way to them.

Default: false (send notifications)

claims[].skip_door_to_door

boolean

Opting out of delivery to the door. (Disable the "Door-to-door" option).

Acceptable values: - true (the courier will deliver the order to the outdoor entrance) - false (default, door-to-door delivery)

claims[].skip_emergency_notify

boolean

Do not send emergency notifications to the contact

Default: false (send notifications)

claims[].status *

string

Claim status

1. new
2. estimating
3. estimating_failed
4. ready_for_approval
5. accepted
6. performer_lookup
7. performer_draft
8. performer_found
9. performer_not_found
10. pickup_arrived
11. ready_for_pickup_confirmation
12. pickuped
13. delivery_arrived
14. ready_for_delivery_confirmation
15. pay_waiting
16. delivered
17. delivered_finish
18. returning
19. return_arrived
20. ready_for_return_confirmation
21. returned
22. returned_finish
23. failed
24. cancelled
25. cancelled_with_payment
26. cancelled_by_taxi
27. cancelled_with_items_on_hands

claims[].taxi_offer

object

Offer from Yandex Taxi (valid for some time). This mechanism is outdated, use pricing.offer

claims[].taxi_offer.offer_id *

string

Offer identifier

claims[].taxi_offer.price *

string

Price Decimal(19, 4)

claims[].taxi_offer.price_raw *

integer

(deprecated) Offer price in the currency specified in the contract (int64)

claims[].updated_ts *

string

Date and time of last update

claims[].user_request_revision *

string

Current version of changes in the user's claim

claims[].version *

integer

Version (int64)

claims[].warnings[]

array

Claim cycle warnings

claims[].warnings[].code *

string

Warning type. not_fit_in_car - the shipment may not fit in the vehicle, requirement_unavailable - the specified requirement is unavailable and was ignored, address_not_found - Yandex Maps didn't find the specified address, address_too_far - coordinates from Yandex Maps at the specified address are far from the passed coordinates,

claims[].warnings[].message

string

Localized information with the reason for the warning

claims[].warnings[].source *

string

Warning source. client_requirements - warning related to client requirements, taxi_requirements - warning related to Taxi requirements, route_points - warning related to passed addresses,

cursor

string

Cursor of the previous search page

code *

string

String error code

1. validation_error

message *

string

Human-readable error message

code *

string

String error code

1. too_many_requests

message *

string

Human-readable error message