# Add carrier to load

Add an additional carrier to a load.

## Use cases

- Split loads (multiple carriers for same load)
- Adding backup carrier
- Re-assigning after TONU/bounce

## What happens

- New LoadCarrier record is created
- Carrier is notified (if configured)

Endpoint: POST /loads/{id}/add-carrier
Version: 1.0.0
Security: BearerAuth

## Path parameters:

  - `id` (string, required)
    Resource ID (UUID) or client key
    Example: "550e8400-e29b-41d4-a716-446655440000"

## Query parameters:

  - `by` (string)
    Specify lookup type for faster retrieval.
If omitted, defaults to looking up by ID first, then falls back to client key if not found.
Use by=key when you know you're providing a client key for best performance.
    Enum: "id", "key"

## Request fields (application/json):

  - `carrier` (any, required)

  - `contact` (any)

  - `charges` (array)

  - `charges.chargeCode` (any, required)

  - `charges.description` (string)

  - `charges.amount` (number, required)

  - `charges.quantity` (number)

  - `driverName` (string)

  - `driverPhone` (string)

  - `truckNumber` (string)

  - `trailerNumber` (string)

## Response 201 fields (application/json):

  - `loadId` (string, required)

  - `loadCarrierId` (string, required)
    The new load carrier ID

  - `loadCarrier` (object)

  - `loadCarrier.id` (string)

  - `loadCarrier.carrier` (object)
    Enhanced reference to a carrier resource (returned in responses).
Includes full carrier details in addition to id/key.

Note: Does NOT include nested references (contacts, etc.) to prevent recursion.
Maximum nesting depth: 1 level.

  - `loadCarrier.carrier.id` (string, required)
    Carrier UUID
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `loadCarrier.carrier.key` (string,null)
    Client-defined reference ID if set
    Example: "ERP-CARRIER-SWIFT"

  - `loadCarrier.carrier.name` (string, required)
    Carrier company name
    Example: "Swift Transportation"

  - `loadCarrier.carrier.phoneNumber` (string,null)
    Primary phone number
    Example: "+1-555-987-6543"

  - `loadCarrier.carrier.email` (string,null)
    Primary email address
    Example: "dispatch@swifttrans.com"

  - `loadCarrier.carrier.createdAt` (string, required)
    When the carrier was created
    Example: "2025-01-15T10:00:00Z"

  - `loadCarrier.carrier.updatedAt` (string, required)
    When the carrier was last updated
    Example: "2025-01-15T14:30:00Z"

  - `loadCarrier.carrier.deletedAt` (string,null)
    When the carrier was soft deleted (null if active)

  - `loadCarrier.contact` (object)

  - `loadCarrier.contact.name` (string)

  - `loadCarrier.contact.phone` (string,null)

  - `loadCarrier.contact.email` (string,null)

  - `loadCarrier.status` (string)
    Status of the carrier assignment.
- ACTIVE: Carrier is actively assigned
- TONU: Truck Ordered Not Used (carrier dispatched but cancelled)
- BOUNCED: Carrier bounced/rejected load
    Enum: "ACTIVE", "TONU", "BOUNCED"

  - `loadCarrier.billingStatus` (string)
    Billing status for the load (AP side).
- AWAITING_INVOICE: Waiting for carrier invoice
- INVOICE_IN_REVIEW: Invoice received, under review
- APPROVED_TO_PAY: Approved for payment
- PAID: Paid to carrier
    Enum: "AWAITING_INVOICE", "INVOICE_IN_REVIEW", "APPROVED_TO_PAY", "PAID"

  - `loadCarrier.bookedAt` (string,null)

  - `loadCarrier.dispatchedAt` (string,null)

  - `loadCarrier.charges` (array)
    Flattened charges array

  - `loadCarrier.charges.chargeCode` (object)
    Reference to another resource (returned in responses)

  - `loadCarrier.charges.chargeCode.id` (string, required)
    Resource UUID

  - `loadCarrier.charges.description` (string,null)

  - `loadCarrier.charges.amount` (number)

  - `loadCarrier.charges.quantity` (number)

  - `loadCarrier.totalCost` (number,null)
    Sum of all charges

  - `loadCarrier.driverName` (string,null)

  - `loadCarrier.driverPhone` (string,null)

  - `loadCarrier.truckNumber` (string,null)

  - `loadCarrier.trailerNumber` (string,null)

  - `loadCarrier.createdAt` (string)

  - `loadCarrier.updatedAt` (string,null)

## Response 400 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 401 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 404 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 422 fields (application/json):

  - `error` (string, required)
    Error code
    Example: "validation_error"

  - `message` (string, required)
    Human-readable error message

  - `details` (array, required)
    Validation error details

  - `details.field` (string, required)
    Field name that failed validation

  - `details.message` (string, required)
    Validation error message