Loadsmart Shipper Accounts API

openapi: 3.2.0
info:
  title: Loadsmart Shipper Accounts 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: Shipper Accounts
  description: 'Manage the accounts associated with shippers. An account

    represents an user.

    '
paths:
  /api/v2/shippers/accounts:
    post:
      summary: Create account
      tags:
      - Shipper Accounts
      security:
      - Application-JWT:
        - user_write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                  description: Unique identifier for this user
                  readOnly: true
                shipper_id:
                  type: string
                  format: uuid
                  description: Unique identifier for the shipper who this user belongs to
                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
                password:
                  type: string
                  description: Password the user will use to log into Loadsmart's website or in OAuth requests
                  maxLength: 255
              required:
              - shipper_id
              - email
            examples:
              minimal:
                summary: Minimal
                value:
                  shipper_id: ba0c0ff4-1db4-48e5-893d-a334dbae0000
                  email: john@example.com
              complete:
                summary: Complete
                value:
                  shipper_id: ba0c0ff4-1db4-48e5-893d-a334dbae0000
                  email: johndoe@example.com
                  first_name: John
                  last_name: Doe
                  phone_number: '+19995551234'
                  verification_code: email
                  password: my-strong-password
      responses:
        '201':
          description: Account was created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: Unique identifier for this user
                        readOnly: true
                      shipper_id:
                        type: string
                        format: uuid
                        description: Unique identifier for the shipper who this user belongs to
                      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
                      password:
                        type: string
                        description: Password the user will use to log into Loadsmart's website or in OAuth requests
                        maxLength: 255
                    required:
                    - shipper_id
                    - email
              example:
                data:
                  id: 6c082402-afe2-4130-bb23-20fb6f01b27f
                  shipper_id: ba0c0ff4-1db4-48e5-893d-a334dbae0000
                  email: johndoe@example.com
                  first_name: John
                  last_name: Doe
                  phone_number: '+19995551234'
        '409':
          description: An account with this email or phone number already exists
          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: user_duplicated_data
                error_description: Can't create the user
        '422':
          description: Account wasn't created because some data is missing or incorrect
          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/accounts/{account_id}:
    get:
      summary: Retrieve account
      description: Returns shipper account details
      tags:
      - Shipper Accounts
      security:
      - Application-JWT:
        - account_read
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: Unique identifier for this user
                        readOnly: true
                      shipper_id:
                        type: string
                        format: uuid
                        description: Unique identifier for the shipper who this user belongs to
                      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
                      password:
                        type: string
                        description: Password the user will use to log into Loadsmart's website or in OAuth requests
                        maxLength: 255
                    required:
                    - shipper_id
                    - email
              example:
                data:
                  avatar_url: 4b3abdd5-8a0f-4803-abab-d354704ebe3c.jpg
                  email: johndoe@email.com
                  first_name: John
                  last_name: Doe
                  id": 9ba86ef0-7c8f-487e-a7f9-60515078d9a2
                  phone_number": '+12345678901'
                  active": true
        '403':
          description: Logged shipper is not related to the uuid in the url
          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: forbiden_access
                error_description: An user is trying to access a not authorized resource.
        '404':
          description: Shipper account 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
    patch:
      summary: Update account
      description: Updates data of the current account (according to the token).
      tags:
      - Shipper Accounts
      security:
      - Application-JWT:
        - user_write
      parameters:
      - in: path
        name: account_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 user
                  readOnly: true
                shipper_id:
                  type: string
                  format: uuid
                  description: Unique identifier for the shipper who this user belongs to
                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
                password:
                  type: string
                  description: Password the user will use to log into Loadsmart's website or in OAuth requests
                  maxLength: 255
              required:
              - shipper_id
              - email
            example:
              email: johndoe@example.com
              first_name: John
              last_name: Doe
              phone_number: 19995551234
      responses:
        '200':
          description: Account updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: Unique identifier for this user
                        readOnly: true
                      shipper_id:
                        type: string
                        format: uuid
                        description: Unique identifier for the shipper who this user belongs to
                      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
                      password:
                        type: string
                        description: Password the user will use to log into Loadsmart's website or in OAuth requests
                        maxLength: 255
                    required:
                    - shipper_id
                    - email
              example:
                data:
                  id: 6c082402-afe2-4130-bb23-20fb6f01b27f
                  shipper_id: ba0c0ff4-1db4-48e5-893d-a334dbae0000
                  email: johndoe@example.com
                  first_name: John
                  last_name: Doe
                  phone_number: 19995551234
        '409':
          description: Another account with this email or phone number already exists
          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: user_duplicated_data
                error_description: Can't update the user
        '422':
          description: Informed account data is invalid
          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"