API docs by Redocly

In-Transit Visibility API (1.0.0-public-preview)

Download OpenAPI specification:Download

URL: https://github.com/dsdcapis/full-truckload License: DSDC Repository License

Overview

In-Transit Visibility is the capability to track freight movements through milestones, events and location updates in real time, from pickup to delivery. It is vital to the lifecycle of a load because it provides insight into where a shipment is at each stage and alerts all parties of important milestones or issues. This capability ties into the broader Digital Standards Development Council open API standards initiative, which aims to digitize data exchange in freight transportation. By adopting standard APIs, the industry can reduce manual processes, improve data accuracy, increase visibility into shipments, enable real-time notifications of shipment changes, and drive process automation.

Shippers today continue to demand real-time updates at every key milestone - before pickup, during transit, and upon arrival. In response, industry leaders are making automated digital tracking a core part of operations, replacing phone calls and emails with API-based status sharing. This broad industry trend underscores how critical in-transit visibility has become. It also reinforces the NMFTA's mission to standardize visibility.

By implementing this API, all parties - shippers, carriers, and intermediaries - share a single source of truth about a load's status. In-transit updates, when combined with other NMFTA standard APIs (e.g. electronic tendering and eBOL), form a continuous digital thread from load creation to completion, greatly enhancing transparency and efficiency in freight movements.

Value Proposition

Shipper

Gaining 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.

Carrier

The 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.

3rd Party

The 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.

Capabilities:

  • Pull events: GET /v1/events (page-based, deterministic ordering)
  • Webhook delivery: webhooks/shipmentEvents (EventBatch + HMAC)
  • Subscription management: /v1/subscriptions
  • Pagination strategy: Page-Based method with page/pageSize
  • Standardized event types
  • Ordering, idempotency, retries
  • RFC 7807 Problem Details

Product Requirements Document (PRD)

The Product Requirements Document (PRD) for this API can be found here.

Events

Pull shipment events

List shipment events (page-based)

Returns a page of events. Pagination in headers; body uses EventsPage for consistency. Results are deterministically ordered by shipmentId, sequence, id.

query Parameters
shipmentId
string

Filter by canonical shipment id.

eventTypes
Array of strings (Event Type)
Items Enum: "PICKUP_SCHEDULED" "PICKUP_ATTEMPTED" "PICKED_UP" "ARRIVED_AT_TERMINAL" "DEPARTED_TERMINAL" "IN_TRANSIT" "DELAY" "EXCEPTION" "CUSTOMS_HOLD" "CUSTOMS_CLEARED" "OUT_FOR_DELIVERY" "DELIVERY_ATTEMPTED" "DELIVERED" "PROOF_OF_DELIVERY" "CANCELLED" "GATE_IN" "GATE_OUT" "VESSEL_LOADED" "VESSEL_UNLOADED" "RAIL_ARRIVAL" "RAIL_DEPARTURE" "AIR_DEPARTURE" "AIR_ARRIVAL" "OTHER"

One or more event types.

occurredFrom
string <date-time>

occurredAt >= this timestamp.

occurredTo
string <date-time>

occurredAt < this timestamp.

page
integer >= 1
Default: 1

1-based page index.

pageSize
integer [ 1 .. 500 ]
Default: 100

Results per page.

order
string
Default: "asc"
Enum: "asc" "desc"

Sort direction on shipmentId, sequence, id.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "page": 1,
  • "pageSize": 0,
  • "totalPages": 0,
  • "totalCount": 0
}

Subscriptions

Manage webhook subscriptions

List subscriptions

Returns a page of subscriptions. Pagination in headers; body uses SubscriptionsPage for consistency. Results are deterministically ordered by id.

query Parameters
status
string
Default: "active"
Enum: "active" "paused" "inactive"
page
integer >= 1
Default: 1
pageSize
integer [ 1 .. 200 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "page": 0,
  • "pageSize": 0,
  • "totalPages": 0,
  • "totalCount": 0
}

Create a subscription

Create a subscription to receive in-transit events via webhook. Provide the delivery configuration webhook url and hmac_secret_id and filters event_types and shipment IDs. Returns the created Subscription on success.

Request Body schema: application/json
required
endpointUrl
required
string <uri>
hmacSecretId
required
string

Reference to the stored secret used for HMAC signing.

object
object (DeliveryMetadata)

Responses

Request samples

Content type
application/json
{
  • "endpointUrl": "http://example.com",
  • "hmacSecretId": "string",
  • "filters": {
    },
  • "delivery": {
    }
}

Response samples

Content type
application/json
{
  • "endpointUrl": "http://example.com",
  • "hmacSecretId": "string",
  • "filters": {
    },
  • "delivery": {
    },
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "status": "active"
}

Get a subscription

Retrieve a single subscription by its unique ID. Returns the subscription's current configuration and status.

path Parameters
subscriptionId
required
string

Responses

Response samples

Content type
application/json
{
  • "endpointUrl": "http://example.com",
  • "hmacSecretId": "string",
  • "filters": {
    },
  • "delivery": {
    },
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "status": "active"
}

Update a subscription (merge-patch)

Partial update using JSON Merge Patch. Provide only fields you want to change.

path Parameters
subscriptionId
required
string
Request Body schema: application/merge-patch+json
required
endpointUrl
string <uri>
hmacSecretId
string

Reference to the stored secret used for HMAC signing.

object
object (DeliveryMetadata)
status
string
Default: "active"
Enum: "active" "paused" "inactive"

Responses

Request samples

Content type
application/merge-patch+json
{
  • "endpointUrl": "http://example.com",
  • "hmacSecretId": "string",
  • "filters": {
    },
  • "delivery": {
    },
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "endpointUrl": "http://example.com",
  • "hmacSecretId": "string",
  • "filters": {
    },
  • "delivery": {
    },
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "status": "active"
}

Delete a subscription

Delete a subscription by its unique ID. Stops future deliveries and removes the subscription.

path Parameters
subscriptionId
required
string

Responses

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "status": 100,
  • "title": "string",
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "errors": [
    ]
}

Shipment events webhook (from Carrier -> Subscriber) Webhook

We POST batches of events to your configured endpointUrl.

Request Body schema: application/json
required
deliveryId
required
string

Stable id for this delivery (constant across retries).

sentAt
required
string <date-time>

When the batch was sent by the publisher.

required
Array of objects (Event) non-empty

Responses

Request samples

Content type
application/json
{
  • "deliveryId": "string",
  • "sentAt": "2019-08-24T14:15:22Z",
  • "events": [
    ]
}

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "status": 100,
  • "title": "string",
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "errors": [
    ]
}