---
title: "List parcels filtered by state."
method: GET
path: "/v1/parcels"
tags: ["parcels"]
---

# List parcels filtered by state.

`GET /v1/parcels`

Returns a paginated list of parcels that match the specified states.

## Query parameters

- `states` string[], required
- `page` number, required

## Response `200`

Success

- PaginatedParcels
  - `parcels` Parcel[], required
    - `id` string, uuid — System-generated UUID for this parcel.
    - `external_id` string — Your own identifier for this parcel, as provided when the parcel was created.
    - `pickup_info` ParcelPointPickupInfo — Information about the pickup point. You must provide exactly one of the following location fields: `loc` (coordinates), `addr` (address string), or `hub_external_id` (reference to a registered hub).
      - `addr` string — Full address where the parcel should be picked up.
      - `contact` NewParcelPickupContact, required
        - `name` string, nullable — Name of the contact person at the pickup location.
        - `phone` string, nullable — Phone number of the contact person at the pickup location.
      - `instr` string, nullable — Additional instructions for the driver at the pickup location.
      - `loc` Point — A geographic coordinate expressed as latitude and longitude.
        - `lat` number, float, required — Latitude in decimal degrees.
        - `lon` number, float, required — Longitude in decimal degrees.
      - `code` string, nullable — Alphanumeric code (typically 4–6 characters) shown to the driver to confirm the pickup. Only one code is shown per delivery, so only use this field when the delivery consists of a single parcel.
      - `hub_external_id` string — External ID of a client hub to use as the pickup location.
    - `dropoff_info` ParcelPointDropoffInfo — Information about the drop-off (destination) point. You must provide exactly one of the following location fields: `loc` (coordinates), `addr` (address string), or `hub_external_id` (reference to a registered hub).
      - `addr` string — Full address where the parcel should be delivered.
      - `contact` NewParcelDropoffContact, required
        - `name` string — Name of the recipient at the drop-off location.
        - `phone` string, nullable — Phone number of the recipient at the drop-off location.
      - `instr` string, nullable — Additional instructions for the driver at the drop-off location.
      - `loc` Point — A geographic coordinate expressed as latitude and longitude.
        - `lat` number, float, required — Latitude in decimal degrees.
        - `lon` number, float, required — Longitude in decimal degrees.
      - `hub_external_id` string — External ID of a client hub to use as the drop-off location.
    - `dimensions` ParcelDimensions — Physical dimensions of the parcel.
      - `height` integer
      - `length` integer
      - `width` integer
      - `unit` 'cm' — Unit of measure for the dimensions. Defaults to `cm` if omitted or set to an invalid value.
    - `weight` ParcelWeight — Weight of the parcel.
      - `value` integer
      - `unit` 'g' — Unit of weight. Defaults to `g` (grams) if omitted or set to an invalid value.
    - `price` Price — Price information for the parcel, used in cash-on-delivery scenarios.
      - `declared_value` integer — Declared value of the parcel's contents, in the smallest currency unit following the ISO 4217 standard (e.g. €6.30 → `630`).
      - `collected_value` integer — Amount to be collected from the recipient upon delivery, in the smallest currency unit following the ISO 4217 standard (e.g. €6.30 → `630`).
      - `currency` string — ISO 4217 currency code.
    - `created_at` string, date-time — Timestamp when the parcel was created, formatted according to RFC 3339, section 5.6.
    - `updated_at` string, date-time — Timestamp of the most recent update to the parcel, formatted according to RFC 3339, section 5.6.
  - `page` number, required — The current page number returned.
  - `page_size` number, required — The number of parcels returned per page.
  - `more_pages` boolean, required — Whether additional pages of results are available.

## Other responses

- `400` — Bad request. One or more query parameters failed validation.
- `401` — Unauthorized. Missing or invalid authentication token.

---

[API](https://skmtc.dev/cabify/apis/ride-hailing-api.md) · [All operations](https://skmtc.dev/cabify/apis/ride-hailing-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cabify/ride-hailing-api/revisions/8da1cb1270df/schema)