Skip to main content
GET
Get Load
Provisional endpoint
This endpoint is available for early access. The core schema is stable, but minor details — such as field names or added fields — may change before it becomes generally available. Backward compatibility is not guaranteed.

See API Stability & Versioning for details on provisional endpoints.

Authorizations

Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

load_id
string<uuid>
required

The unique identifier of the load.

Query Parameters

include_source_data
boolean
default:false

Include the raw data from the telematics provider. Useful for auditing or accessing fields not normalized by Catena

Response

Successful Response

Load model for API responses.

id
string<uuid>
required

Unique identifier of the record at Catena Telematics.

created_at
string<date-time>
required

Immutable: The datetime the record was ingested into Catena Telematics.

updated_at
string<date-time>
required

The datetime the record was last modified in Catena Telematics.

tms_connection_id
string<uuid>
required

Unique identifier of the connection at Catena Telematics through which this record was ingested. A TMS connection represents a TmsAccount/TMS pairing. No foreign key: TmsConnection lives in telematics-integrations-service's own database, so this is a logical reference only.

source_name
enum<string>
required

The underlying TMS platform that provided this data (e.g., tms_simulator).

Available options:
tms_simulator
source_id
string
required

Unique identifier of the record in the TMS. Note: we generate a deterministic composite key based on available fields if the TMS does not provide a unique ID.

source_data_hash
string
required

SHA-256 hash of the source data payload. Note: we use it internally for idempotence and deduplication.

Maximum string length: 64
tms_account_id
string<uuid> | null

The TMS account that owns this record's tms_connection_id.

deleted_at
string<date-time> | null

The datetime the record was logically deleted from Catena Telematics.

tms_id
string<uuid> | null

Unique identifier of the TMS at Catena Telematics from which this record was ingested.

tms_slug
string | null

Human readable slug of the TMS at Catena Telematics from which this record was ingested.

source_data
Source Data · object

Raw source payload as ingested from the TMS. Note: use it for audit/debugging.

occurred_at
string<date-time> | null

Datetime of when the underlying event/observation occurred, as reported by the TMS, or the moment it was ingested by us if not available in the source data.

extras
Extras · object | null

Additional data available in the TMS that doesn't fit into the model (this field captures those extra attributes in a flexible way).

execution_id
string<uuid> | null

Unique identifier for the execution that ingested this record into Catena Telematics. Note: useful for tracing. Stamped by upsert_data() onto every record regardless of resource domain (functions/upsert/src/upsert.py), so this is populated the same way it is for TSP tables even though there is no TMS Schedule/Execution pipeline yet.

schedule_id
string<uuid> | null

Unique identifier for schedule that triggered this record's execution. Note: useful for tracing.

load_number
string | null

Load/shipment number as provided by the TMS.

status
string | null

TMS-provided load status (e.g., 'booked', 'in_transit', 'delivered'). Not normalized across TMS providers.

source_customer_id
string | null

External source system customer identifier (from the TMS).

customer_id
string<uuid> | null

Internal customer identifier (Catena), deterministically derived from source_customer_id. No foreign key: no standalone Customer resource table exists yet.

customer_name
string | null

Customer name as provided by the TMS.

source_carrier_id
string | null

External source system carrier identifier (from the TMS).

carrier_id
string<uuid> | null

Internal carrier identifier (Catena), deterministically derived from source_carrier_id. No foreign key: no standalone Carrier resource table exists yet.

carrier_name
string | null

Carrier name as provided by the TMS.

stops
Stops · object[]

Ordered pickup/delivery stops within the load (see LoadStop for the expected shape). Stored as JSON-safe dicts rather than list[LoadStop]: SQLAlchemy's JSONB column serializes with the stdlib json encoder, which can't handle Pydantic model instances or datetimes, so callers must pass stop.model_dump(mode='json') rather than a LoadStop instance (mirrors why functions/upsert/src/upsert.py's _normalize_jsonb_columns exists for the ingestion path).