---
title: "Create or update carrier"
method: POST
path: "/v1/carriers"
tags: ["Carrier Management"]
---

# Create or update carrier

`POST /v1/carriers`

## Request

- Base URL: `https://api.prod.goaugment.com`
- URL: `https://api.prod.goaugment.com/v1/carriers`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/goaugment/apis/augment-api/docs/v1/carriers/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a new carrier or update an existing one. This endpoint supports three operations:
- **Creation**: Provide all required fields to create a new carrier.
- **Partial Update**: Include only the fields you want to update. Carriers
  are matched by `tmsId`, so provide the `tmsId` of the carrier you want
  to update.

- **Full Update**: Include all fields to completely replace the carrier
  data.

For updating managers and contacts, it is highly recommended to provide `tmsId` for each manager and contact when creating them. This allows the system to match and update existing managers/contacts by their `tmsId` during subsequent updates. If `tmsId` is not provided for managers or contacts, you will need to clear the entire array and re-add all managers/contacts when updating.

## Request body

- CarrierRequest
  - `name` string, required: Carrier name (required)
  - `tmsId` string, required: TMS identifier for the carrier. Used for matching existing carriers. Cannot be changed after creation.
  - `status` object: Carrier status.
    - `code` 'ACTIVE' | 'DO_NOT_USE': Status code indicating the carrier's current state
    - `reason` string: Optional reason for the status
  - `complianceStatus` object: Compliance status information.
    - `codes` object: Compliance codes as key-value pairs
  - `mcNumber` integer: MC number
  - `dotNumber` integer: DOT number
  - `scac` string: SCAC code
  - `address` object: Carrier address.
    - `street1` string: Street address line 1
    - `street2` string: Street address line 2 (optional)
    - `city` string: City name
    - `stateOrProvince` string: State or province code
    - `postalCode` string: Postal or ZIP code
    - `country` string: Must be 2-letter ISO country code as listed here: https://www.iban.com/country-codes
    - `name` string: Location name (e.g., building name)
    - `company` string: Company name
  - `email` string, email: Carrier email address.
  - `phone` string: Phone number in E.164 format (e.g., +13125551234).
  - `phoneExtension` string: Phone extension.
  - `managers` BrokerageContactRequest[]: Array of organization contacts (managers) who manage this carrier. Pass an empty array [] to clear all managers when updating.
    - `name` string: Contact name
    - `email` string, email: Contact email address
    - `phone` string: Phone number in E.164 format (e.g., +13125551234)
    - `phoneExtension` string: Phone extension
    - `tmsId` string: TMS identifier for matching existing contacts. If provided, the system will match and update the existing contact.
    - `roles` string[]: The employee's role(s) on each load. Possible values: `CARRIER_REP` — rep who gets commission credit for the load, `OPERATIONS_REP` — manages day-to-day operations on the load, `OPERATIONS_MANAGER` — brokerage-side manager or supervisor, `ACCOUNT_MANAGER` — manages the customer relationship, `CUSTOMER_REP` — sales rep to the customer, `CUSTOMER_TEAM` — part of the broader customer team, `CARRIER_TEAM` — team responsible for carrier-facing operations and relationships, `BOOKED_BY` — party who booked the load, `AP_REP` — Accounts Payable Specialist, who manages invoice and payment processes, `AFTER_HOURS_REP` — contact available outside of regular business hours.
    - `preferredContactMode` 'EMAIL' | 'PHONE_CALL' | 'TEXT_MESSAGE' | 'TELEGRAM': Preferred method of contact
  - `contacts` CarrierContactRequest[]: Array of carrier contacts (carrier employees). Pass an empty array [] to clear all contacts when updating.
    - `name` string: Contact name
    - `email` string, email: Contact email address. Either email or phone is required.
    - `phone` string: Phone number in E.164 format (e.g., +13125551234). Either email or phone is required.
    - `phoneExtension` string: Phone extension
    - `tmsId` string: TMS identifier for matching existing contacts. If provided, the system will match and update the existing contact.
    - `roles` string[]: Carrier contact roles: - `ACCOUNTANT` — Accountant - `AP_REP` — manages invoices and payments - `DISPATCHER` — Dispatcher - `AFTER_HOURS_DISPATCHER` — dispatcher to contact outside of regular business hours - `WEEKEND_DISPATCHER` — dispatcher to contact on weekends - `BOOKING` — handles load booking - `TRACKING` — handles load tracking - `DRIVER` — Driver - `OTHER` — Other
    - `preferredContactMode` 'EMAIL' | 'PHONE_CALL' | 'TEXT_MESSAGE' | 'TELEGRAM': Preferred method of contact
  - `notes` string: Free-form notes about the carrier.
  - `customData` CarrierCustomData: Optional metadata for the carrier. Use string keys; each value may be a string, number, boolean, array of JSON-safe values, or nested object with the same rules. Omit or send `{}` when you have nothing to store.

## Response `201`

Carrier created or updated successfully

- CarrierResponse
  - `id` string: Carrier ID (ULID)
  - `name` string: Carrier name
  - `tmsId` string, nullable: TMS identifier for the carrier
  - `status` object, nullable: Carrier status
    - `code` 'ACTIVE' | 'DO_NOT_USE': Status code indicating the carrier's current state
    - `reason` string, nullable: Optional reason for the status
  - `complianceStatus` object, nullable: Compliance status information
    - `codes` object: Compliance codes as key-value pairs
  - `mcNumber` integer, nullable: MC number
  - `dotNumber` integer, nullable: DOT number
  - `scac` string, nullable: SCAC code
  - `address` object, nullable: Carrier address
    - `street1` string: Street address line 1
    - `street2` string, nullable: Street address line 2
    - `city` string: City name
    - `stateOrProvince` string, nullable: State or province code
    - `postalCode` string: Postal or ZIP code
    - `country` string: Country code (2-letter ISO)
    - `name` string, nullable: Location name
    - `company` string, nullable: Company name
  - `email` string, nullable: Carrier email address
  - `phone` string, nullable: Phone number in E.164 format (e.g., +13125551234)
  - `phoneExtension` string, nullable: Phone extension
  - `managers` BrokerageContactResponse[]: Array of organization contacts (managers) who manage this carrier
    - `id` string: Organization contact ID (ULID)
    - `name` string, nullable: Contact name
    - `tmsId` string, nullable: TMS identifier for the contact
    - `roles` string[]: The employee's role(s) on each load. Possible values: `CARRIER_REP` — rep who gets commission credit for the load, `OPERATIONS_REP` — manages day-to-day operations on the load, `OPERATIONS_MANAGER` — brokerage-side manager or supervisor, `ACCOUNT_MANAGER` — manages the customer relationship, `CUSTOMER_REP` — sales rep to the customer, `CUSTOMER_TEAM` — part of the broader customer team, `CARRIER_TEAM` — team responsible for carrier-facing operations and relationships, `BOOKED_BY` — party who booked the load, `AP_REP` — Accounts Payable Specialist, who manages invoice and payment processes, `AFTER_HOURS_REP` — contact available outside of regular business hours.
    - `preferredContactMode` 'EMAIL' | 'PHONE_CALL' | 'TEXT_MESSAGE' | 'TELEGRAM', nullable: Preferred method of contact
    - `email` string, nullable: Contact email address
    - `phone` string, nullable: Phone number in E.164 format (e.g., +13125551234)
    - `phoneExtension` string, nullable: Phone extension
  - `contacts` CarrierContactResponse[]: Array of carrier contacts (carrier employees)
    - `id` string: Carrier contact ID (ULID)
    - `name` string, nullable: Contact name
    - `tmsId` string, nullable: TMS identifier for the contact
    - `roles` string[]: Carrier contact roles: - `ACCOUNTANT` — Accountant - `AP_REP` — manages invoices and payments - `DISPATCHER` — Dispatcher - `AFTER_HOURS_DISPATCHER` — dispatcher to contact outside of regular business hours - `WEEKEND_DISPATCHER` — dispatcher to contact on weekends - `BOOKING` — handles load booking - `TRACKING` — handles load tracking - `DRIVER` — Driver - `OTHER` — Other
    - `preferredContactMode` 'EMAIL' | 'PHONE_CALL' | 'TEXT_MESSAGE' | 'TELEGRAM', nullable: Preferred method of contact
    - `email` string, nullable: Contact email address
    - `phone` string, nullable: Phone number in E.164 format (e.g., +13125551234)
    - `phoneExtension` string, nullable: Phone extension
  - `notes` string, nullable: Free-form notes about the carrier
  - `customData` CarrierCustomData: Optional metadata for the carrier. Use string keys; each value may be a string, number, boolean, array of JSON-safe values, or nested object with the same rules. Omit or send `{}` when you have nothing to store.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `422`: Unprocessable Entity - Validation errors

---

[API](https://skmtc.dev/goaugment/apis/augment-api.md) - [All operations](https://skmtc.dev/goaugment/apis/augment-api/llms.txt) - [OpenAPI document](https://skmtc.dev/goaugment/apis/augment-api/revisions/b61097634d79?raw)