NMFTA In Transit Visibility API

openapi: 3.2.0
info:
  title: In-Transit Visibility In Transit Visibility 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: In Transit Visibility API
paths: {}
webhooks:
  shipmentEvents:
    post:
      summary: Shipment events webhook (from Carrier -> Subscriber)
      description: 'We POST batches of events to your configured `endpointUrl`.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./schemas/schemas.yaml#/components/schemas/EventBatch
      responses:
        '200':
          description: Acknowledged (no retry)
        '202':
          description: Accepted (no retry)
        default:
          $ref: ./schemas/schemas.yaml#/components/responses/UnexpectedError
      tags:
      - In Transit Visibility API