---
title: "Find canonical carrier slugs (beta)"
method: GET
path: "/carriers"
tags: ["Delivery Estimates"]
---

# Find canonical carrier slugs (beta)

`GET /carriers`

## Request

- Base URL: `https://parcelsapp.com/api-docs/mock/v4`
- URL: `https://parcelsapp.com/api-docs/mock/v4/carriers`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/parcelsapp/apis/parcels-api-v4/docs/carriers/get.ts> (a function with typed inputs; its response is checked against the schema)

Beta companion to delivery estimates. Searches carrier names and aliases for use in delivery-estimate requests. `transport_modes` lists only the modes supported by that canonical carrier; callers must use one of those values. Ambiguous names such as a global network with several country branches are returned as separate canonical slugs.

## Query parameters

- `query` string
- `transport_mode` 'parcel' | 'postal' | 'express' | 'road_freight' | 'air_cargo' | 'ocean_container': Concrete transport mode. Forecast fallback never crosses this boundary.
- `limit` integer

## Response `200`

Matching carriers.

- DeliveryEstimateCarrierSearchResponse
  - `query` string, required
  - `transport_mode` 'parcel' | 'postal' | 'express' | 'road_freight' | 'air_cargo' | 'ocean_container': Concrete transport mode. Forecast fallback never crosses this boundary.
  - `carriers` object[], required
    - `slug` string, required
    - `name` string, required
    - `aliases` string[], required
    - `transport_modes` TransportMode[], required
  - `total_matches` integer, required
  - `has_more` boolean, required

## Other responses

- `400`: Invalid transport mode or a mode not supported by the selected carrier.
- `401`: Missing or invalid API key.
- `404`: Beta endpoint is disabled by the production feature flag.
- `429`: Too many requests.

## Changes

- **2026-11-06** `dd6315a8bc4e`: 6 warning, 1 info
  - added the new `INVALID_ADDITIONAL_FIELDS` enum value to the `error/rejected/items/code` response property for the response status `400`
  - added the new `INVALID_ADDITIONAL_FIELDS` enum value to the `error/rejected/items/code` response property for the response status `401`
  - added the new `INVALID_ADDITIONAL_FIELDS` enum value to the `error/rejected/items/code` response property for the response status `429`
  - added the new `INVALID_CURSOR` enum value to the `error/code` response property for the response status `400`
  - …3 more
- **2026-07-19** `f8d02f819394`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/parcelsapp/apis/parcels-api-v4/changes/carriers/get.md)

---

[API](https://skmtc.dev/parcelsapp/apis/parcels-api-v4.md) - [All operations](https://skmtc.dev/parcelsapp/apis/parcels-api-v4/llms.txt) - [OpenAPI document](https://skmtc.dev/parcelsapp/apis/parcels-api-v4/revisions/dd6315a8bc4e?raw)