Loadsmart Shippers API

openapi: 3.2.0
info:
  title: Loadsmart Shippers 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: Shippers
  description: 'Manage shippers. A shipper is a company that creates and manages

    loads on Loadsmart platform.

    '
paths:
  /api/v2/shippers:
    post:
      summary: Create shipper
      tags:
      - Shippers
      security:
      - Application-JWT:
        - shipper_write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                  description: Unique identifier for this shipper
                  readOnly: true
                company_name:
                  type: string
                  description: Company name
                  minLength: 10
                  maxLength: 255
                account:
                  type: object
                  writeOnly: true
                  properties:
                    email:
                      type: string
                      format: email
                      description: User's email address
                      maxLength: 100
                    first_name:
                      type: string
                      description: User's first name
                      maxLength: 255
                    last_name:
                      type: string
                      description: User's last name
                      maxLength: 255
                    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/)
                    verification_channel:
                      type: string
                      enum:
                      - email
                      - sms
                      description: Channel selected to send the verification code
                  required:
                  - email
              required:
              - company_name
            example:
              company_name: Shipper Ship Inc.
      responses:
        '201':
          description: Shipper was created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: Unique identifier for this shipper
                        readOnly: true
                      company_name:
                        type: string
                        description: Company name
                        minLength: 10
                        maxLength: 255
                    required:
                    - company_name
              example:
                data:
                  id: 6faebc3d-4423-45eb-bce6-ee6601b155f9
                  company_name: Shipper Ship Inc.
        '422':
          description: Payload is invalid and a shipper can't be created
          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.
  /api/v2/shippers/{shipper_id}:
    patch:
      summary: Update shipper
      tags:
      - Shippers
      security:
      - Application-JWT:
        - shipper_write
      parameters:
      - in: path
        name: shipper_id
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                  description: Unique identifier for this shipper
                  readOnly: true
                company_name:
                  type: string
                  description: Company name
                  minLength: 10
                  maxLength: 255
              required:
              - company_name
            example:
              company_name: Some Shipper Ship Inc.
      responses:
        '200':
          description: Shipper was updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: Unique identifier for this shipper
                        readOnly: true
                      company_name:
                        type: string
                        description: Company name
                        minLength: 10
                        maxLength: 255
                    required:
                    - company_name
              example:
                data:
                  id: ad5aa25c-3e20-4de8-aeba-3a71d3c3242c
                  company_name: Some Shipper Ship Inc.
        '422':
          description: Payload is invalid and a shipper can't be updated
          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.
components:
  securitySchemes:
    Application-JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "Authorize the request with the application context (preferred\nfor the endpoints that support it):\n\n```\n{\n  \"sub\": \"sys\",\n  \"iss\": \"token-issuer\",\n  \"exp\": 1626239022,\n  \"iat\": 1517239022\n}\n```\n"
    User-JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "Authorize the request with an user context. A payload example\nwould be:\n\n```\n{\n  \"sub\": \"usr:87127882-d1db-4e50-8f7c-c792a80d7c49\",\n  \"iss\": \"token-issuer\",\n  \"iat\": 1517239022,\n  \"exp\": 1626239022\n}\n```\n"