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

# Carriers, labels, and notes

> Choose a carrier and an available label before creating an asset, then add a note to the asset.

Look up carriers and available labels, create an asset, and add notes as shipments progress. All requests use your `AccessKey` header. Examples use fictional values.

Carrier and label assignments are optional when creating an asset. Skip the corresponding lookup when you do not need that assignment.

## 1. Look up a carrier

Call `GET /Carriers/GetCarriers`. The response is a direct array:

```json theme={null}
[
  {
    "CarrierName": "Example Carrier",
    "CarrierID": "00000000000000000000000000000004"
  }
]
```

By default, this endpoint returns four carriers: UPS, USPS, FedEx, and DHL. Use the returned `CarrierID` when creating or editing an asset. To retrieve a single carrier, supply its `CarrierID`; the response remains an array and is empty when nothing matches.

Results are returned in a single response. Look up carriers when you configure your integration and reuse the result instead of requesting the list before every asset operation.

## 2. Find an available label

Call `GET /Labels/GetLabels`. The response is an object with two separate properties:

```json theme={null}
{
  "Summary": {
    "Total": 2,
    "Healthy": 1,
    "NearExpiration": 0,
    "Assigned": 1
  },
  "Labels": [
    {
      "LabelID": 100002,
      "StatusNo": 0,
      "Status": "Available",
      "SubStatus": "Healthy",
      "SKU": "EXAMPLE-SKU",
      "AccountName": "Example Account",
      "AccountID": "00000000000000000000000000000002"
    }
  ]
}
```

This example shows only a subset of the row fields; the endpoint page lists all of them.

* `Labels` contains only available labels: state `0` (Healthy) and state `8` (Near expiration).
* `Summary` also counts assigned labels (state `2`). Assigned labels are counted but not returned as rows, so the number of rows is not `Total`.
* Label states are a different set of values from asset statuses.
* Each label includes its `AccountID`. Choose a label whose `AccountID` matches the asset's `AccountID`.
* Results are returned in one response. Retrieve the list when you need to choose a label.

## 3. Create the asset

Send the chosen identifiers to `POST /Assets/NewAssets`. Send `LabelID` as a string:

```json theme={null}
[
  {
    "AssetName": "Example Shipment",
    "AccountID": "00000000000000000000000000000002",
    "CarrierID": "00000000000000000000000000000004",
    "LabelID": "100002"
  }
]
```

Use a `CarrierID` returned by List carriers. Choose a label whose `AccountID` matches the asset's `AccountID`. You can also assign a label later, while the asset is Created. Assigning a label moves the asset to Ready, after which `LabelID` cannot be changed.

## 4. Add a note

Call `POST /Assets/UserComment` with the asset and the note text:

```json theme={null}
{
  "AssetID": "00000000000000000000000000000003",
  "Context": "Shipment handoff confirmed."
}
```

A successful request returns:

```json theme={null}
{"Code":200,"Message":"Success"}
```

The response does not include a note identifier or the stored entry. Each successful request creates a separate note, and there is no idempotency key, so do not automatically retry a request whose result is uncertain. Adding a note generates a `User comment` event, and configured email notifications for that event can be sent.

Rejected requests return HTTP `400`, with a body such as `{"Code":400,"Message":"Asset not found."}`. Invalid input, such as a missing required field, returns HTTP `422`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.