---
title: "Bulk create or update carriers"
method: POST
path: "/v1/carriers/bulk"
tags: ["Carrier Management"]
---

# Bulk create or update carriers

`POST /v1/carriers/bulk`

## Request

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

Create or update multiple carriers in a single request. Maximum 20 carriers per request. Each carrier is processed in its own transaction. Partial success is supported - some carriers may succeed while others fail.

## Request body

- BulkUpsertCarriersRequest
  - `carriers` CarrierRequest[], required: Array of carriers to create or update. Maximum 20 carriers per request.
    - `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 `200`

Bulk operation completed (may have partial success)

- BulkUpsertCarriersResponse
  - `total` integer: Total number of carriers in the request
  - `successCount` integer: Number of carriers successfully processed
  - `failureCount` integer: Number of carriers that failed to process
  - `errors` object[]: Details of failures (if any)
    - `index` integer: Index of the carrier in the original request array
    - `error` string: Error message

## Other responses

- `400`: Bad request (e.g., exceeds maximum batch size)
- `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)