Documentation
Documentation
https://developers.project44.com/
Authentication
https://developers.project44.com/authentication
OpenAPI Specification
openapi: 3.1.0
info:
title: project44 Tracking Shipments API
description: project44 Tracking API provides real-time shipment tracking and visibility for multimodal freight including truckload (TL), LTL, ocean, rail, air, and parcel. APIs deliver shipment status updates, predictive ETAs, and exception alerts.
version: 2.0.0
contact:
name: project44 Support
url: https://support.project44.com
license:
name: project44 Terms of Service
url: https://www.project44.com/legal/
servers:
- url: https://api.project44.com/api/v4
description: project44 Production API
security:
- oauth2: []
tags:
- name: Shipments
description: Shipment tracking and management
paths:
/shipments:
post:
operationId: createShipment
summary: Create a tracked shipment
description: Creates a new shipment to track, associating it with carrier and identifier information.
tags:
- Shipments
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ShipmentCreate'
responses:
'201':
description: Shipment created
content:
application/json:
schema:
$ref: '#/components/schemas/Shipment'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
get:
operationId: listShipments
summary: List tracked shipments
description: Returns a paginated list of tracked shipments with current status.
tags:
- Shipments
parameters:
- name: status
in: query
description: Filter by shipment lifecycle status
schema:
type: string
enum:
- AT_STOP
- IN_TRANSIT
- COMPLETED
- EXCEPTION
- UNKNOWN
- name: mode
in: query
description: Transportation mode filter
schema:
type: string
enum:
- TL
- LTL
- OCEAN
- AIR
- RAIL
- PARCEL
- DRAY
- name: carrierId
in: query
description: Carrier SCAC code or project44 carrier ID
schema:
type: string
- name: updatedSince
in: query
description: Return shipments updated after this ISO 8601 timestamp
schema:
type: string
format: date-time
- name: page
in: query
schema:
type: integer
default: 0
- name: pageSize
in: query
schema:
type: integer
default: 50
maximum: 200
responses:
'200':
description: Shipment list
content:
application/json:
schema:
type: object
properties:
shipments:
type: array
items:
$ref: '#/components/schemas/Shipment'
pageInfo:
$ref: '#/components/schemas/PageInfo'
'401':
$ref: '#/components/responses/Unauthorized'
/shipments/{shipmentId}:
get:
operationId: getShipment
summary: Get a shipment
description: Returns current status, position, ETA, and event history for a shipment.
tags:
- Shipments
parameters:
- $ref: '#/components/parameters/ShipmentId'
responses:
'200':
description: Shipment details
content:
application/json:
schema:
$ref: '#/components/schemas/ShipmentDetail'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteShipment
summary: Stop tracking a shipment
description: Removes a shipment from active tracking.
tags:
- Shipments
parameters:
- $ref: '#/components/parameters/ShipmentId'
responses:
'204':
description: Shipment deleted
components:
schemas:
ShipmentStopInput:
type: object
required:
- stopNumber
- stopType
properties:
stopNumber:
type: integer
stopType:
type: string
enum:
- ORIGIN
- DESTINATION
- INTERMEDIATE
city:
type: string
state:
type: string
postalCode:
type: string
country:
type: string
maxLength: 3
appointmentWindow:
$ref: '#/components/schemas/TimeWindow'
PageInfo:
type: object
properties:
page:
type: integer
pageSize:
type: integer
totalCount:
type: integer
hasNextPage:
type: boolean
Shipment:
type: object
description: A tracked freight shipment
properties:
id:
type: string
format: uuid
description: project44 internal shipment ID
masterShipmentId:
type: string
description: Unique master shipment ID across modes
mode:
type: string
enum:
- TL
- LTL
- OCEAN
- AIR
- RAIL
- PARCEL
- DRAY
status:
type: string
enum:
- AT_STOP
- IN_TRANSIT
- COMPLETED
- EXCEPTION
- UNKNOWN
carrierCode:
type: string
description: Carrier SCAC code
carrierName:
type: string
proNumber:
type: string
description: PRO/tracking number
bolNumber:
type: string
description: Bill of lading number
poNumber:
type: string
description: Purchase order number
origin:
$ref: '#/components/schemas/ShipmentStop'
destination:
$ref: '#/components/schemas/ShipmentStop'
estimatedDelivery:
$ref: '#/components/schemas/ETAWindow'
currentPosition:
$ref: '#/components/schemas/Position'
exceptions:
type: array
items:
$ref: '#/components/schemas/ShipmentException'
createDatetime:
type: string
format: date-time
lastUpdateDatetime:
type: string
format: date-time
Error:
type: object
properties:
code:
type: string
message:
type: string
details:
type: array
items:
type: object
ShipmentDetail:
allOf:
- $ref: '#/components/schemas/Shipment'
- type: object
properties:
stops:
type: array
items:
$ref: '#/components/schemas/ShipmentStop'
statusUpdates:
type: array
items:
$ref: '#/components/schemas/StatusUpdate'
ShipmentCreate:
type: object
required:
- mode
- carrierCode
- identifiers
properties:
mode:
type: string
enum:
- TL
- LTL
- OCEAN
- AIR
- RAIL
- PARCEL
- DRAY
carrierCode:
type: string
description: SCAC code
identifiers:
type: array
description: At least one tracking identifier required
items:
type: object
required:
- type
- value
properties:
type:
type: string
enum:
- PRO
- BOL
- PO
- TRACKING_NUMBER
- CONTAINER_NUMBER
- BOOKING_NUMBER
value:
type: string
stops:
type: array
items:
$ref: '#/components/schemas/ShipmentStopInput'
ETAWindow:
type: object
properties:
estimatedAt:
type: string
format: date-time
confidenceLow:
type: string
format: date-time
confidenceHigh:
type: string
format: date-time
predictedOnTime:
type: boolean
predictedLateMinutes:
type: integer
nullable: true
ShipmentStop:
type: object
properties:
stopNumber:
type: integer
stopType:
type: string
enum:
- ORIGIN
- DESTINATION
- INTERMEDIATE
name:
type: string
address:
type: string
city:
type: string
state:
type: string
postalCode:
type: string
country:
type: string
maxLength: 3
latitude:
type: number
format: double
longitude:
type: number
format: double
appointmentWindow:
$ref: '#/components/schemas/TimeWindow'
actualArrival:
type: string
format: date-time
nullable: true
actualDeparture:
type: string
format: date-time
nullable: true
StatusUpdate:
type: object
properties:
updateId:
type: string
timestamp:
type: string
format: date-time
statusCode:
type: string
statusDescription:
type: string
city:
type: string
state:
type: string
country:
type: string
maxLength: 3
isException:
type: boolean
exceptionCode:
type: string
nullable: true
source:
type: string
enum:
- CARRIER_EDI
- CARRIER_API
- TELEMATICS
- MANUAL
ShipmentException:
type: object
properties:
exceptionCode:
type: string
description:
type: string
severity:
type: string
enum:
- LOW
- MEDIUM
- HIGH
- CRITICAL
timestamp:
type: string
format: date-time
resolvedAt:
type: string
format: date-time
nullable: true
TimeWindow:
type: object
properties:
startDateTime:
type: string
format: date-time
endDateTime:
type: string
format: date-time
Position:
type: object
properties:
timestamp:
type: string
format: date-time
latitude:
type: number
format: double
longitude:
type: number
format: double
heading:
type: number
format: double
nullable: true
speed:
type: number
format: double
nullable: true
speedUnit:
type: string
enum:
- MPH
- KPH
responses:
Unauthorized:
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
parameters:
ShipmentId:
name: shipmentId
in: path
required: true
description: project44 shipment identifier
schema:
type: string
format: uuid
securitySchemes:
oauth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://api.project44.com/api/v4/oauth2/token
scopes:
tracking.read: Read shipment tracking data
tracking.write: Create and manage shipments
webhooks.write: Manage webhook subscriptions