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

# Upsert carrier relationships

> Create or update carrier relationships and statuses from your TMS to Cargado.
If a carrier is not found, the relationship will be null.
Returns the relationships in the same order and length as the input.


## OpenAPI

````yaml /openapi.yml post /carrier-relationships/upsert
openapi: 3.1.0
info:
  title: Cargado API
  version: 1.0.0
  description: Cargado's API
  termsOfService: https://cargado.com/terms/
  contact:
    email: dev-support@cargado.com
servers:
  - url: https://api.cargado.com
    description: The production Cargado API server
security: []
tags:
  - name: Border Crossings
  - name: Loads
  - name: Rates
  - name: CarrierRelationship
  - name: User
  - name: Team
  - name: Webhooks
  - name: Bids
paths:
  /carrier-relationships/upsert:
    post:
      tags:
        - CarrierRelationship
      summary: Upsert carrier relationships
      description: >-
        Create or update carrier relationships and statuses from your TMS to
        Cargado.

        If a carrier is not found, the relationship will be null.

        Returns the relationships in the same order and length as the input.
      operationId: UpsertACarrierRelationship
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierRelationshipUpsertInput'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierRelationshipUpsertOutput'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                required:
                  - message
                type: object
              examples:
                Example 1:
                  value:
                    message: Unauthorized
      security:
        - apiKey: []
components:
  schemas:
    CarrierRelationshipUpsertInput:
      properties:
        carrierRelationships:
          items:
            $ref: '#/components/schemas/CarrierRelationshipInput'
          type: array
      required:
        - carrierRelationships
      type: object
      additionalProperties: true
    CarrierRelationshipUpsertOutput:
      properties:
        carrierRelationships:
          items:
            allOf:
              - $ref: '#/components/schemas/CarrierRelationship'
            nullable: true
          type: array
      required:
        - carrierRelationships
      type: object
      additionalProperties: true
    CarrierRelationshipInput:
      properties:
        carrier:
          $ref: '#/components/schemas/CarrierInput'
        status:
          $ref: '#/components/schemas/CarrierRelationshipStatus'
        onboardingStatus:
          $ref: '#/components/schemas/CarrierOnboardingStatus'
        carrierExternalId:
          type: string
          description: |-
            An external identifier for the carrier in your TMS. When provided,
            this ID is stored on the carrier relationship and can be used to
            consistently match carriers during load sync.
          minLength: 1
          maxLength: 255
          examples:
            - GJNTMIIN
      required:
        - carrier
        - status
        - onboardingStatus
      type: object
      additionalProperties: true
    CarrierRelationship:
      description: >-
        A carrier relationship represents the relationship between a carrier and

        an organization, including their onboarding status and whether they can
        be

        assigned to freight.


        If a carrier relationship is not found, the carrier will be offered an
        onboarding link

        but will not be assigned to freight until a relationship is created.


        A NEEDS_REVIEW but onboarded carrier still requires manual review prior
        to being assigned

        to freight. An ACTIVE but not onboarded carrier can be assigned to
        freight but the

        carrier is still offered an onboarding link.


        DO_NOT_DISPATCH should be used to block a carrier from being assigned to
        freight at an

        organization level. Use freight level rules to block a carrier from
        being assigned to

        specific freight.
      properties:
        id:
          type: string
        organizationId:
          type: string
        carrierOrganizationId:
          type: string
        status:
          $ref: '#/components/schemas/CarrierRelationshipStatus'
        onboardingStatus:
          $ref: '#/components/schemas/CarrierOnboardingStatus'
        source:
          $ref: '#/components/schemas/CarrierRelationshipSource'
        carrierExternalId:
          type: string
          description: |-
            An external identifier for the carrier in your TMS. When provided,
            this ID is stored on the carrier relationship and can be used to
            consistently match carriers during load sync.
          minLength: 1
          maxLength: 255
          examples:
            - GJNTMIIN
      required:
        - id
        - organizationId
        - carrierOrganizationId
        - status
        - onboardingStatus
      type: object
      additionalProperties: true
    CarrierInput:
      description: |-
        A specific carrier as defined by a set of unique government identifiers.
        At least one of the identifiers must be provided.
      properties:
        dotNumber:
          type: string
          description: The carrier's DOT number
          examples:
            - '123456'
        mcNumber:
          type: string
          description: The carrier's MC number
          examples:
            - '248243'
        mxNumber:
          type: string
          description: The carrier's MX number
          examples:
            - '2343'
        rfcNumber:
          type: string
          description: The carrier's RFC number
          examples:
            - RUSM2344227MY4
        cvorNumber:
          type: string
          description: The carrier's Commercial Vehicle Operator Registration number (CVOR)
          examples:
            - 2344227MY4
        nirNumber:
          type: string
          description: The carrier's Registration identification number (NIR)
          examples:
            - R-23424
        nscNumber:
          type: string
          description: The carrier's National Safety Code (NSC) number
          examples:
            - 2344227MY4
        externalId:
          type: string
          description: >-
            An external identifier for the carrier in your TMS. This is used to

            match carriers across systems when government identifiers (DOT, MC)

            are not available on the source record.


            Examples: McLeod's vendor/payee ID ("GJNTMIIN"), Tai's
            carrierMasterId.
          minLength: 1
          maxLength: 255
          examples:
            - GJNTMIIN
      type: object
      additionalProperties: true
    CarrierRelationshipStatus:
      type: string
      enum:
        - ACTIVE
        - NEEDS_REVIEW
        - DO_NOT_DISPATCH
      description: >-
        - ACTIVE: The carrier is active with the organization and ready to be
        assigned to freight.

        - NEEDS_REVIEW: The carrier needs review prior to being assigned to
        freight.

        - DO_NOT_DISPATCH: The carrier is not allowed to be assigned to freight,
        and will not see


          any freight in the marketplace.
    CarrierOnboardingStatus:
      type: string
      enum:
        - ONBOARDED
        - NEEDS_TO_ONBOARD
      description: >-
        There are 2 possible values for a carrier relationship status:

        - ONBOARDED: The carrier is onboarded.

        - NEEDS_TO_ONBOARD: The carrier needs to be onboarded, even if they have
        been onboarded before.
    CarrierRelationshipSource:
      type: string
      enum:
        - API
        - USER
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: api-key

````