Augment Carrier Management API

openapi: 3.2.0
info:
  title: Augment Carrier Management API
  description: 'Augment is now SOC 2 Type II Certified


    The Augment API endpoints are calls your system makes to manage loads,

    carriers, and webhook configuration.

    The latest version of the Augment API is hosted online.


    ## API Endpoints


    Endpoints your system calls to interact with Augment:


    - Load Management

    - Carrier Management

    - CSV Imports

    - Quote Management - implemented by the

    rate provider and called by Augment

    - Models

    - Webhook Endpoints

    - Webhook Event Subscriptions


    Webhook management access is gated. Request access from Augment before using

    these endpoints. After access is enabled, you can self-manage the webhook

    endpoints that receive event payloads and the webhook event subscriptions

    that control which events are sent to each endpoint.


    Use Webhook Endpoints to create and

    update the HTTPS destinations where Augment sends webhook payloads. Use

    Webhook Event Subscriptions to

    choose event types for each endpoint and send test deliveries.


    Outbound webhook payloads, including Track & Trace events, are documented

    separately in the Webhooks reference. Subscriptions created

    through the public webhook management APIs deliver version 2 webhook payloads only.


    Quote Management is the exception to all

    of the above: that endpoint is implemented by the rate provider and called by

    Augment, which cannot retrieve quotes until it is live.


    ## Resources


    * Homepage

    * LinkedIn

    * Jobs - we''re hiring!


    ## Developer Notes


    All date-time fields are represented as strings. The date-time notation is defined by RFC 3339, section 5.6. Examples:

    - `2025-08-21T12:34:56Z`

    - `2025-08-21T04:34:56-08:00`


    However, when using local time, do not include the trailing `Z` or timezone offset in the date-time string.


    Example:

    - `2025-08-21T12:34:56`'
  version: 2.90.1
servers:
- url: https://api.prod.goaugment.com
security:
- httpBasic: []
tags:
- name: Carrier Management
  description: API endpoints for managing carriers, carrier contacts, and carrier-manager relationships.
paths:
  /v1/carriers:
    post:
      operationId: createOrUpdateCarrier
      tags:
      - Carrier Management
      summary: Create or update carrier
      description: '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.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierRequest'
            example:
              name: Acme Logistics
              tmsId: acme-tms-001
              dotNumber: 1234567
              mcNumber: 765432
              customData:
                tier: gold
                score: 98.5
                verified: true
                aliases:
                - Acme Freight
                - Acme Carriers LLC
                routing:
                  defaultRegion: NS
                  allowCrossBorder: false
      responses:
        '201':
          description: Carrier created or updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '422':
          description: Unprocessable Entity - Validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
    get:
      operationId: getCarrierByIdentifier
      tags:
      - Carrier Management
      summary: Get carrier by DOT or MC number
      description: Fetch a carrier by its DOT number or MC number. Returns the carrier with associated managers and contacts.
      parameters:
      - name: dotNumber
        in: query
        required: false
        schema:
          type: integer
        description: DOT number
      - name: mcNumber
        in: query
        required: false
        schema:
          type: integer
        description: MC number
      responses:
        '200':
          description: Carrier found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '404':
          description: Carrier not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
  /v1/carriers/bulk:
    post:
      operationId: bulkUpsertCarriers
      tags:
      - Carrier Management
      summary: Bulk create or update carriers
      description: 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.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkUpsertCarriersRequest'
      responses:
        '200':
          description: Bulk operation completed (may have partial success)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkUpsertCarriersResponse'
        '400':
          description: Bad request (e.g., exceeds maximum batch size)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '422':
          description: Unprocessable Entity - Validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
  /v1/carriers/{carrierId}:
    get:
      operationId: getCarrierById
      tags:
      - Carrier Management
      summary: Get carrier by ID
      description: Fetch a carrier by its carrier ID. Returns the carrier with associated managers and contacts.
      parameters:
      - name: carrierId
        in: path
        required: true
        schema:
          type: string
        description: Augment's carrier identifier, returned as `carrierId` in the create/update carrier response.
      responses:
        '200':
          description: Carrier found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '404':
          description: Carrier not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
    delete:
      operationId: archiveCarrier
      tags:
      - Carrier Management
      summary: Archive carrier
      description: Soft delete a carrier. The carrier will no longer be returned in GET requests.
      parameters:
      - name: carrierId
        in: path
        required: true
        schema:
          type: string
        description: Augment's carrier identifier, returned as `carrierId` in the create/update carrier response.
      responses:
        '204':
          description: Carrier archived successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '404':
          description: Carrier not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
components:
  schemas:
    CarrierRequest:
      type: object
      required:
      - name
      - tmsId
      x-property-order:
      - name
      - tmsId
      - status
      - complianceStatus
      - mcNumber
      - dotNumber
      - scac
      - address
      - email
      - phone
      - phoneExtension
      - managers
      - contacts
      - notes
      - customData
      properties:
        name:
          type: string
          description: Carrier name (required)
        tmsId:
          type: string
          description: TMS identifier for the carrier. Used for matching existing carriers. Cannot be changed after creation.
        status:
          type: object
          description: Carrier status.
          x-property-order:
          - code
          - reason
          properties:
            code:
              type: string
              enum:
              - ACTIVE
              - DO_NOT_USE
              description: Status code indicating the carrier's current state
            reason:
              type: string
              description: Optional reason for the status
        complianceStatus:
          type: object
          description: Compliance status information.
          properties:
            codes:
              type: object
              additionalProperties:
                type: string
              description: Compliance codes as key-value pairs
        mcNumber:
          type: integer
          description: MC number
        dotNumber:
          type: integer
          description: DOT number
        scac:
          type: string
          description: SCAC code
        address:
          type: object
          description: Carrier address.
          x-property-order:
          - name
          - company
          - street1
          - street2
          - city
          - stateOrProvince
          - postalCode
          - country
          properties:
            street1:
              type: string
              description: Street address line 1
            street2:
              type: string
              description: Street address line 2 (optional)
            city:
              type: string
              description: City name
            stateOrProvince:
              type: string
              description: State or province code
            postalCode:
              type: string
              description: Postal or ZIP code
            country:
              type: string
              description: 'Must be 2-letter ISO country code as listed here: https://www.iban.com/country-codes'
            name:
              type: string
              description: Location name (e.g., building name)
            company:
              type: string
              description: Company name
        email:
          type: string
          format: email
          description: Carrier email address.
        phone:
          type: string
          description: Phone number in E.164 format (e.g., +13125551234).
        phoneExtension:
          type: string
          description: Phone extension.
        managers:
          type: array
          description: Array of organization contacts (managers) who manage this carrier. Pass an empty array [] to clear all managers when updating.
          items:
            $ref: '#/components/schemas/BrokerageContactRequest'
        contacts:
          type: array
          description: Array of carrier contacts (carrier employees). Pass an empty array [] to clear all contacts when updating.
          items:
            $ref: '#/components/schemas/CarrierContactRequest'
        notes:
          type: string
          description: Free-form notes about the carrier.
        customData:
          $ref: '#/components/schemas/CarrierCustomData'
    BrokerageContactResponse:
      type: object
      x-property-order:
      - id
      - tmsId
      - name
      - email
      - phone
      - phoneExtension
      - preferredContactMode
      - roles
      properties:
        id:
          type: string
          description: Organization contact ID (ULID)
        name:
          type: string
          nullable: true
          description: Contact name
        tmsId:
          type: string
          nullable: true
          description: TMS identifier for the contact
        roles:
          type: array
          items:
            type: string
            enum:
            - CARRIER_REP
            - ACCOUNT_MANAGER
            - OPERATIONS_REP
            - OPERATIONS_MANAGER
            - BOOKED_BY
            - CUSTOMER_REP
            - CUSTOMER_TEAM
            - CARRIER_TEAM
            - AP_REP
            - AFTER_HOURS_REP
          description: '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:
          type: string
          nullable: true
          enum:
          - EMAIL
          - PHONE_CALL
          - TEXT_MESSAGE
          - TELEGRAM
          description: Preferred method of contact
        email:
          type: string
          nullable: true
          description: Contact email address
        phone:
          type: string
          nullable: true
          description: Phone number in E.164 format (e.g., +13125551234)
        phoneExtension:
          type: string
          nullable: true
          description: Phone extension
    BrokerageContactRequest:
      type: object
      x-property-order:
      - tmsId
      - name
      - email
      - phone
      - phoneExtension
      - preferredContactMode
      - roles
      properties:
        name:
          type: string
          description: Contact name
        email:
          type: string
          format: email
          description: Contact email address
        phone:
          type: string
          description: Phone number in E.164 format (e.g., +13125551234)
        phoneExtension:
          type: string
          description: Phone extension
        tmsId:
          type: string
          description: TMS identifier for matching existing contacts. If provided, the system will match and update the existing contact.
        roles:
          type: array
          items:
            type: string
            enum:
            - CARRIER_REP
            - ACCOUNT_MANAGER
            - OPERATIONS_REP
            - OPERATIONS_MANAGER
            - BOOKED_BY
            - CUSTOMER_REP
            - CUSTOMER_TEAM
            - CARRIER_TEAM
            - AP_REP
            - AFTER_HOURS_REP
          description: '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:
          type: string
          enum:
          - EMAIL
          - PHONE_CALL
          - TEXT_MESSAGE
          - TELEGRAM
          description: Preferred method of contact
    CarrierContactResponse:
      type: object
      x-property-order:
      - id
      - tmsId
      - name
      - email
      - phone
      - phoneExtension
      - preferredContactMode
      - roles
      properties:
        id:
          type: string
          description: Carrier contact ID (ULID)
        name:
          type: string
          nullable: true
          description: Contact name
        tmsId:
          type: string
          nullable: true
          description: TMS identifier for the contact
        roles:
          type: array
          items:
            type: string
            enum:
            - ACCOUNTANT
            - AP_REP
            - DISPATCHER
            - AFTER_HOURS_DISPATCHER
            - WEEKEND_DISPATCHER
            - BOOKING
            - TRACKING
            - DRIVER
            - OTHER
          description: '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:
          type: string
          nullable: true
          enum:
          - EMAIL
          - PHONE_CALL
          - TEXT_MESSAGE
          - TELEGRAM
          description: Preferred method of contact
        email:
          type: string
          nullable: true
          description: Contact email address
        phone:
          type: string
          nullable: true
          description: Phone number in E.164 format (e.g., +13125551234)
        phoneExtension:
          type: string
          nullable: true
          description: Phone extension
    ApiErrorBody:
      type: object
      required:
      - message
      x-property-order:
      - message
      - errorCode
      - details
      properties:
        message:
          type: string
          description: An error message
        errorCode:
          type: string
          description: An error code
        details:
          oneOf:
          - type: object
          - type: string
          description: Additional error details
    BulkUpsertCarriersRequest:
      type: object
      required:
      - carriers
      x-property-order:
      - carriers
      properties:
        carriers:
          type: array
          maxItems: 20
          description: Array of carriers to create or update. Maximum 20 carriers per request.
          items:
            $ref: '#/components/schemas/CarrierRequest'
    CarrierContactRequest:
      type: object
      x-property-order:
      - tmsId
      - name
      - email
      - phone
      - phoneExtension
      - preferredContactMode
      - roles
      properties:
        name:
          type: string
          description: Contact name
        email:
          type: string
          format: email
          description: Contact email address. Either email or phone is required.
        phone:
          type: string
          description: Phone number in E.164 format (e.g., +13125551234). Either email or phone is required.
        phoneExtension:
          type: string
          description: Phone extension
        tmsId:
          type: string
          description: TMS identifier for matching existing contacts. If provided, the system will match and update the existing contact.
        roles:
          type: array
          items:
            type: string
            enum:
            - ACCOUNTANT
            - AP_REP
            - DISPATCHER
            - AFTER_HOURS_DISPATCHER
            - WEEKEND_DISPATCHER
            - BOOKING
            - TRACKING
            - DRIVER
            - OTHER
          description: '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:
          type: string
          enum:
          - EMAIL
          - PHONE_CALL
          - TEXT_MESSAGE
          - TELEGRAM
          description: Preferred method of contact
    CarrierResponse:
      type: object
      x-property-order:
      - id
      - name
      - tmsId
      - status
      - complianceStatus
      - mcNumber
      - dotNumber
      - scac
      - address
      - email
      - phone
      - phoneExtension
      - managers
      - contacts
      - notes
      - customData
      properties:
        id:
          type: string
          description: Carrier ID (ULID)
        name:
          type: string
          description: Carrier name
        tmsId:
          type: string
          nullable: true
          description: TMS identifier for the carrier
        status:
          type: object
          nullable: true
          description: Carrier status
          x-property-order:
          - code
          - reason
          properties:
            code:
              type: string
              enum:
              - ACTIVE
              - DO_NOT_USE
              description: Status code indicating the carrier's current state
            reason:
              type: string
              nullable: true
              description: Optional reason for the status
        complianceStatus:
          type: object
          nullable: true
          description: Compliance status information
          properties:
            codes:
              type: object
              additionalProperties:
                type: string
              description: Compliance codes as key-value pairs
        mcNumber:
          type: integer
          nullable: true
          description: MC number
        dotNumber:
          type: integer
          nullable: true
          description: DOT number
        scac:
          type: string
          nullable: true
          description: SCAC code
        address:
          type: object
          nullable: true
          description: Carrier address
          x-property-order:
          - name
          - company
          - street1
          - street2
          - city
          - stateOrProvince
          - postalCode
          - country
          properties:
            street1:
              type: string
              description: Street address line 1
            street2:
              type: string
              nullable: true
              description: Street address line 2
            city:
              type: string
              description: City name
            stateOrProvince:
              type: string
              nullable: true
              description: State or province code
            postalCode:
              type: string
              description: Postal or ZIP code
            country:
              type: string
              description: Country code (2-letter ISO)
            name:
              type: string
              nullable: true
              description: Location name
            company:
              type: string
              nullable: true
              description: Company name
        email:
          type: string
          nullable: true
          description: Carrier email address
        phone:
          type: string
          nullable: true
          description: Phone number in E.164 format (e.g., +13125551234)
        phoneExtension:
          type: string
          nullable: true
          description: Phone extension
        managers:
          type: array
          description: Array of organization contacts (managers) who manage this carrier
          items:
            $ref: '#/components/schemas/BrokerageContactResponse'
        contacts:
          type: array
          description: Array of carrier contacts (carrier employees)
          items:
            $ref: '#/components/schemas/CarrierContactResponse'
        notes:
          type: string
          nullable: true
          description: Free-form notes about the carrier
        customData:
          description: 'Optional metadata returned for the carrier; `null` when none is stored.

            '
          oneOf:
          - $ref: '#/components/schemas/CarrierCustomData'
          - type: 'null'
    BulkUpsertCarriersResponse:
      type: object
      x-property-order:
      - total
      - successCount
      - failureCount
      - errors
      properties:
        total:
          type: integer
          description: Total number of carriers in the request
          example: 2
        successCount:
          type: integer
          description: Number of carriers successfully processed
        failureCount:
          type: integer
          description: Number of carriers that failed to process
        errors:
          type: array
          description: Details of failures (if any)
          items:
            type: object
            x-property-order:
            - index
            - error
            properties:
              index:
                type: integer
                description: Index of the carrier in the original request array
              error:
                type: string
                description: Error message
    CarrierCustomData:
      type: object
      description: '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.

        '
      additionalProperties: true
      example:
        tier: gold
        score: 98.5
        verified: true
        aliases:
        - Acme Freight
        - Acme Carriers LLC
        routing:
          defaultRegion: NS
          allowCrossBorder: false
  securitySchemes:
    httpBasic:
      type: http
      scheme: basic
      description: 'Authenticate with HTTP Basic auth by sending an empty username and your API key as the password, equivalent to encoding :<API_KEY> in the Basic credential.

        '
x-ext-urls: {}
x-provenance:
  method: harvested
  publisher: Augment
  source: https://apidocs.goaugment.com/reference/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)