NMFTA Events API

openapi: 3.2.0
info:
  title: In-Transit Visibility Events API
  version: 1.0.0-public-preview
  contact:
    name: DSDC APIs Full Truckload
    url: https://github.com/dsdcapis/full-truckload
  license:
    name: DSDC Repository License
    url: https://github.com/dsdcapis/full-truckload/blob/main/LICENSE.md
  description: "# Overview\nIn-Transit Visibility is the capability to track freight movements through milestones, events and \nlocation updates in real time, from pickup to delivery. It is vital to the lifecycle of a load because\nit provides insight into where a shipment is at each stage and alerts all parties of important\nmilestones or issues. This capability ties into the broader Digital Standards Development\nCouncil open API standards initiative, which aims to digitize data exchange in freight\ntransportation. By adopting standard APIs, the industry can reduce manual processes, improve\ndata accuracy, increase visibility into shipments, enable real-time notifications of shipment\nchanges, and drive process automation.\n\nShippers today continue to demand real-time updates at every key milestone - before pickup,\nduring transit, and upon arrival. In response, industry leaders are making automated digital\ntracking a core part of operations, replacing phone calls and emails with API-based status\nsharing. This broad industry trend underscores how critical in-transit visibility has become. It\nalso reinforces the NMFTA's mission to standardize visibility.\n\nBy implementing this API, all parties - shippers, carriers, and intermediaries - share a single\nsource of truth about a load's status. In-transit updates, when combined with other NMFTA\nstandard APIs (e.g. electronic tendering and eBOL), form a continuous digital thread from load\ncreation to completion, greatly enhancing transparency and efficiency in freight movements.    \n# Value Proposition\n\n## Shipper\n\nGaining in-transit visibility allows shippers to easily get updates on the status and location of their shipments, reducing misunderstandings, human error, and theft. For example, instead of waiting for manual updates, a shipper can see when a load is picked up, in transit, or delayed, and even receive location updates before pickup occurs. This proactive insight gives shippers peace of mind and the ability to address exceptions quickly.\n\n## Carrier\n\nThe In-Transit Visibility API allows carriers to provide digital status updates to relevant parties using a standard protocol. This approach enables tracking information to be shared with shippers and third-party logistics providers (3PLs), supporting automated communication of updates such as departure, arrival, or delay notifications, and contributing to operational transparency.\n\n## 3rd Party\n\nThe In-Transit Visibility API will allow third parties of all kinds to receive and send necessary shipment information to ensure a seamless flow through the life cycle of a shipment. Due to the nature of their business and having to interact with multiple parties in the transportation industry, they stand much to gain by simplification of their business processes, which the In-Transit Visibility specification will enable. Overall, the In-Transit Visibility standard helps 3rd parties coordinate more effectively and provide better service with less overhead.\n\n# Capabilities:\n\n- Pull events: GET /v1/events (page-based, deterministic ordering)\n- Webhook delivery: webhooks/shipmentEvents (EventBatch + HMAC)\n- Subscription management: /v1/subscriptions\n- Pagination strategy: Page-Based method with page/pageSize\n- Standardized event types\n- Ordering, idempotency, retries\n- [RFC 7807 Problem Details](https://datatracker.ietf.org/doc/html/rfc7807)\n\n# Product Requirements Document (PRD)\n\nThe Product Requirements Document (PRD) for this API can be found [here](https://dsdcapis.github.io/full-truckload/api-prds/API%20Product%20Requirements%20-%20In%20Transit%20Visibility.pdf).\n"
tags:
- name: Events
  description: Pull shipment events
paths:
  /v1/events:
    get:
      tags:
      - Events
      summary: List shipment events (page-based)
      operationId: listEvents
      description: "Returns a page of events. Pagination in headers; body uses EventsPage for consistency.\nResults are deterministically ordered by `shipmentId`, `sequence`, `id`.      \n"
      parameters:
      - in: query
        name: shipmentId
        schema:
          type: string
        description: Filter by canonical shipment id.
      - in: query
        name: eventTypes
        schema:
          type: array
          items:
            $ref: ./schemas/schemas.yaml#/components/schemas/EventType
        description: One or more event types.
      - in: query
        name: occurredFrom
        schema:
          type: string
          format: date-time
        description: occurredAt >= this timestamp.
      - in: query
        name: occurredTo
        schema:
          type: string
          format: date-time
        description: occurredAt < this timestamp.
      - in: query
        name: page
        schema:
          type: integer
          minimum: 1
          default: 1
        description: 1-based page index.
      - in: query
        name: pageSize
        schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 100
        description: Results per page.
      - in: query
        name: order
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
        description: Sort direction on `shipmentId`, `sequence`, `id`.
      responses:
        '200':
          description: A page of events
          content:
            application/json:
              schema:
                $ref: ./schemas/schemas.yaml#/components/schemas/EventsPage
        default:
          $ref: ./schemas/schemas.yaml#/components/responses/UnexpectedError