Loadsmart Carrier API

openapi: 3.2.0
info:
  title: Loadsmart Carrier API
  x-logo:
    altText: Loadsmart API
    url: https://developer.loadsmart.com/logo.svg
  description: "Loadsmart API provides endpoints to quote, book and track shipments autonomously.\n\n# Authentication\n\nLoadsmart API supports JWT tokens for authentication, signed using\npublic/private key pairs (RSA 4096).\n\n## What is JWT?\n\nJSON Web Token (JWT) is an [open standard](https://tools.ietf.org/html/rfc7519) used to\ncreate access tokens that contain some number of claims and is cryptographically signed by\nthe issuer, so its integrity can be verified without an auth server.\n\n## Token algorithm\n\nWe support JWT tokens signed using RS256 algorithm:\n\n```\n{\n  \"alg\": \"RS256\",\n  \"typ\": \"JWT\"\n}\n```\n\n## Required Claims\n\nFor the token payload, we require at least the following claims:\n\n- `sub`: Identifies the subject of the API call. This could be\n  either `sys` (without any user or client context) or `usr:UUID`,\n  where `UUID` is the uuid of the user that will provide the\n  context for the API call.\n- `iss`: Identifies who issued the token. This will be provided by\n  Loadsmart when setting up the integration.\n- `iat`: Standard \"issued at\" claim; should be an unix timestamp.\n- `exp`: Standard \"expires at\" claim; should be an unix timestamp.\n  We recomend to keep the token as short-lived as possible - ideally\n  it should not be valid for more than 1 minute. In the future,\n  Loadsmart could reject tokens with high expiration times.\n\n## Using the token\n\nThe token must be present in the `Authorization` header on all\nrequests, following the format:\n\n```\nAuthorization: JWT <token>\n```\n\nEach part of the token is encoded in base64 and joined with a dot separating each encoded part -\nif you use a library to generate it (which is recommended), you don't need to worry about it.\n\n**Important: Authorization header value must have the prefix `JWT`**.\n\nSee an example:\n\n```\nAuthorization: JWT eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.TCYt5XsITJX1CxPCT8yAV-TVkIEq_PbChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUcX16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTwLtjPAYuNzVBAh4vGHSrQyHUdBBPM\n```\n\n## Available contexts\n\nEach token has an implicit context associated with it (usually depending on the value of `sub`\nclaim). This context identifies to the API if the entity doing an action is an user or a system.\n\nLoadsmart API has different token contexts depending on the endpoint being called. Each endpoint\nwill specify the supported contexts (and required scopes) in `AUTHORIZATIONS` section.\n\n<!-- ReDoc-Inject: <security-definitions> -->\n\n## API Access\n\nTo start using Loadsmart API, please get in touch through your\npoint of contact. They will direct you through the proper flow.\n\n### Creating a public/private key pair\n\nFor JWT tokens, you should provide your *public key*. To generate a\npublic and private key pair, you can use OpenSSL:\n\n```bash\n$ openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:4096\n$ openssl rsa -in private_key.pem -pubout -out public_key.pem\n```\n\n*Never* reuse keys between multiple systems.\n\nFor more information, checkout the [official JWT website](https://jwt.io/).\n"
  version: 1.0.0
servers:
- url: https://api.loadsmart.com
  description: Production server
- url: https://api.sandbox.loadsmart.com
  description: Sandbox environment
tags:
- name: Carrier
  description: 'This API allows partners to request integration for Carriers and also manage Carrier''s information.


    The usage of this API is detailed at https://developer.loadsmart.com/carrier-integrations/how-tos/how-to-connect.html.


    To sum up how to integrate a Carrier, follow these steps:

    * `Search a carrier` by its MC# or DOT;

    * `Request Integration for a Carrier`;

    * Check the status by `Detail Carrier Integration Request status`;

    * Once the status is `ACCEPTED`, do requests on behalf of this carrier.

    '
paths:
  /api/v2/carrier/search:
    get:
      summary: Search a carrier
      tags:
      - Carrier
      security:
      - Application-JWT:
        - carrier_search
      description: 'Search a carrier by dot or mc

        '
      parameters:
      - in: query
        name: mc
        schema:
          description: Carrier mc
          type: string
          format: integer
        required: false
      - in: query
        name: dot
        schema:
          description: Carrier dot
          type: string
          format: integer
        required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  mc:
                    type: string
                  dot:
                    type: string
                  eligible:
                    type: bool
                    description: 'Flag that report if the Carrier is eligible to carry loads

                      '
                  status:
                    type: string
                    enum:
                    - NEW
                    - PENDING
                    - READY
                    description: 'Onboarding process status:

                      `NEW` means that Carrier is New

                      `PENDING` means that Onboard Process is under review

                      `READY` means that Carrier is successfully onboarded

                      '
              example:
                id: 9b739d7a-b4db-45f7-a61b-990c7ac77082
                dot: '2953461'
                mc: '456'
                status: New
                eligible: false
                name: J R T TRANS CORP
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                    - invalid_data
                  error_description:
                    type: string
                    description: Description of what happened
                  errors:
                    type: object
                    description: Object where each field is a key and the value is an array of errors
                required:
                - error
                - error_description
              example:
                missing_parameters:
                - query must have mc or dot fields
        '404':
          description: Carrier not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                    - invalid_data
                  error_description:
                    type: string
                    description: Description of what happened
                  errors:
                    type: object
                    description: Object where each field is a key and the value is an array of errors
                required:
                - error
                - error_description
              example:
                error: object_not_found
                error_description: Object not found
  /api/v2/carrier/integrations:
    get:
      summary: List of integrations
      tags:
      - Carrier
      security:
      - Application-JWT:
        - carrier_read
      description: 'List the integrations that the intermediary have with loadsmart

        '
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: An array of integrations
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                  count:
                    type: integer
                  next:
                    type: string
                  previous:
                    type: string
              example:
                count: 2
                next: null
                previous: null
                data:
                - id: f0c1b42c-9f8b-434e-9971-ae1c527e2680
                - id: d11a1f7c-fad9-4ff9-b0ba-34fc93f63c3f
  /api/v2/carrier/integration-request:
    post:
      summary: Request Integration for a Carrier
      description: '3PP can integrate a carrier and create a Carrier Account

        '
      security:
      - Application-JWT:
        - request_integration_write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                carrier_id:
                  type: string
                  description: Carrier UUID
                  maxLength: 255
                owner:
                  type: object
                  description: Company main contact information.
                  properties:
                    first_name:
                      type: string
                      description: First Name
                      maxLength: 255
                    last_name:
                      type: string
                      description: Last Name
                      maxLength: 255
                    email:
                      type: string
                      description: Email Address
                      maxLength: 255
                    phone_number:
                      type: string
                      pattern: \+\d{4,15}
                      maxLength: 16
                      description: Phone number following the format [E.164](https://www.itu.int/rec/T-REC-E.164/)
                    phone_number_extension:
                      type: string
                      description: Phone Number Extension
                      maxLength: 255
                  required:
                  - first_name
                  - last_name
                  - email
              required:
              - carrier_id
            example:
              carrier_id: 9f87d040-f843-42e7-887a-45bea55e76f3
              owner:
                first_name: John
                last_name: Doe
                email: john.doe@email.com
                phone_number: '+1111111111'
                phone_number_extension: '123'
      responses:
        '200':
          description: Integration Request with same data already exists
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique Identifier of the Integration Request
                  account_id:
                    type: string
                    description: Unique Identifier of the Account
                  carrier:
                    type: object
                    properties:
                      id:
                        type: string
                        description: Unique Identifier of the Carrier on Loadsmart
                      mc:
                        type: string
                        description: Carrier Interstate Operating Authority (MC number)
                      dot:
                        type: string
                        description: Carrier US DOT Number
                      name:
                        type: string
                        description: Carrier legal name
                      eligible:
                        type: bool
                        description: Flag that report if the Carrier is eligible to carry loads
                      status:
                        type: string
                        enum:
                        - New
                        - Pending
                        - Ready
                        - Inactive
                        description: Carrier status on Loadsmart
                  status:
                    type: string
                    enum:
                    - pending
                    - accepted
                    - rejected
                    description: 'Status of the Integration Request

                      - pending: waiting/under evaluation from Carrier owner and/or Loadsmart

                      - accepted: Integration Request accepted

                      - rejected: Integration Request rejected by Carrier owner and/or Loadsmart

                      '
                  documents:
                    type: array
                    description: List of required documents and its status
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          description: Document type (Form W9, Insurance or Authority)
                        status:
                          type: string
                          enum:
                          - missing
                          - under-review
                          - accepted
              example:
                id: fe17b7e7-6453-4520-b99d-2d2b44972468
                account_id: bc32c4d4-5732-7845-aa32-132cdab5467b
                carrier:
                  id: 9f87d040-f843-42e7-887a-45bea55e76f3
                  mc: '12345'
                  dot: '54321'
                  name: John Doe Freights
                  status: new
                  eligible: false
                status: PENDING
                documents:
                - type: w9
                  status: missing
                - type: insurance
                  status: under-review
                - type: authority
                  status: accepted
        '201':
          description: Integration Request successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique Identifier of the Integration Request
                  account_id:
                    type: string
                    description: Unique Identifier of the Account
                  carrier:
                    type: object
                    properties:
                      id:
                        type: string
                        description: Unique Identifier of the Carrier on Loadsmart
                      mc:
                        type: string
                        description: Carrier Interstate Operating Authority (MC number)
                      dot:
                        type: string
                        description: Carrier US DOT Number
                      name:
                        type: string
                        description: Carrier legal name
                      eligible:
                        type: bool
                        description: Flag that report if the Carrier is eligible to carry loads
                      status:
                        type: string
                        enum:
                        - New
                        - Pending
                        - Ready
                        - Inactive
                        description: Carrier status on Loadsmart
                  status:
                    type: string
                    enum:
                    - pending
                    - accepted
                    - rejected
                    description: 'Status of the Integration Request

                      - pending: waiting/under evaluation from Carrier owner and/or Loadsmart

                      - accepted: Integration Request accepted

                      - rejected: Integration Request rejected by Carrier owner and/or Loadsmart

                      '
                  documents:
                    type: array
                    description: List of required documents and its status
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          description: Document type (Form W9, Insurance or Authority)
                        status:
                          type: string
                          enum:
                          - missing
                          - under-review
                          - accepted
              example:
                id: fe17b7e7-6453-4520-b99d-2d2b44972468
                account_id: bc32c4d4-5732-7845-aa32-132cdab5467b
                carrier:
                  id: 9f87d040-f843-42e7-887a-45bea55e76f3
                  mc: '12345'
                  dot: '54321'
                  name: John Doe Freights
                  status: new
                  eligible: false
                status: PENDING
                documents:
                - type: w9
                  status: missing
                - type: insurance
                  status: under-review
                - type: authority
                  status: accepted
        '404':
          description: Carrier not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                    - invalid_data
                  error_description:
                    type: string
                    description: Description of what happened
                  errors:
                    type: object
                    description: Object where each field is a key and the value is an array of errors
                required:
                - error
                - error_description
              example:
                error: object_not_found
                error_description: Object not found
        '422':
          description: Integration already requested
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                    - invalid_data
                  error_description:
                    type: string
                    description: Description of what happened
                  errors:
                    type: object
                    description: Object where each field is a key and the value is an array of errors
                required:
                - error
                - error_description
              example:
                error: invalid_data
                error_description: Can't create the object
                errors:
                  field_name:
                  - This field is required.
                  other_field:
                  - Expected string but received integer.
      tags:
      - Carrier
    get:
      summary: List Carrier Integration Request status
      description: 'List partner''s integration requests

        '
      security:
      - Application-JWT:
        - request_integration_read
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: An array of integrations
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Unique Identifier of the Integration Request
                        carrier_id:
                          type: string
                          description: Unique Identifier of the Carrier on Loadsmart
                        mc:
                          type: string
                          description: Carrier Interstate Operating Authority (MC number)
                        dot:
                          type: string
                          description: Carrier US DOT Number
                        name:
                          type: string
                          description: Carrier legal name
                        status:
                          type: string
                          enum:
                          - pending
                          - accepted
                          - rejected
                          description: 'Status of the Integration Request

                            - pending: waiting/under evaluation from Carrier owner and/or Loadsmart

                            - accepted: Integration Request accepted

                            - rejected: Integration Request rejected by Carrier owner and/or Loadsmart

                            '
                  count:
                    type: integer
                  next:
                    type: string
                  previous:
                    type: string
              example:
                count: 1
                next: null
                previous: null
                data:
                - id: fe17b7e7-6453-4520-b99d-2d2b44972468
                  carrier_id: bc32c4d4-5732-7845-aa32-132cdab5467b
                  mc: '12345'
                  dot: '54321'
                  name: John Doe Freights
                  status: pending
        '404':
          description: No integration requests found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                    - invalid_data
                  error_description:
                    type: string
                    description: Description of what happened
                  errors:
                    type: object
                    description: Object where each field is a key and the value is an array of errors
                required:
                - error
                - error_description
              example:
                error: object_not_found
                error_description: Object not found
      tags:
      - Carrier
  /api/v2/carrier/integration-request/{id}:
    get:
      summary: Detail Carrier Integration Request status
      description: '3PP can check the Integrate Status of a Carrier

        '
      security:
      - Application-JWT:
        - request_integration_read
      parameters:
      - in: path
        name: id
        schema:
          description: Unique Integration Request identifier
          type: string
          format: uuid
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique Identifier of the Integration Request
                  account_id:
                    type: string
                    description: Unique Identifier of the Account
                  carrier:
                    type: object
                    properties:
                      id:
                        type: string
                        description: Unique Identifier of the Carrier on Loadsmart
                      mc:
                        type: string
                        description: Carrier Interstate Operating Authority (MC number)
                      dot:
                        type: string
                        description: Carrier US DOT Number
                      name:
                        type: string
                        description: Carrier legal name
                      eligible:
                        type: bool
                        description: Flag that report if the Carrier is eligible to carry loads
                      status:
                        type: string
                        enum:
                        - New
                        - Pending
                        - Ready
                        - Inactive
                        description: Carrier status on Loadsmart
                  status:
                    type: string
                    enum:
                    - pending
                    - accepted
                    - rejected
                    description: 'Status of the Integration Request

                      - pending: waiting/under evaluation from Carrier owner and/or Loadsmart

                      - accepted: Integration Request accepted

                      - rejected: Integration Request rejected by Carrier owner and/or Loadsmart

                      '
                  documents:
                    type: array
                    description: List of required documents and its status
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          description: Document type (Form W9, Insurance or Authority)
                        status:
                          type: string
                          enum:
                          - missing
                          - under-review
                          - accepted
              example:
                id: fe17b7e7-6453-4520-b99d-2d2b44972468
                account_id: bc32c4d4-5732-7845-aa32-132cdab5467b
                carrier:
                  id: 9f87d040-f843-42e7-887a-45bea55e76f3
                  mc: '12345'
                  dot: '54321'
                  name: John Doe Freights
                  status: new
                  eligible: false
                status: PENDING
                documents:
                - type: w9
                  status: missing
                - type: insurance
                  status: under-review
                - type: authority
                  status: accepted
        '404':
          description: Integrate Request not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                    - invalid_data
                  error_description:
                    type: string
                    description: Description of what happened
                  errors:
                    type: object
                    description: Object where each field is a key and the value is an array of errors
                required:
                - error
                - error_description
              example:
                error: object_not_found
                error_description: Object not found
      tags:
      - Carrier
  /api/v2/carrier/documents:
    post:
      summary: Upload document
      description: Uploads Carrier related documents, such as Form W9, Insurance and
      security:
      - User-JWT:
        - carrier_write
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                document_type:
                  type: string
                  enum:
                  - w9
                  - insurance
                  - authority
                  description: 'Type of document:

                    `w9`: Form W9

                    `insurance`: Certificate of Insurance

                    `authority`: Letter of Authority

                    '
                document:
                  type: string
                  format: binary
      responses:
        '200':
          description: File successfully uploaded
          content:
            application/json:
              schema:
                type: object
                properties:
                  document_url:
                    type: string
                    description: File URL
                  type:
                    type: string
                    enum:
                    - w9
                    - insurance
                    - authority
                    description: 'Type of document:

                      `w9`: Form W9

                      `insurance`: Certificate of Insurance

                      `authority`: Letter of Authority

                      '
                  verified:
                    type: boolean
                    description: File has been verified
        '422':
          description: Invalid or missing data
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                    - invalid_data
                  error_description:
                    type: string
                    description: Description of what happened
                  errors:
                    type: object
                    description: Object where each field is a key and the value is an array of errors
                required:
                - error
                - error_description
              example:
                error: invalid_data
                error_description: Can't create the object
                errors:
                  field_name:
                  - This field is required.
                  other_field:
                  - Expected string but received integer.
      tags:
      - Carrier
  /api/v2/carrier/drivers:
    get:
      summary: List drivers
      tags:
      - Carrier
      description: List drivers for this carrier.
      security:
      - User-JWT:
        - carrier_read
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: List of drivers
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Unique identifier for this driver
                          format: uuid
                          readOnly: true
                        name:
                          type: string
                          description: Driver's full name
                        phone_number:
                          type:
                          - string
                          - 'null'
                          pattern: \+\d{4,15}
                          maxLength: 16
                          description: Phone number following the format [E.164](https://www.itu.int/rec/T-REC-E.164/)
                        sms_enabled:
                          type: boolean
                          description: If this driver can receive Loadsmart text messages
                          default: true
                        location:
                          type: object
                          description: Driver's last location
                          readOnly: true
                      required:
                      - id
                      - name
                  count:
                    type: integer
                    description: The number of results in the payload.
                  next:
                    type: string
                    format: uri
                    description: An URL for the next result page.
                  previous:
                    type: string
                    format: uri
                    description: An URL for the previous result page.
                required:
                - data
              example:
                data:
                - id: a1336ea6-cf21-4515-a1fa-ab1d0153ef5b
                  name: Doralin Secret
                  phone_number: '+162331747869'
                  sms_enabled: true
                  location: null
                  owner_operator_id: null
                - id: a392494b-50f7-47f3-8125-bbf63ba930fa
                  name: Lorinda Jeyness
                  phone_number: +171 588 992 8431
                  sms_en

# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/loadsmart/refs/heads/main/openapi/loadsmart-carrier-api-openapi.yml