Loadsmart Asset Visit API

openapi: 3.2.0
info:
  title: Opendock Nova API Documentation Asset Visit API
  description: '## Welcome to Opendock Nova! #### What is Opendock Nova? Opendock is an online dock appointment scheduling tool. Facilities such as warehouses, distribution centers, and

    manufacturing plants use it to organize their docks and schedule appointments for outbound pickups and inbound

    deliveries. You can read all our knowledge base

    articles here. We now provide an SSO option for User Authentication. Read

    the docs here. ---


    ## Our APIs


    We have 3 main APIs:


    - REST API called _Neutron_ for performing standard HTTP operations. - Real-time API called _Subspace_ for receiving streaming events whenever objects are Created/Updated/Deleted. - A **"Reference Number Validation"** aka "PO Validation" _protocol_ for validating PO numbers (or similar) before an

    appointment is scheduled. Detailed documentation for it can be found

    here: PO/Ref Number Validation Implementation


    ---


    ## Neutron - REST API


    All endpoints are listed below. Depending on your User Role, some may be forbidden. Almost all endpoints expect a simple

    JWT token to be set in the `Authorization: Bearer` HTTP header. Read more about Bearer

    tokens here. ### Base URL


    The base URL is the same as it is for this document (look at the current URL in your browser''s address bar). For

    example, our production Neutron Base URL is https://neutron.opendock.com. ### Authentication


    To start, call the `POST /auth/login` endpoint to exchange your user credentials (email + password) for a simple JWT

    token. If you don''t have an account yet, reach out to your account admin or contact us for further help. If login is successful, the response will be a JWT token to use as your `Bearer` header as described above. The JWT expiration time depends on your User Role as well as other factors. You may base64-decode your JWT token to view

    more technical details about it. #### Test it:


    To test that your auth headers are set correctly, call the `GET /auth/me` endpoint. It will return a JSON payload with

    your User information. ---


    ## Subspace - Real-time Streaming API


    Subspace is a _read-only_ API that allows your system to recieve streaming real-time information about changes to your

    Appointments, Warehouses, Docks, etc. Using Subspace you can implement a "push"-based approach to your integration instead of relying only on "poll"-ing

    methods (which can be inefficient). Subpsace is based on the famous `socket.io` library. ### Choosing a socket.io Client


    The socket.io project provides a JavaScript client library that works in the browser as well as NodeJS. However there

    are also client implementations in many other languages including C#, Java, Python, and Go, so you should select the

    appropriate client for your project. A good overview of socket.io and a list of client implementations can be found

    here: Socket.IO Introduction


    **NOTE:** Currently Opendock uses socket.io server **v4.x** so please make sure to select an appropriate socket.io

    client version that is protocol compatible. ### Connecting and Authentication


    The base connection URL is the same as the base URL for Neutron above, except with the word "subspace" instead of "

    neutron". For example, our production Subspace connection URL

    is wss://subspace.opendock.com. For convenience, the same JWT token obtained from the Neutron `/auth/login` endpoint above is used for Subspace

    authentication. Connecting and Authenticating are done in a single operation: simply connect to the following `wss` URL:


    ```

    ?token=

    ```


    That can be a little confusing to parse. Here''s a real-life example connection string:


    ```

    wss://subspace.opendock.com?token=eyJhbGciOiJIUzI1Ni...(full token continues)

    ```


    **NOTE:** Currently Opendock only supports the `websocket` transport, so you must specify this in your connection

    settings. Here''s an example of connecting to Subspace using the JavaScript client:


    ```JavaScript

    // NOTE: we assume "accessToken" was already obtained earlier via a call to ''/auth/login''.'
  version: v4.144.0 - 39b4253
  contact: {}
servers:
- url: https://neutron.opendock.com
  description: Production Server
- url: https://neutron.staging.opendock.com
  description: Staging Server
tags:
- name: Asset Visit
paths:
  /asset-visit:
    post:
      operationId: createOneBaseAssetVisitControllerAssetVisit
      summary: Create a single AssetVisit
      parameters:
      - name: assetContainerId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAssetVisitDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetVisit'
        '201':
          description: Get create one base response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetVisit'
      tags:
      - Asset Visit
      security:
      - bearer: []
    get:
      operationId: getManyBaseAssetVisitControllerAssetVisit
      summary: Retrieve multiple AssetVisits
      parameters:
      - name: excludeStatuses
        required: false
        in: query
        description: Event types to exclude. Asset visits with any event matching these types will be filtered out.
        schema:
          type: array
          items:
            type: string
            enum:
            - NotArrived
            - Arrived
            - Docked
            - Departed
            - Canceled
            - Attached
            - Detached
            - Appointment Linked
            - Appointment Unlinked
            - RejectedByCheckin
            - RejectedByWarehouse
      - name: assetContainerId
        required: true
        in: path
        schema:
          type: string
      - name: fields
        description: Selects resource fields. <a href="https://github.com/nestjsx/crud/wiki/Requests#select" target="_blank">Docs</a>
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
        style: form
        explode: false
      - name: s
        description: Adds search condition. <a href="https://github.com/nestjsx/crud/wiki/Requests#search" target="_blank">Docs</a>
        required: false
        in: query
        schema:
          type: string
      - name: filter
        description: Adds filter condition. <a href="https://github.com/nestjsx/crud/wiki/Requests#filter" target="_blank">Docs</a>
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: or
        description: Adds OR condition. <a href="https://github.com/nestjsx/crud/wiki/Requests#or" target="_blank">Docs</a>
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: sort
        description: Adds sort by field. <a href="https://github.com/nestjsx/crud/wiki/Requests#sort" target="_blank">Docs</a>
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: join
        description: Adds relational resources. <a href="https://github.com/nestjsx/crud/wiki/Requests#join" target="_blank">Docs</a>
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: limit
        description: Limit amount of resources. <a href="https://github.com/nestjsx/crud/wiki/Requests#limit" target="_blank">Docs</a>
        required: false
        in: query
        schema:
          type: integer
      - name: offset
        description: Offset amount of resources. <a href="https://github.com/nestjsx/crud/wiki/Requests#offset" target="_blank">Docs</a>
        required: false
        in: query
        schema:
          type: integer
      - name: page
        description: Page portion of resources. <a href="https://github.com/nestjsx/crud/wiki/Requests#page" target="_blank">Docs</a>
        required: false
        in: query
        schema:
          type: integer
      - name: cache
        description: Reset cache (if was enabled). <a href="https://github.com/nestjsx/crud/wiki/Requests#cache" target="_blank">Docs</a>
        required: false
        in: query
        schema:
          type: integer
          minimum: 0
          maximum: 1
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaginatedDto'
                - properties:
                    entity:
                      type: string
                      example: AssetVisit
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/AssetVisit'
      tags:
      - Asset Visit
      security:
      - bearer: []
  /asset-visit/{id}:
    patch:
      operationId: updateOneBaseAssetVisitControllerAssetVisit
      summary: Update a single AssetVisit
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: assetContainerId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAssetVisitDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetVisit'
      tags:
      - Asset Visit
      security:
      - bearer: []
    get:
      operationId: getOneBaseAssetVisitControllerAssetVisit
      summary: Retrieve a single AssetVisit
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: assetContainerId
        required: true
        in: path
        schema:
          type: string
      - name: fields
        description: Selects resource fields. <a href="https://github.com/nestjsx/crud/wiki/Requests#select" target="_blank">Docs</a>
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
        style: form
        explode: false
      - name: join
        description: Adds relational resources. <a href="https://github.com/nestjsx/crud/wiki/Requests#join" target="_blank">Docs</a>
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: cache
        description: Reset cache (if was enabled). <a href="https://github.com/nestjsx/crud/wiki/Requests#cache" target="_blank">Docs</a>
        required: false
        in: query
        schema:
          type: integer
          minimum: 0
          maximum: 1
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetVisit'
      tags:
      - Asset Visit
      security:
      - bearer: []
    delete:
      operationId: deleteOneBaseAssetVisitControllerAssetVisit
      summary: Delete a single AssetVisit
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: assetContainerId
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: Delete one base response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetVisit'
      tags:
      - Asset Visit
      security:
      - bearer: []
  /asset-visit/event:
    post:
      operationId: AssetVisitController_createAssetVisitEvent
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAssetVisitEventDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetVisit'
      tags:
      - Asset Visit
      security:
      - bearer: []
      summary: Asset visit controller create asset visit event
      x-summary-source: derived
  /asset-visit/{id}/yard-events:
    get:
      operationId: AssetVisitController_getAssetVisitEvents
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      tags:
      - Asset Visit
      security:
      - bearer: []
      summary: Asset visit controller get asset visit events
      x-summary-source: derived
  /asset-visit/{id}/arrival-container:
    get:
      operationId: AssetVisitController_getArrivalAssetContainerForVisit
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AssetContainer'
      tags:
      - Asset Visit
      security:
      - bearer: []
      summary: Asset visit controller get arrival asset container for visit
      x-summary-source: derived
  /asset-visit/{id}/check-in-acknowledgment:
    patch:
      operationId: AssetVisitController_updateCheckInAcknowledgment
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAssetVisitAcknowledgmentDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetVisit'
      tags:
      - Asset Visit
      security:
      - bearer: []
      summary: Asset visit controller update check in acknowledgment
      x-summary-source: derived
  /asset-visit/{id}/attach/{assetContainerId}:
    post:
      operationId: AssetVisitController_attachContainer
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: assetContainerId
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      tags:
      - Asset Visit
      security:
      - bearer: []
      summary: Asset visit controller attach container
      x-summary-source: derived
  /asset-visit/{id}/detach/{assetContainerId}:
    post:
      operationId: AssetVisitController_detachContainer
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: assetContainerId
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      tags:
      - Asset Visit
      security:
      - bearer: []
      summary: Asset visit controller detach container
      x-summary-source: derived
  /asset-visit/link-unplanned-checkin-to-appointment:
    post:
      operationId: AssetVisitController_linkUnplannedCheckinToAppointment
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkUnplannedCheckinToAppointmentDto'
      responses:
        '200':
          description: ''
      tags:
      - Asset Visit
      security:
      - bearer: []
      summary: Asset visit controller link unplanned checkin to appointment
      x-summary-source: derived
  /asset-visit/unlink-checkin-from-appointment:
    post:
      operationId: AssetVisitController_unlinkCheckinFromAppointment
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnlinkAssetFromAppointmentDto'
      responses:
        '200':
          description: ''
      tags:
      - Asset Visit
      security:
      - bearer: []
      summary: Asset visit controller unlink checkin from appointment
      x-summary-source: derived
components:
  schemas:
    AssetContainer:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the record
          example: a0e1f2c3-d4e5-6f7g-8h9i-j0k1l2m3n4o5
          readOnly: true
        createDateTime:
          format: date-time
          type: string
          description: The date and time when the record was created
          example: '2023-10-01T12:00:00Z'
          readOnly: true
        createdBy:
          type: object
          description: The ID of the user who created the record
          example: a0e1f2c3-d4e5-6f7g-8h9i-j0k1l2m3n4o5
          readOnly: true
        lastChangedDateTime:
          format: date-time
          type: string
          description: The date and time when the record was last changed
          example: '2023-10-01T12:00:00Z'
          readOnly: true
        type:
          $ref: '#/components/schemas/AssetContainerType'
        state:
          $ref: '#/components/schemas/AssetContainerState'
        code:
          type: string
          description: The code of the asset container
          example: AC001
        notes:
          type: string
          description: Extra data about the asset container
          example: Asset container for storing goods
        lastLocationCheckConfirmedAt:
          type: object
          description: When a yard location check last confirmed the container present (server-set only; not generic “seen”).
          format: date-time
        assetVisitId:
          type: string
          format: uuid
          description: The id of the asset visit
          example: a0e4b1c2-3d4e-5f6g-7h8i-9j0k1l2m3n4o
        orgId:
          type: string
          format: uuid
        warehouseId:
          type: string
          format: uuid
          description: The id of the warehouse
          example: a0e4b1c2-3d4e-5f6g-7h8i-9j0k1l2m3n4o
        pickupAppointmentId:
          type: string
          format: uuid
          description: The id of the pickup appointment
          example: a0e4b1c2-3d4e-5f6g-7h8i-9j0k1l2m3n4o
        dropAppointmentId:
          type: string
          format: uuid
          description: The id of the drop appointment
          example: a0e4b1c2-3d4e-5f6g-7h8i-9j0k1l2m3n4o
        companyId:
          type: string
          format: uuid
          description: The id of the company that owns the asset container
          example: a0e4b1c2-3d4e-5f6g-7h8i-9j0k1l2m3n4o
      required:
      - id
      - createDateTime
      - createdBy
      - lastChangedDateTime
      - type
      - code
      - orgId
      - warehouseId
      - pickupAppointmentId
    UpdateAssetVisitAcknowledgmentDto:
      type: object
      properties:
        tags:
          type: object
    AssetVisitType:
      type: string
      description: The type of the asset visit
      enum:
      - LiveUnload
      - LiveLoad
      - Live
      - Drop
      - PickUp
      - DropHook
      - Unknown
    AssetVisit:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the record
          example: a0e1f2c3-d4e5-6f7g-8h9i-j0k1l2m3n4o5
          readOnly: true
        createDateTime:
          format: date-time
          type: string
          description: The date and time when the record was created
          example: '2023-10-01T12:00:00Z'
          readOnly: true
        createdBy:
          type: object
          description: The ID of the user who created the record
          example: a0e1f2c3-d4e5-6f7g-8h9i-j0k1l2m3n4o5
          readOnly: true
        lastChangedDateTime:
          format: date-time
          type: string
          description: The date and time when the record was last changed
          example: '2023-10-01T12:00:00Z'
          readOnly: true
        orgId:
          type: string
          format: uuid
        warehouseId:
          type: string
          format: uuid
          description: The id of the warehouse
          example: a0e4b1c2-3d4e-5f6g-7h8i-9j0k1l2m3n4o
        appointmentId:
          type: string
          format: uuid
          description: The id of the appointment
          example: a0e4b1c2-3d4e-5f6g-7h8i-9j0k1l2m3n4o
        secondaryAppointmentId:
          type: string
          format: uuid
          description: The id of the secondary appointment
          example: b1e4b1c2-3d4e-5f6g-7h8i-9j0k1l2m3n4p
        companyId:
          type: string
          format: uuid
          description: The id of the company
          example: a0e4b1c2-3d4e-5f6g-7h8i-9j0k1l2m3n4o
        phone:
          type: string
          description: The phone number of the driver
          example: '+14155552671'
        isPlanned:
          type: boolean
          description: Indicates if the visit has an appointment or not
          example: false
        companyHint:
          type: string
          description: A free-text to indicate the company name when there is no appointment
          example: Super Company CO.
        driverNotes:
          type: string
          description: Notes typed by the driver when checking in
          example: My truck is broken, please help me
        driverAppointmentIdentifier:
          type: string
          description: Appointment identification typed by the driver when checking in
          example: PO48593
        visitType:
          example: Live
          $ref: '#/components/schemas/AssetVisitType'
        checkInAcknowledged:
          type: boolean
          description: Whether the check-in was acknowledged by the warehouse or not
          example: false
        rejectReason:
          type: object
          description: The reason the asset visit was rejected
          example: Driver did not pass safety check
      required:
      - id
      - createDateTime
      - createdBy
      - lastChangedDateTime
      - orgId
      - warehouseId
      - phone
      - isPlanned
    PaginatedDto:
      type: object
      properties:
        count:
          type: number
          example: 2
        total:
          type: number
          example: 2
        page:
          type: number
          example: 1
        pageCount:
          type: number
          example: 1
        action:
          type: string
          example: read
        entity:
          type: string
          example: Appointment
        data:
          type: array
          items:
            type: string
      required:
      - count
      - total
      - page
      - pageCount
      - action
      - entity
      - data
    LinkUnplannedCheckinToAppointmentDto:
      type: object
      properties:
        tags:
          type: object
        appointmentId:
          type: string
        assetVisitId:
          type: string
        companyId:
          type: string
          deprecated: true
          description: 'Deprecated: company is resolved from the appointment user on the server. Optional for legacy clients only.'
      required:
      - appointmentId
      - assetVisitId
    UnlinkAssetFromAppointmentDto:
      type: object
      properties:
        tags:
          type: object
        appointmentId:
          type: string
        assetVisitId:
          type: string
      required:
      - appointmentId
      - assetVisitId
    AssetContainerState:
      type: string
      description: The state of the asset container
      enum:
      - Full
      - Empty
      - Partially Loaded
    AssetContainerType:
      type: string
      description: The type of the asset container
      enum:
      - Trailer
      - Container
      - Oversized
      - Chassis
      - Reefer
      - Other
    CreateAssetVisitEventDto:
      type: object
      properties:
        tags:
          type: object
    UpdateAssetVisitDto:
      type: object
      properties:
        tags:
          type: object
        appointmentId:
          type: string
          format: uuid
        companyId:
          type: object
          format: uuid
        licensePlate:
          type: string
        dotNumber:
          type: string
        companyHint:
          type: string
          maxLength: 128
          description: Free-text carrier name when no companyId is selected
        visitType:
          $ref: '#/components/schemas/AssetVisitType'
    AssetContainerDetailsDto:
      type: object
      properties: {}
    CreateAssetVisitDto:
      type: object
      properties:
        tags:
          type: object
        warehouseId:
          type: string
          format: uuid
        appointmentId:
          type: string
          format: uuid
        licensePlate:
          type: object
        dotNumber:
          type: object
        companyId:
          type: string
          format: uuid
        phone:
          type: string
          description: Driver Phone number in E.164 format
        useWhatsApp:
          type: boolean
          description: Whether to communicate via WhatsApp
        isPlanned:
          type: boolean
        companyHint:
          type: string
          description: Company name
        visitType:
          $ref: '#/components/schemas/AssetVisitType'
        driverNotes:
          type: string
          description: Driver notes for check-in
        driverAppointmentIdentifier:
          type: string
          description: Appointment identifier entered by the driver for check-in
        hasArrived:
          type: boolean
        assetContainerDetails:
          type: array
          items:
            $ref: '#/components/schemas/AssetContainerDetailsDto'
      required:
      - warehouseId
      - phone
      - useWhatsApp
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http