> ## Documentation Index
> Fetch the complete documentation index at: https://developers.perform.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Carriers

> How carriers work in Perform.AI — the master catalogue, your configurations, and the two identifiers you must not confuse.

Perform.AI tracks deliveries across 1,000+ carriers by normalizing each carrier's events, statuses, and data quirks into one model. Working with carriers through the API means understanding one distinction:

## The two identifiers

| Identifier              | What it is                                                                                                                                                                             | Where you use it                                                                                                                                                   |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`carrier_reference`** | **Your name for one carrier configuration** in your account (**Settings > Carriers**). The same carrier can have several — e.g. `ups-outbound` and `ups-returns` for two UPS accounts. | The field you send: [Create Shipment](/guides/create-shipment), [Create Booking](/guides/create-booking), linked shipments. An unconfigured value is **rejected**. |
| **`carrier_id`**        | **Perform.AI's 6-character identifier for the carrier itself**, from the master catalogue.                                                                                             | Filters and lookups: [List Shipments](/guides/list-shipments)' `carrier_id` filter, [PUDO locations](/guides/pudo-locations)' `carrier_ids`.                       |

Mixing them up is the most common integration error: `carrier_id` values like `dhleco` never work as a Shipment's carrier field, and your `carrier_reference` values mean nothing outside your account.

Discover both with [Carrier configurations](/guides/carrier-configurations) — it lists every configuration in your account with its `carrier_id`, name, and `carrier_reference`.

## Configurations power everything

A carrier must be configured in your account before it can be used — for creating tracked Shipments, retrieving events, booking, label generation, and PUDO search. Configurations are set up in the Portal (contact your account team to add carrier integrations); the API consumes them.

## Carrier objects in responses

Responses embed a `carrier` object with the master-catalogue identity: the 6-character `id`, `name`, operating countries, languages, contact, and site link. Shipments retrieved via v5.2 responses and webhooks also carry carrier context on every event (`carrier_name`) — meaningful when [linked shipments](/concepts/shipments) merge several carriers' events into one timeline.

<Tip>
  Carriers enforce their own field constraints at booking — commonly \~35 characters per address line — stricter than the API's own limits. If bookings fail on fields that passed creation, shorten the values.
</Tip>