Introduction
This page helps TMS developers, mobile app authors, and enterprise shippers integrate with Exspeedite CheckPoint. CheckPoint is the outside-carrier visibility layer: your systems send load data in; CheckPoint handles driver links, milestone check-ins, maps, notifications, and optional shipper feeds.
https://exspeeditecheckpoint.com
All paths below are relative to this host. Use HTTPS from trusted server-side code only — never embed bearer tokens in browser JavaScript.
What you can build
One POST per load to initialize tracking, driver SMS, and stop workflow.
Poll active shipments with HMAC-signed GET requests — no driver PII in the payload.
Token-authenticated POST endpoints for load context, milestone check-in, background GPS, and POD photos.
Per-company Samsara / Motive ELD keys in the CheckPoint admin UI — separate from the TMS bearer token. See Asset GPS.
Recommended reading order
- Skim the API reference — pick your integration path (TMS, shipper, or driver app).
- Complete the 5-minute quickstart with a test bearer token.
- Review Authentication, the JSON contract, and error codes.
- Download the full machine-readable integration package: Export Integration JSON (endpoints, auth, payload contract, errors, examples).
- Export this page as Markdown for your internal wiki: Download export.
API reference
Every public integration surface is listed here with HTTP method, path, and auth model. Click a card to jump to the full contract, samples, and error handling for that endpoint.
Initialize load
Create or refresh an active load, ordered stops, driver handoff (direct or private link), and optional continuous tracking mode.
/v1/tracking/initialize.php
Bearer token · TMS server only
Active shipments (shipper)
Enterprise shipper poll of in-flight shipments bound to the shipper UUID. HMAC-signed; privacy-safe fields only.
/v1/shipper/active-shipments.php
HMAC · X-Shipper-UUID + secret
Load info
Driver app bootstrap — stops, tracking mode, interval, and web check-in link for the load token.
/v1/tracking/load-info.php
Load token · 64-char hex
Background ping
Continuous GPS breadcrumb from the CheckPoint driver app between milestone check-ins.
/v1/tracking/background-ping.php
Load token · continuous mode only
Milestone ping
Driver web or app check-in at pickup, transit, or delivery — advances stops and records GPS at the milestone.
/v1/tracking/ping.php
Load token
POD upload
Delivery proof photo metadata and file upload when POD capture is enabled for the tenant.
/v1/tracking/pod-upload.php
Load token · delivery stop
Private driver assignment
Carrier-facing flow after private_link initialize — collects driver phone without exposing it to dispatch.
/v1/carrier/assign-driver.php
Assignment token · not bearer
5-minute quickstart
Generate a bearer token from the client workspace, then send a JSON payload to the initialize endpoint. The first stop receives the first driver tracking link.
Your TMS server reads the load, adds the bearer token, and posts JSON to CheckPoint.
Use direct-driver when you have a phone, or private-link when the carrier should enter it.
Normalize E.164 phone numbers, stop order, milestone type, and location identity.
Store the response, expose API errors in TMS logs, and subscribe to Integration Events when needed.
Create an API client in CheckPoint and copy the bearer token once.
Send load, driver, carrier, and ordered stop data to the initialize endpoint.
CheckPoint texts the driver immediately, or returns a private assignment link when the carrier should enter the driver phone.
- Server-side token storage and POST request.
- Payload validation and clear connector logs.
- A Send to CheckPoint action in the TMS load screen.
- Driver tracking links, GPS check-ins, and next-stop advancement.
- Private driver assignment email and token page.
- Dashboard visibility, notifications, and outbound Integration Events.
curl -X POST "https://exspeeditecheckpoint.com/v1/tracking/initialize.php" \
-H "Authorization: Bearer YOUR_CHECKPOINT_TOKEN" \
-H "Content-Type: application/json" \
--data '{
"load_number": "TMS-104482",
"carrier_name": "Blue River Transport",
"driver_name": "Maria Santos",
"driver_phone": "+13125550119",
"driver_email": "[email protected]",
"tms_vehicle_id": "TRUCK-1042",
"power_unit": "1042",
"reference_numbers": "BOL 88421, PO 77219",
"commodity_description": "Packaged retail goods",
"total_weight_lbs": 38250,
"pallet_count": 22,
"trailer_type": "53 dry van",
"user1": "Retail division 42",
"user2": "Customer PO 77219",
"required_paperwork": "Signed BOL and POD with signature/time/photo",
"notification_emails": [
"[email protected]",
"[email protected]"
],
"email_notifications": {
"load": true,
"pickup": true,
"stopoffs": true,
"checkpoints": false,
"delivered": true
},
"stops": [
{
"stop_sequence": 1,
"milestone_type": "pickup",
"location_name": "Exspeedite Chicago DC",
"address1": "1200 W Logistics Way",
"city": "Chicago",
"state": "IL",
"zip": "60632",
"scheduled_at": "2026-06-25T14:00:00Z",
"time_window_end": "2026-06-25T16:00:00Z",
"appointment_type": "appointment",
"load_unload_type": "live",
"facility_hours": "0800-1700",
"dock_instructions": "Check in at guard shack, use dock 12"
},
{
"stop_sequence": 2,
"milestone_type": "transit",
"location_name": "Memphis Crossdock",
"address1": "88 Riverport Rd",
"city": "Memphis",
"state": "TN",
"zip": "38118",
"scheduled_at": "2026-06-26T03:00:00Z"
},
{
"stop_sequence": 3,
"milestone_type": "delivery",
"location_name": "Dallas Retail Pool",
"address1": "4400 Distribution Dr",
"city": "Dallas",
"state": "TX",
"zip": "75241",
"scheduled_at": "2026-06-26T16:30:00Z"
}
]
}'
CSV import template
CSV Import is the dispatcher-facing spreadsheet path, separate from the bearer-token JSON API. Dispatchers open /exp_csv-load-import.php from CheckPoint, or use Add Load's Export CSV button to download checkpoint-load-template.csv.
One CSV row equals one stop. Rows with the same load_number are grouped into one load before the importer calls run_initialize(). Multiple pickups, deliveries, and intermediate stop-offs are allowed.
The template includes core load fields, notification flags, rich freight/paperwork fields, custom user1 through user10 fields, and stop fields such as time_window_end, facility_hours, dock_instructions, and driver_instructions.
milestone_type to pickup, transit, or delivery. Use transit for Stop / Stop-off rows such as dispatcher stop-offs, crossdocks, partial deliveries, and other intermediate stops. The value controls the row color in Add Load, map marker color, and driver check-in workflow.CheckPoint brand assets
Grab these customer-facing artifacts for TMS screens, slide decks, integration docs, and email mockups. Both live on this server — right-click or use the download link.
CheckPoint brand badge (PNG)
Same pill button styling as Send to CheckPoint, but with CheckPoint and Live Visibility only — for slide decks, PDFs, and partner docs.
Same accent glow, shield icon, pill shape, and typography as the TMS action button below — not a separate logo treatment.
/images/checkpoint-brand-badge.svg (vector, transparent background). Use SVG in docs or export to PNG from your design tool for pixel-perfect output.
Public developer asset — no auth required.
Send to CheckPoint button asset
This is the customer-facing artifact for Expedite-C and other TMS screens: one premium action button that launches the server-side connector call. The button should appear near the TMS load action area after the load has enough data to transmit.
Copy the button HTML, CSS, and click handler
<button class="checkpoint-send-button" type="button" onclick="sendLoadToCheckpoint(loadId)">
<span class="cp-icon" aria-hidden="true">
<svg viewBox="0 0 32 32" role="img">
<path d="M16 3.5 25.5 8.8v7.3c0 6-3.9 10.7-9.5 12.4-5.6-1.7-9.5-6.4-9.5-12.4V8.8L16 3.5Z" fill="none" stroke="var(--cp-accent)" stroke-width="2.2" stroke-linejoin="round"/>
<path d="M10.2 16.3h8.9" stroke="#f8fafc" stroke-width="2.2" stroke-linecap="round"/>
<path d="m16.2 11.5 5 4.8-5 4.8" fill="none" stroke="#38bdf8" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/>
<circle cx="16" cy="16" r="12.4" fill="none" stroke="rgba(56,189,248,.42)" stroke-width="1.1"/>
</svg>
</span>
<span class="cp-text">
<strong>Send to CheckPoint</strong>
<span>Live Visibility</span>
</span>
</button>
.checkpoint-send-button {
--cp-cyan: var(--cp-accent);
--cp-blue: #38bdf8;
--cp-white: #f8fafc;
position: relative;
isolation: isolate;
display: inline-flex;
align-items: center;
gap: 13px;
min-height: 58px;
padding: 9px 22px 9px 10px;
border: 1px solid color-mix(in srgb, var(--cp-accent) 55%, transparent);
border-radius: 999px;
color: var(--cp-white);
background:
linear-gradient(135deg, color-mix(in srgb, var(--cp-accent) 24%, transparent), rgba(219,17,31,.12) 46%, rgba(4, 6, 12, .92)),
linear-gradient(135deg, #065f46, #b50e19);
box-shadow:
0 16px 38px rgba(219,17,31, .34),
0 0 0 1px rgba(255,255,255,.08) inset,
0 0 32px color-mix(in srgb, var(--cp-accent) 22%, transparent);
font: 950 13px/1 "Segoe UI", Inter, system-ui, sans-serif;
letter-spacing: .105em;
text-decoration: none;
text-transform: uppercase;
cursor: pointer;
overflow: hidden;
transform: translateZ(0);
transition: transform .18s ease, box-shadow .18s ease, border-color .18s ease;
}
.checkpoint-send-button::before {
content: "";
position: absolute;
inset: 1px;
z-index: -1;
border-radius: inherit;
background:
linear-gradient(110deg, transparent 0 26%, rgba(255,255,255,.28) 38%, transparent 52%),
radial-gradient(circle at 18% 28%, rgba(255,255,255,.18), transparent 36%);
opacity: .68;
transform: translateX(-34%);
}
.checkpoint-send-button:hover {
transform: translateY(-2px);
border-color: rgba(167, 243, 208, .82);
box-shadow:
0 20px 48px rgba(219,17,31, .42),
0 0 0 1px rgba(255,255,255,.10) inset,
0 0 44px color-mix(in srgb, var(--cp-accent) 34%, transparent);
}
.cp-icon {
display: grid;
place-items: center;
width: 40px;
height: 40px;
flex: 0 0 40px;
border-radius: 50%;
background: radial-gradient(circle, color-mix(in srgb, var(--cp-accent) 18%, transparent), rgba(2,6,23,.82));
box-shadow: 0 0 0 1px color-mix(in srgb, var(--cp-accent) 38%, transparent), 0 0 22px color-mix(in srgb, var(--cp-accent) 28%, transparent);
}
.cp-icon svg {
width: 25px;
height: 25px;
filter: drop-shadow(0 0 8px color-mix(in srgb, var(--cp-accent) 55%, transparent));
}
.cp-text {
display: grid;
gap: 3px;
text-align: left;
}
.cp-text strong {
color: #fff5f5;
font-size: 13px;
white-space: nowrap;
}
.cp-text span {
color: #99f6e4;
font-size: 9px;
letter-spacing: .18em;
opacity: .86;
white-space: nowrap;
}
async function sendLoadToCheckpoint(loadId) {
const button = document.querySelector(".checkpoint-send-button");
button.disabled = true;
button.classList.add("is-sending");
try {
// Call your TMS backend, not CheckPoint directly from the browser.
// Your backend adds the CheckPoint bearer token and posts to initialize.php.
const response = await fetch(`/api/checkpoint/send-load/${encodeURIComponent(loadId)}`, {
method: "POST",
headers: { "Content-Type": "application/json" }
});
const result = await response.json();
if (!response.ok || !result.success) throw new Error(result.message || "CheckPoint send failed");
button.querySelector(".cp-text span").textContent = "Sent";
} catch (error) {
button.disabled = false;
button.classList.remove("is-sending");
alert(error.message);
}
}
Email look and feel
Private driver assignment emails are generated by CheckPoint, not the TMS. The TMS sends load data to the API; CheckPoint owns the carrier-facing email so the outside carrier sees the same futuristic CheckPoint identity as the button and tracking page.
Securely enter the driver once. CheckPoint will text the tracking link without exposing the phone number to dispatch.
Enter Driver PrivatelyThe raw token URL stays hidden behind this button in HTML email.
CheckPoint sends the private assignment email through SendGrid after the API receives driver_assignment_mode: "private_link".
HTML email uses an Enter Driver Privately button instead of showing the full token URL. Plain-text fallback still includes the full URL for compatibility.
CheckPoint disables SendGrid click tracking for these messages so links do not display as long ct.sendgrid.net redirect URLs.
Private Driver Assignment
Load: EXS-295911
Carrier: ROADSTAR CARRIER INC.
Enter the driver privately here:
https://exspeeditecheckpoint.com/carrier/assign.php?token=...
The driver's phone number is used only to send the secure CheckPoint tracking link and is not shown to the broker or dispatcher.
Authentication
Every request must include a bearer token assigned to the client workspace. Tokens are tenant-scoped; a token for one company cannot create or modify loads for another company.
| Header | Value | Notes |
|---|---|---|
Authorization | Bearer YOUR_CHECKPOINT_TOKEN | Required. Store securely server-side. |
Content-Type | application/json | Required for JSON payloads. |
Unified Shipper Visibility API V1
Enterprise shippers can poll active shipments with HMAC authentication. This API is shipment-centric only: it excludes delivered, cancelled, unassigned, disabled, and unbound loads and never returns driver phone/name, rates, broker fields, internal notes, or raw provider payloads.
GET /api/v1/shipper/active-shipments.phpGET /v1/shipper/active-shipments.php
Carrier admins use the public shipper UUID to tag loads. Shipper admins sign in at /shipper-login.php to rotate and manage the private API secret.
| Header | Required | Purpose |
|---|---|---|
X-Shipper-UUID | Yes | Global shipper UUID issued by CheckPoint. |
X-Timestamp | Yes | UTC timestamp. Requests older than five minutes are rejected. |
X-Signature | Yes | Hex HMAC-SHA256 of the canonical string. |
METHOD + "\n" +
PATH + "\n" +
CANONICAL_QUERY + "\n" +
X_TIMESTAMP + "\n" +
SHA256_HEX(BODY)
SHA256(secret), and verifies signatures using that derived value as the HMAC key. Store the one-time secret securely and derive the signing key in server-side code.<?php
$secret = getenv('CHECKPOINT_SHIPPER_SECRET');
$shipperUuid = getenv('CHECKPOINT_SHIPPER_UUID');
$path = '/api/v1/shipper/active-shipments.php';
$timestamp = gmdate('Y-m-d\TH:i:s\Z');
$body = '';
$canonical = "GET\n{$path}\n\n{$timestamp}\n" . hash('sha256', $body);
$signingKey = hash('sha256', $secret);
$signature = hash_hmac('sha256', $canonical, $signingKey);
$ch = curl_init('https://exspeeditecheckpoint.com' . $path);
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => [
'X-Shipper-UUID: ' . $shipperUuid,
'X-Timestamp: ' . $timestamp,
'X-Signature: ' . $signature,
],
CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
import datetime, hashlib, hmac, os, requests
secret = os.environ["CHECKPOINT_SHIPPER_SECRET"]
shipper_uuid = os.environ["CHECKPOINT_SHIPPER_UUID"]
path = "/api/v1/shipper/active-shipments.php"
timestamp = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
body = b""
canonical = f"GET\n{path}\n\n{timestamp}\n{hashlib.sha256(body).hexdigest()}"
signing_key = hashlib.sha256(secret.encode()).hexdigest().encode()
signature = hmac.new(signing_key, canonical.encode(), hashlib.sha256).hexdigest()
response = requests.get(
"https://exspeeditecheckpoint.com" + path,
headers={"X-Shipper-UUID": shipper_uuid, "X-Timestamp": timestamp, "X-Signature": signature},
timeout=20,
)
import crypto from "node:crypto";
const secret = process.env.CHECKPOINT_SHIPPER_SECRET;
const shipperUuid = process.env.CHECKPOINT_SHIPPER_UUID;
const path = "/api/v1/shipper/active-shipments.php";
const timestamp = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
const body = "";
const canonical = `GET\n${path}\n\n${timestamp}\n${crypto.createHash("sha256").update(body).digest("hex")}`;
const signingKey = crypto.createHash("sha256").update(secret).digest("hex");
const signature = crypto.createHmac("sha256", signingKey).update(canonical).digest("hex");
const response = await fetch(`https://exspeeditecheckpoint.com${path}`, {
headers: {
"X-Shipper-UUID": shipperUuid,
"X-Timestamp": timestamp,
"X-Signature": signature
}
});
Optional load binding fields
| Field | Type | Description |
|---|---|---|
global_shipper_uuid | string | Binds an active load to the global shipper API. |
shipper_reference | string | PO, BOL, order, or shipper shipment reference returned in the response. |
shipper_visibility_enabled | boolean | Per-load visibility kill switch. Defaults on when a global shipper UUID is provided. |
Shipper visibility response and HMAC errors
{
"shipper_uuid": "7d62d2c5-5e67-4e20-9e34-0a2c0f64d812",
"generated_at": "2026-06-29T05:00:00Z",
"shipments": [
{
"shipment_id": "EXP-10001",
"load_number": "EXP-10001",
"shipper_reference": "PO 4500099123",
"carrier_name": "Example Carrier LLC",
"status": "in_transit",
"origin": { "name": "Pickup DC", "city": "Anoka", "state": "MN", "scheduled_at": "2026-06-29T13:00:00Z" },
"destination": { "name": "Receiving", "city": "Dallas", "state": "TX", "scheduled_at": "2026-06-30T18:00:00Z" },
"current_location": { "lat": 41.8781, "lng": -87.6298, "timestamp": "2026-06-29T04:58:12Z", "freshness": "fresh", "source": "provider_gps" },
"eta": { "estimated_arrival_at": "2026-06-30T17:20:00Z", "confidence": "medium", "status": "unknown" }
}
],
"correlation_id": "shp_20260629050000_ab12cd34ef56"
}
| HTTP | Error code | Meaning |
|---|---|---|
401 | MISSING_HMAC_HEADERS | Missing shipper UUID, timestamp, or signature header. |
401 | INVALID_SHIPPER_UUID | The shipper UUID is not valid UUID format. |
401 | EXPIRED_HMAC_TIMESTAMP | The timestamp is outside the five-minute replay window. |
401 | SHIPPER_NOT_ACTIVE | The global shipper is disabled or not found. |
403 | INVALID_HMAC_SIGNATURE | The signature is not a 64-character lowercase hex HMAC. |
403 | HMAC_SIGNATURE_MISMATCH | The canonical string or signing key does not match CheckPoint. |
Asset GPS / ELD integrations (admin UI)
Asset-based carriers can attach fleet GPS / ELD provider credentials so CheckPoint can show tractor markers on the Live Map. This is separate from driver phone tracking (ping / continuous). TMS connectors still send tms_vehicle_id or power_unit on initialize so CheckPoint can match provider telemetry to active loads.
GPS Integrations — Settings → GPS Integrations. Requires Admin role (dispatchers cannot open this page).
Samsara — connection, vehicle sync, ELD refresh, auto/manual mapping.
Motive — same workflow: API key, sync, refresh, auto/manual mapping.
PeopleNet — planned; contact CheckPoint support.
Expedite TMS — Motive / Samsara GPS handoff — copy-paste spec for initialize fields, auth split, and admin setup. No ELD API keys in TMS code.
checkpoint_schema.html → GPS Provider Integrations — gps_provider_connections, gps_vehicle_mappings, gps_vehicle_telemetry, and per-company app_credentials rows (gps_samsara, gps_motive, gps_provider).
GPS Provider Framework — provider-agnostic design, vehicle mapping, polling, and future webhook automation.
Multi-tenant permissions (who sees what)
The GPS Integrations page stores credentials per company workspace. Wilson and Manning each get their own API key rows. The optional Multi-Tenant Overview table appears only when your login can access more than one company.
| Login type | Companies visible | Overview table | Secrets shown? |
|---|---|---|---|
| Client admin — one company | That company only (e.g. Wilson) | Hidden | Never — only “token saved” yes/no |
| Client admin — multiple assigned companies | Only companies checked in User Access | Those assigned companies only | Never |
Platform admin (is_platform_admin) | All companies in CheckPoint | All tenants | Never |
| Dispatcher | — | 403 — page blocked | — |
admin_user_company_access (see schema). Saving credentials requires a single-company workspace — not “All Companies”.Related admin pages
| Page | Purpose |
|---|---|
| /gps-integrations.php | Per-company Samsara / Motive API setup, vehicle mapping, ELD refresh. |
| /gps-live-map-setup.php | Guided wizard: connect provider → sync fleet → map color → live map. |
POST /v1/dashboard/refresh-provider-gps.php | Admin session — refreshes all verified Samsara and Motive connections for the selected workspace(s). |
| /user-access.php | Controls which companies a login can see in the workspace switcher and GPS overview. |
| /company-profile.php | TMS bearer tokens for initialize.php (separate from ELD provider keys). |
| /settings.php | Settings hub link to GPS Integrations. |
| /dashboard.php | Live Map — cyan diamond markers for mapped provider GPS when telemetry exists. |
TMS connector fields for provider GPS matching
When posting to initialize, include the tractor identifier your TMS uses so CheckPoint can match Samsara/Motive vehicles after admin mapping:
| Field | Purpose |
|---|---|
tms_vehicle_id | Primary TMS tractor / power-unit ID for provider vehicle mapping. |
power_unit | Secondary matching key when display name differs from TMS ID. |
tracking_mode as documented in Tracking modes.Expedite TMS Live Map launch (signed GET)
Expedite dispatchers can open CheckPoint Live Map in a new tab without pasting the initialize bearer token into the browser. Expedite signs a short-lived HMAC server-side; CheckPoint validates it and starts a dispatcher session scoped to the company workspace.
GET /v1/auth/tms-launch.php — returns 302 to /dashboard.php on success.
Company Profile → API client → Generate TMS Launch Secret. Separate from the initialize bearer token.
Expedite TMS Live Map launch spec — HMAC canonical string, replay window, audit log, Expedite office fields.
/dev/tms_launch_test_url.php — admin-only signed URL builder for QA (after secret is generated).
Query parameters
| Param | Required | Notes |
|---|---|---|
company_id | Yes | CheckPoint workspace ID (e.g. Small Town Trucking = 5). |
ts | Yes | Unix timestamp; must be within 120 seconds of server time. |
client | Yes | V1: expedite — must match tms_launch_client_key on the API client row. |
sig | Yes | Lowercase hex HMAC-SHA256 (64 chars). Key = SHA-256(raw_launch_secret). |
nonce | No | Optional replay guard; reused nonce within 10 minutes is rejected. |
source, user | No | Audit labels only (e.g. expedite_mobile_com, dispatcher username). |
redirect | No | Relative path only; default /dashboard.php. |
CHECKPOINT_LAUNCH_SECRET server-side and signs each link at click time.Expedite signing (PHP)
$base = 'https://exspeeditecheckpoint.com/v1/auth/tms-launch.php';
$companyId = 5;
$ts = time();
$client = 'expedite';
$nonce = bin2hex(random_bytes(8));
$canonical = "GET\n/v1/auth/tms-launch.php\n{$companyId}\n{$ts}\n{$client}\n{$nonce}";
$hmacKey = hash('sha256', $rawLaunchSecret);
$sig = hash_hmac('sha256', $canonical, $hmacKey);
$query = http_build_query([
'company_id' => $companyId,
'ts' => $ts,
'client' => $client,
'nonce' => $nonce,
'sig' => $sig,
'source' => 'expedite_mobile_com',
]);
$url = $base . '?' . $query;
EXSPEEDITE TMS adapter
EXSPEEDITE is the primary inbound TMS connector for CheckPoint. This section summarizes the initialize contract EXSPEEDITE should implement — full field reference is in JSON payload contract below.
ExpediteCallbackService::eventCatalog() in the repo.| Topic | EXSPEEDITE behavior |
|---|---|
| Required at initialize | load_number, carrier_name, stops (ordered array). At least one stop must have milestone_type: "delivery". For direct_driver: driver_name + driver_phone. For private_link: carrier_contact_email. |
| Recommended optional | tms_vehicle_id / power_unit (provider GPS match), tracking_mode, reference_numbers, shipper_reference, global_shipper_uuid, rich freight fields, correlation_id (echoed on every response). |
| Success response | Always includes correlation_id and tracking_session_id (trk_…). First init → status: "initialized". Repeat POST for same active load_number → status: "reinitialized" (equipment/stop refresh; same session id and customer links). |
| Validation errors | HTTP 400 with error_code, message, correlation_id, and field-level errors[]. Example: missing delivery stop → MISSING_DELIVERY_STOP. No partial load is created on hard validation failure. |
| Tractor / equipment change | Re-send initialize with updated tms_vehicle_id or power_unit while load is active. CheckPoint updates the snapshot, re-upserts stops, re-runs Samsara auto-map, and returns the existing tracking_url / assignment_url when tokens already exist. |
JSON payload contract
The initialize request represents one active load. All required values should be sent as strings except stop_sequence, which should be a number.
Top-level load fields
| Field | Type | Required | Description |
|---|---|---|---|
load_number | string | Required | Your TMS load, shipment, or pro number. Must be unique while active for this tenant. |
carrier_name | string | Required | Carrier or vendor name shown to dispatchers. |
driver_assignment_mode | string | Optional | Use direct_driver when you have the driver phone. Use private_link when the carrier or driver should enter the phone privately. |
tracking_mode | string | Optional | ping (default) — Milestone SMS / web check-in only; no driver app required. continuous — Live GPS Trail add-on; driver may use the CheckPoint Android app for background GPS between stops. Milestone SMS still works on the same load. |
background_ping_interval_seconds | integer | Optional | Only when tracking_mode is continuous. Seconds between GPS breadcrumbs (10–900). Omit to use tenant default (usually 60). |
carrier_contact_email | string | Conditional | Required for private_link. CheckPoint emails this recipient the private driver assignment link. |
driver_name | string | Conditional | Required for direct_driver. Optional for private_link because the private page collects it. |
driver_phone | string | Conditional | Required for direct_driver. E.164 format, for example +13125550119. Normalize formatted TMS values such as (312) 555-0119, 312-555-0119, or 3125550119 before sending. Do not send this field for private driver assignment. |
driver_email | string | Optional | Driver email for reference only. SMS failure does not trigger an automatic email. |
tms_vehicle_id / power_unit | string | Optional | TMS tractor, vehicle, or power-unit identifier used to match a mapped Samsara or Motive vehicle for provider GPS live-map visibility. Driver phone tracking remains unchanged. Provider-agnostic — same fields for every ELD. |
reference_numbers | string or array | Optional | Extra load identifiers such as BOL, PO, shipment, order, or customer reference numbers. |
commodity_description | string | Optional | Plain-English freight description. Use special_properties for hazmat, reefer, fragile, odor-sensitive, or stackability details. |
total_weight_lbs | number | Optional | Total freight weight in pounds. |
piece_count / pallet_count | integer | Optional | Piece, pallet, or skid quantities. Use freight_dimensions for dimensions or cube. |
freight_class / nmfc_number | string | Optional | LTL freight class and NMFC when relevant. |
trailer_type / equipment_specs | string | Optional | Dry van, reefer, flatbed, length, air-ride, liftgate, or other equipment requirements. |
driver_assist / securement_requirements / onboard_tools | string | Optional | Driver assist, tarping, chains/straps, pallet jack, PPE, or other handling requirements. |
detention_layover_terms / tracking_expectations / routing_hos_notes | string | Optional | Operational context such as free time, ping/photo expectations, routing, HOS, or team-driver needs. |
required_paperwork / special_instructions | string | Optional | Signed BOL, POD, seals, weight tickets, no-stacking rules, security protocols, damage reporting, or site rules. |
broker_name / broker_contact | string | Optional | Dispatcher/internal broker context for load questions. CheckPoint does not expose these fields to driver, public share, or customer-facing Integration Events payloads. |
user1 ... user10 | string | Optional | Tenant-configurable custom load fields for customer references, TMS lanes, divisions, project codes, or other non-sensitive business context. Display labels are managed in Company Profile; payload keys remain stable as user1 through user10. |
notification_emails | array or comma-separated string | Optional | Email recipients for requested notifications. Multiple recipients are allowed. |
email_notifications | object | Optional | Controls which email events are sent. If omitted or all false, no emails are sent. |
stops | array | Required | Ordered stop list. Multiple pickups, multiple deliveries, and intermediate stop-offs are allowed. |
Private driver assignment
Use driver_assignment_mode: "private_link" when the broker or dispatcher should not receive the driver's phone number. CheckPoint creates the load, returns assignment_url, and sends that link to carrier_contact_email. The carrier or driver enters the driver name and phone on a token-gated page. The dashboard only shows Phone on file or the masked last four digits.
{
"load_number": "TMS-104483",
"carrier_name": "Blue River Transport",
"driver_assignment_mode": "private_link",
"carrier_contact_email": "[email protected]",
"reference_numbers": "BOL 88422, PO 77220",
"commodity_description": "Retail pool distribution",
"stops": [
{
"stop_sequence": 1,
"milestone_type": "pickup",
"location_name": "Exspeedite Chicago DC",
"city": "Chicago",
"state": "IL",
"scheduled_at": "2026-06-25T14:00:00Z",
"dock_instructions": "Check in at guard shack"
},
{
"stop_sequence": 2,
"milestone_type": "transit",
"location_name": "Memphis Crossdock",
"city": "Memphis",
"state": "TN",
"driver_instructions": "Stop / Stop-off: unload 6 pallets and get dock receipt."
},
{
"stop_sequence": 3,
"milestone_type": "delivery",
"location_name": "Dallas Retail Pool",
"city": "Dallas",
"state": "TX"
}
]
}
Continuous background tracking (add-on)
Optional native-driver mode. Default remains tracking_mode: "ping" (web link check-in only). Continuous mode requires the tenant add-on enabled in CheckPoint Settings Hub.
| Field | Value | Notes |
|---|---|---|
tracking_mode | "continuous" | Per load. Omit or use ping for standard web workflow. |
background_ping_interval_seconds | 10–900 | Optional per-load override. Floor 10 seconds. Falls back to tenant default (usually 60). |
The initialize response is unchanged — you still receive tracking_url for milestone web check-in. For continuous loads, also send the driver the app deep link checkpoint://track?token={token_from_tracking_url} or distribute the native iOS/Android app.
{
"load_number": "TMS-104901",
"carrier_name": "Blue River Transport",
"driver_name": "Alex Driver",
"driver_phone": "+13125550119",
"tracking_mode": "continuous",
"background_ping_interval_seconds": 60,
"stops": [
{
"stop_sequence": 1,
"milestone_type": "pickup",
"location_name": "Chicago DC",
"city": "Chicago",
"state": "IL"
},
{
"stop_sequence": 2,
"milestone_type": "delivery",
"location_name": "Dallas Retail",
"city": "Dallas",
"state": "TX"
}
]
}
Email notification options
Email is opt-in only. CheckPoint sends zero emails unless notification_emails is populated and at least one option below is true.
| Field | Type | Meaning |
|---|---|---|
email_notifications.load | boolean | Email when the load is created in CheckPoint. |
email_notifications.pickup | boolean | Email when the driver checks in at pickup. |
email_notifications.stopoffs | boolean | Email when the driver checks in at transit/stop-off stops. |
email_notifications.checkpoints | boolean | Email for every driver checkpoint, regardless of milestone type. |
email_notifications.delivered | boolean | Email when the driver checks in at final delivery. |
Stop fields and validation notes
| Field | Type | Required | Description |
|---|---|---|---|
stop_sequence | integer | Required | 1-based order. Use 1, 2, 3 without gaps. |
milestone_type | string | Required | One of pickup, transit, or delivery. Use transit for Stop / Stop-off rows between pickups and deliveries. Do not send only a local field named type; CheckPoint validates milestone_type. |
location_name | string | Required | Facility, shipper, consignee, or stop name. If the TMS does not have a facility name, send a safe fallback such as Pickup Stop, Transit Stop, or Delivery Stop. |
address1 | string | Optional | Street address used for map stop context when provided. |
city | string | Required | Stop city. |
state | string | Required | Two-letter state or region abbreviation recommended. |
zip | string | Optional | Postal code. |
scheduled_at | string | Optional | ISO 8601 timestamp recommended, for example 2026-06-25T14:00:00Z. |
time_window_start / time_window_end | string | Optional | Exact appointment or receiving window. If start is omitted, CheckPoint uses scheduled_at as the window start. |
appointment_type | string | Optional | Appointment process such as appointment, fcfs, or call_for_appointment. |
load_unload_type | string | Optional | Live load/unload, drop trailer, preloaded, or similar stop handling context. |
facility_hours / appointment_process | string | Optional | Receiving hours, call-ahead, check-in, or appointment scheduling notes. |
dock_instructions / access_rules / stop_restrictions / driver_instructions | string | Optional | Dock, gate, access, PPE, parking, security, and site-specific instructions safe for the driver workflow. |
transit. CheckPoint supports multiple pickups and multiple deliveries when trucking operations need them.user1 through user10 are customer-safe optional load context and may appear in dashboard details and Integration Events. Do not store passwords, SSNs, payment data, or other regulated secrets in these fields.driver_phone is E.164 in direct-driver mode, every stop uses milestone_type instead of only type, and every stop has a non-empty location_name, city, and state. If a request fails, compare the exact outbound JSON your TMS logged against this contract.Tracking modes — plain English for TMS builders
Every load has a tracking_mode on the CheckPoint snapshot. Your TMS sets it once in the initialize POST — CheckPoint handles driver texts, app sync, map display, and auto-stop when the load closes.
ping (default)
Driver gets SMS links for PU, stop-off, and DEL. They tap in the phone browser — no app install. The live map shows milestone pins and straight connector lines. This is the standard outside-carrier workflow.
TMS sends: omit tracking_mode or "tracking_mode": "ping".
continuous (add-on)
Everything in Milestone SMS, plus optional CheckPoint Android app. Driver opens the app link once and taps Turn Tracking On; GPS breadcrumbs post between stops. Map shows teal trail / road-snapped path. Tenant must enable the add-on in Settings Hub.
TMS sends: "tracking_mode": "continuous" and optional background_ping_interval_seconds.
Initialize request fields (TMS connector)
| Field | Values | When to use |
|---|---|---|
tracking_mode | ping | continuous | Per load at dispatch. Default ping if omitted. |
background_ping_interval_seconds | 10–900 | Only for continuous. Optional override of tenant default (60s typical). |
Initialize response fields (store in TMS audit log)
| Field | Always? | Meaning |
|---|---|---|
tracking_mode | Yes | Echo of stored mode: ping or continuous. |
tracking_url | Direct driver | Milestone web check-in link (first stop). Same for both modes. |
driver_app_url | Continuous only | Deep link checkpoint://track?token=… for Android app sync. |
driver_app_sms_sent | Continuous only | true when CheckPoint texted the app sync link to the driver. |
sms_sent | Direct driver | First milestone SMS sent (both modes). |
tracking_mode at initialize; CheckPoint and the driver app handle the rest.{
"load_number": "EXS-104901",
"carrier_name": "Manning Transfer",
"driver_name": "John Driver",
"driver_phone": "+17634446474",
"tracking_mode": "ping",
"stops": [ /* … */ ]
}
{
"load_number": "EXS-104902",
"carrier_name": "Manning Transfer",
"driver_name": "John Driver",
"driver_phone": "+17634446474",
"tracking_mode": "continuous",
"background_ping_interval_seconds": 60,
"stops": [ /* … */ ]
}
{
"success": true,
"status": "initialized",
"load_number": "EXS-104902",
"tracking_mode": "continuous",
"tracking_url": "https://exspeeditecheckpoint.com/tracking/start.php?token=...",
"driver_app_url": "checkpoint://track?token=...",
"driver_app_sms_sent": true,
"sms_sent": true,
"driver_assignment_status": "assigned"
}
Tracking mode errors
| HTTP | error_code | Meaning | Fix |
|---|---|---|---|
400 | CONTINUOUS_TRACKING_DISABLED | Tenant Live GPS add-on is off but request sent continuous. | Enable add-on in CheckPoint Settings Hub, or send ping. |
400 | INVALID_BACKGROUND_INTERVAL | background_ping_interval_seconds below 10 or not an integer. | Send 10–900 or omit the field. |
Continuous GPS add-on (driver app APIs)
When a tenant enables Continuous Background GPS, drivers on tracking_mode: continuous loads may use the CheckPoint native app to send GPS between milestone check-ins. Web check-in via ping.php is unchanged on the same load.
tracking_mode and optional background_ping_interval_seconds. Background pings are posted by the driver app, not your TMS server.Prerequisites
- Tenant add-on enabled: Settings Hub → Continuous Background GPS.
- Load dispatched with
tracking_mode: "continuous". - Active 64-character hex token from initialize response or dashboard.
Driver endpoints (token auth, no bearer)
| Endpoint | Method | Purpose |
|---|---|---|
/v1/tracking/load-info.php | POST JSON | Load context, stops, and tracking block (interval, flags, tracking_stopped, links.web_checkin). |
/v1/tracking/background-ping.php | POST JSON | Record background GPS in track_background_pings. Returns ping_id and resolved interval. |
/v1/tracking/ping.php | POST JSON | Same milestone web check-in as ping-mode loads (optional on continuous loads for POD/milestones). |
POST https://exspeeditecheckpoint.com/v1/tracking/load-info.php
Content-Type: application/json
{ "token": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" }
// Excerpt of success response:
{
"success": true,
"carrier_name": "Blue River Transport",
"tracking": {
"tracking_mode": "continuous",
"background_ping_interval_seconds": 60,
"adaptive_interval_enabled": false,
"battery_efficiency_mode": false,
"continuous_tracking_addon_enabled": true,
"background_tracking_active": true,
"tracking_stopped": false
},
"links": {
"web_checkin": "/tracking/start.php?token=..."
}
}
POST https://exspeeditecheckpoint.com/v1/tracking/background-ping.php
Content-Type: application/json
{
"token": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"lat": 41.8781,
"lng": -87.6298,
"accuracy": 12.5,
"speed": 45.2,
"heading": 180,
"battery_pct": 78,
"recorded_at": "2026-06-30T18:00:00Z"
}
Background ping responses
| HTTP | Meaning |
|---|---|
200 | Ping stored. Body includes ping_id and background_ping_interval_seconds for client timer. |
401 | Invalid or expired token. |
403 | Tenant add-off disabled, or load is ping mode. |
409 | Load completed or canceled — app should stop tracking. |
Visibility for dispatchers and customers
Background pings feed the Live Map pin, Trail/History (teal dots), Share Tracking, and Visibility Health stale logic (~15 minutes without pings). Milestone check-ins remain blue dots on the same trail.
Auto-stop
Continuous tracking stops when the load is completed (ping.php final stop), canceled, or closed from the dashboard. load-info.php then returns tracking_stopped: true so the app can stop GPS and notify the driver.
Deep link for driver onboarding
checkpoint://track?token={64_hex} — used by iOS and Android scaffolds under mobile/. Extract the token from the standard tracking_url query string.
Copy-paste code samples
These examples all send the same payload. Replace the bearer token and load details with values from your TMS.
{
"load_number": "TMS-104482",
"carrier_name": "Blue River Transport",
"driver_name": "Maria Santos",
"driver_phone": "+13125550119",
"driver_email": "[email protected]",
"reference_numbers": "BOL 88421, PO 77219",
"commodity_description": "Packaged retail goods",
"total_weight_lbs": 38250,
"pallet_count": 22,
"freight_dimensions": "22 standard pallets, non-stackable",
"trailer_type": "53 dry van",
"equipment_specs": "Swing doors, food-grade trailer",
"driver_assist": "Driver count required at delivery",
"user1": "Retail division 42",
"user2": "Customer PO 77219",
"user3": "TMS lane CHI-DAL",
"required_paperwork": "Signed BOL and POD with signature/time/photo",
"special_instructions": "No stacking. Report damage before departure.",
"broker_name": "Northstar Brokerage",
"broker_contact": "[email protected], 312-555-0199",
"notification_emails": [
"[email protected]",
"[email protected]"
],
"email_notifications": {
"load": true,
"pickup": true,
"stopoffs": true,
"checkpoints": false,
"delivered": true
},
"stops": [
{
"stop_sequence": 1,
"milestone_type": "pickup",
"location_name": "Exspeedite Chicago DC",
"address1": "1200 W Logistics Way",
"city": "Chicago",
"state": "IL",
"zip": "60632",
"scheduled_at": "2026-06-25T14:00:00Z",
"time_window_end": "2026-06-25T16:00:00Z",
"appointment_type": "appointment",
"load_unload_type": "live",
"facility_hours": "0800-1700",
"dock_instructions": "Check in at guard shack, use dock 12",
"driver_instructions": "Bring signed BOL to shipping office before departure."
},
{
"stop_sequence": 2,
"milestone_type": "transit",
"location_name": "Memphis Crossdock",
"address1": "88 Riverport Rd",
"city": "Memphis",
"state": "TN",
"zip": "38118",
"scheduled_at": "2026-06-26T03:00:00Z"
},
{
"stop_sequence": 3,
"milestone_type": "delivery",
"location_name": "Dallas Retail Pool",
"address1": "4400 Distribution Dr",
"city": "Dallas",
"state": "TX",
"zip": "75241",
"scheduled_at": "2026-06-26T16:30:00Z"
}
]
}
const endpoint = "https://exspeeditecheckpoint.com/v1/tracking/initialize.php";
const token = process.env.CHECKPOINT_BEARER_TOKEN;
const payload = {
load_number: "TMS-104482",
carrier_name: "Blue River Transport",
driver_name: "Maria Santos",
driver_phone: "+13125550119",
driver_email: "[email protected]",
notification_emails: ["[email protected]", "[email protected]"],
email_notifications: {
load: true,
pickup: true,
stopoffs: true,
checkpoints: false,
delivered: true
},
stops: [
{
stop_sequence: 1,
milestone_type: "pickup",
location_name: "Exspeedite Chicago DC",
address1: "1200 W Logistics Way",
city: "Chicago",
state: "IL",
zip: "60632",
scheduled_at: "2026-06-25T14:00:00Z"
},
{
stop_sequence: 2,
milestone_type: "transit",
location_name: "Memphis Crossdock",
address1: "88 Riverport Rd",
city: "Memphis",
state: "TN",
zip: "38118",
scheduled_at: "2026-06-26T03:00:00Z"
},
{
stop_sequence: 3,
milestone_type: "delivery",
location_name: "Dallas Retail Pool",
address1: "4400 Distribution Dr",
city: "Dallas",
state: "TX",
zip: "75241",
scheduled_at: "2026-06-26T16:30:00Z"
}
]
};
const response = await fetch(endpoint, {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify(payload)
});
const result = await response.json();
if (!response.ok || !result.success) {
throw new Error(`${result.error_code || response.status}: ${result.message}`);
}
console.log("CheckPoint tracking URL:", result.tracking_url);
<?php
$endpoint = 'https://exspeeditecheckpoint.com/v1/tracking/initialize.php';
$token = getenv('CHECKPOINT_BEARER_TOKEN');
$payload = [
'load_number' => 'TMS-104482',
'carrier_name' => 'Blue River Transport',
'driver_name' => 'Maria Santos',
'driver_phone' => '+13125550119',
'driver_email' => '[email protected]',
'notification_emails' => ['[email protected]', '[email protected]'],
'email_notifications' => [
'load' => true,
'pickup' => true,
'stopoffs' => true,
'checkpoints' => false,
'delivered' => true,
],
'stops' => [
[
'stop_sequence' => 1,
'milestone_type' => 'pickup',
'location_name' => 'Exspeedite Chicago DC',
'address1' => '1200 W Logistics Way',
'city' => 'Chicago',
'state' => 'IL',
'zip' => '60632',
'scheduled_at' => '2026-06-25T14:00:00Z',
],
[
'stop_sequence' => 2,
'milestone_type' => 'transit',
'location_name' => 'Memphis Crossdock',
'address1' => '88 Riverport Rd',
'city' => 'Memphis',
'state' => 'TN',
'zip' => '38118',
'scheduled_at' => '2026-06-26T03:00:00Z',
],
[
'stop_sequence' => 3,
'milestone_type' => 'delivery',
'location_name' => 'Dallas Retail Pool',
'address1' => '4400 Distribution Dr',
'city' => 'Dallas',
'state' => 'TX',
'zip' => '75241',
'scheduled_at' => '2026-06-26T16:30:00Z',
],
],
];
$ch = curl_init($endpoint);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $token,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 20,
]);
$body = curl_exec($ch);
$httpCode = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$result = json_decode((string) $body, true);
if ($httpCode < 200 || $httpCode >= 300 || empty($result['success'])) {
throw new RuntimeException(($result['error_code'] ?? $httpCode) . ': ' . ($result['message'] ?? 'Unknown error'));
}
echo $result['tracking_url'] . PHP_EOL;
import os
import requests
endpoint = "https://exspeeditecheckpoint.com/v1/tracking/initialize.php"
token = os.environ["CHECKPOINT_BEARER_TOKEN"]
payload = {
"load_number": "TMS-104482",
"carrier_name": "Blue River Transport",
"driver_name": "Maria Santos",
"driver_phone": "+13125550119",
"driver_email": "[email protected]",
"notification_emails": ["[email protected]", "[email protected]"],
"email_notifications": {
"load": True,
"pickup": True,
"stopoffs": True,
"checkpoints": False,
"delivered": True,
},
"stops": [
{
"stop_sequence": 1,
"milestone_type": "pickup",
"location_name": "Exspeedite Chicago DC",
"address1": "1200 W Logistics Way",
"city": "Chicago",
"state": "IL",
"zip": "60632",
"scheduled_at": "2026-06-25T14:00:00Z",
},
{
"stop_sequence": 2,
"milestone_type": "transit",
"location_name": "Memphis Crossdock",
"address1": "88 Riverport Rd",
"city": "Memphis",
"state": "TN",
"zip": "38118",
"scheduled_at": "2026-06-26T03:00:00Z",
},
{
"stop_sequence": 3,
"milestone_type": "delivery",
"location_name": "Dallas Retail Pool",
"address1": "4400 Distribution Dr",
"city": "Dallas",
"state": "TX",
"zip": "75241",
"scheduled_at": "2026-06-26T16:30:00Z",
},
],
}
response = requests.post(
endpoint,
headers={
"Authorization": f"Bearer {token}",
"Content-Type": "application/json",
},
json=payload,
timeout=20,
)
result = response.json()
if not response.ok or not result.get("success"):
raise RuntimeError(f"{result.get('error_code', response.status_code)}: {result.get('message')}")
print("CheckPoint tracking URL:", result["tracking_url"])
Responses and errors
Success response
{
"success": true,
"status": "initialized",
"load_number": "TMS-104482",
"tracking_mode": "ping",
"tracking_url": "https://exspeeditecheckpoint.com/tracking/start.php?token=...&milestone=pickup&stop=1",
"sms_sent": true,
"email_sent": false,
"driver_assignment_status": "assigned"
}
{
"success": true,
"status": "initialized",
"load_number": "TMS-104483",
"assignment_url": "https://exspeeditecheckpoint.com/carrier/assign.php?token=...",
"sms_sent": false,
"email_sent": false,
"driver_assignment_status": "pending_assignment"
}
Error response shape
{
"success": false,
"error_code": "INVALID_STOP_MILESTONE_TYPE",
"message": "Stop 2 milestone_type must be pickup, transit, or delivery.",
"details": {
"stop_sequence": 2,
"field": "milestone_type",
"allowed": ["pickup", "transit", "delivery"]
}
}
Validation errors include a stable error_code, a human-readable message, and details when the connector can use structured fields to fix the payload.
HTTP status and error dictionary
| HTTP | Error code | Meaning | Recommended action |
|---|---|---|---|
200 | none | Load accepted and initialized. | Store the response for audit. Direct-driver mode attempts SMS immediately; private-link mode returns assignment_url. |
400 | MISSING_MANDATORY_FIELDS | One or more required top-level fields are missing. details.missing_fields lists the exact fields, such as load_number, carrier_name, stops, driver_name, or driver_phone. | Populate every listed field before retrying. For private_link, driver name and phone are not required at initialize time. |
400 | INVALID_DRIVER_ASSIGNMENT_MODE | driver_assignment_mode is not direct_driver or private_link. | Send direct_driver when the TMS has a driver phone, or private_link when the carrier should enter the driver privately. |
400 | INVALID_DRIVER_PHONE | Direct-driver mode requires driver_phone in E.164 format. | Normalize formatted values before posting. Example: (312) 555-0119 or 3125550119 must be sent as +13125550119. The response only exposes details.phone_last4, never the full phone. |
400 | INVALID_STOPS_PAYLOAD | stops is not an array or is empty. | Send a JSON array with at least one stop object. The connector should log the exact outbound JSON so developers can confirm stops is not serialized as a string or object. |
400 | INVALID_STOP_SEQUENCE | A stop has a missing or invalid stop_sequence. | Use 1-based stop numbers such as 1, 2, 3. The response includes the stop position and details.minimum. |
400 | INVALID_STOP_MILESTONE_TYPE | A stop is missing milestone_type or sent a value other than pickup, transit, or delivery. | Map TMS stop-off rows to transit. Do not send only a local field named type; CheckPoint validates milestone_type. |
400 | MISSING_STOP_LOCATION_NAME | A stop has a blank location_name. | Send the facility, shipper, consignee, or a safe fallback such as Pickup Stop, Transit Stop, or Delivery Stop. |
400 | MISSING_STOP_CITY_STATE | A stop is missing city, state, or both. details.missing_fields lists the exact field names. | Populate city and state for every stop. Street address and ZIP are optional, but city/state are required for the workflow and map context. |
401 | INVALID_BEARER_TOKEN | Bearer token missing, inactive, or invalid. | Verify the token generated for the client workspace. |
400 | CONTINUOUS_TRACKING_DISABLED | tracking_mode: continuous requested but tenant Live GPS add-on is disabled. | Enable Continuous Background GPS in Settings Hub, or default to ping. |
400 | INVALID_BACKGROUND_INTERVAL | background_ping_interval_seconds is missing, non-numeric, or below minimum (10). | Omit the field or send an integer from 10 through 900. |
200 | reinitialized | Same active load_number received again — equipment/stops refreshed; tracking_session_id unchanged; existing driver/assignment links preserved. | Use returned tracking_url or assignment_url; do not create a new load in EXSPEEDITE. |
500 | SERVER_ERROR | Unexpected server failure. | Retry later and contact support with the load number and timestamp. |
400 responses as non-retryable until the outbound JSON is changed. Display error_code, message, and details in TMS logs so dispatch and developers can see whether the issue is E.164 phone formatting, an empty stops array, or a bad milestone_type.Integration Events and webhooks
Integration Events send customer-facing 214-Style Visibility updates by email, secure JSON webhook, or both. They are transportation-style status notifications for outside systems and special customer mailboxes; they are not formal EDI 214 and they are separate from normal load email checkmarks.
Subscriptions can be company-wide or load-specific and can listen for dispatched, picked up, arrived at stop, delivered, POD submitted, ETA updated, geofence arrival, exception, or general status events.
JSON includes load number, carrier, reference numbers, commodity, custom fields with configured labels, required paperwork, special instructions, ordered stops, Stop / Stop-off details, ETA, POD status, latest driver location, share link when available, and sanitized event context.
broker_name and broker_contact are dispatcher/internal context only. They are intentionally excluded from driver pages, public share payloads, and customer-facing Integration Events unless a future dispatcher-only output is explicitly added.{
"output_type": "214_style_visibility",
"message_type": "transportation_style_status_update",
"event_type": "arrived_stop",
"load_number": "TMS-104482",
"status": {
"code": "X1",
"label": "Arrived at stop",
"description": "Driver arrived at Stop / Stop-off",
"timestamp_utc": "2026-06-26T03:05:00+00:00"
},
"load": {
"load_number": "TMS-104482",
"carrier_name": "Blue River Transport",
"reference_numbers": "BOL 88421, PO 77219",
"commodity_description": "Packaged retail goods",
"required_paperwork": "Signed BOL and POD with signature/time/photo",
"custom_fields": [
{ "key": "user1", "label": "Division", "value": "Retail division 42" },
{ "key": "user2", "label": "Customer PO", "value": "Customer PO 77219" }
],
"origin": { "stop_sequence": 1, "milestone_type": "pickup", "city": "Chicago", "state": "IL" },
"destination": { "stop_sequence": 3, "milestone_type": "delivery", "city": "Dallas", "state": "TX" },
"stops": [
{ "stop_sequence": 1, "milestone_type": "pickup", "location_name": "Exspeedite Chicago DC", "scheduled_at": "2026-06-25T14:00:00+00:00" },
{ "stop_sequence": 2, "milestone_type": "transit", "location_name": "Memphis Crossdock", "driver_instructions": "Stop / Stop-off: unload 6 pallets and get dock receipt.", "pod_submitted": false },
{ "stop_sequence": 3, "milestone_type": "delivery", "location_name": "Dallas Retail Pool", "eta_at": "2026-06-26T16:30:00+00:00", "pod_submitted": false }
],
"eta_at": "2026-06-26T16:30:00+00:00",
"share_url": "https://exspeeditecheckpoint.com/share.php?token=..."
},
"current_location": {
"lat": 35.1495,
"lng": -90.0490,
"milestone_type": "transit",
"stop_sequence": 2,
"timestamp_utc": "2026-06-26T03:05:00+00:00"
},
"context": {
"source": "checkpoint"
}
}
What CheckPoint does after receipt
The connector does not need to build driver pages or manage driver GPS. Once the load is initialized, CheckPoint controls the driver workflow.
tracking_mode defaults to ping.Testing checklist
Use this checklist before moving a connector from sandbox testing to production traffic.
assignment_url opens the private assignment page and SMS is only sent after assignment.tracking_mode: "continuous", and verify background pings appear on Trail/History (teal dots).load-info.php returns tracking.background_tracking_active: true and background-ping.php returns HTTP 200 for a valid token.Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
401 INVALID_BEARER_TOKEN | The token is missing, copied incorrectly, inactive, or belongs to another workspace. | Generate a new API client token and use the full value after Bearer. |
400 MISSING_MANDATORY_FIELDS | A required top-level field is blank. The response includes details.missing_fields. | Validate the exact JSON payload before sending. For direct-driver mode, include driver_name and driver_phone. For private-link mode, set driver_assignment_mode to private_link. |
400 INVALID_DRIVER_PHONE | The connector sent a formatted phone number such as (312) 555-0119, 312-555-0119, or 3125550119. | Normalize to E.164 before validation and before posting JSON. Example: (312) 555-0119 becomes +13125550119. |
400 INVALID_STOPS_PAYLOAD | stops was omitted, empty, or not encoded as a JSON array. | Send stops as an array of stop objects. Review the raw outbound request body from the TMS connector. |
400 INVALID_STOP_MILESTONE_TYPE | A stop is missing milestone_type, has an invalid milestone value, or the TMS sent only type. | Send milestone_type as pickup, transit, or delivery. Use transit for Stop / Stop-off rows. |
400 INVALID_STOP_SEQUENCE | A stop sequence is missing, zero, negative, or not numeric. | Send 1-based stop numbers in order. Start with 1. |
400 MISSING_STOP_LOCATION_NAME or MISSING_STOP_CITY_STATE | A stop does not have enough location identity for CheckPoint to create the workflow. | Send non-empty location_name, city, and state for every stop. |
| Private assignment link not returned | driver_assignment_mode was not set to private_link, or the endpoint rejected the payload. | Confirm the response is HTTP 200 and the payload includes driver_assignment_mode and carrier_contact_email. |
200 reinitialized | Active load updated in place (tractor swap, stop refresh). | Keep the same CheckPoint session; update TMS display from response fields only. |
400 MISSING_DELIVERY_STOP | No stop with milestone_type: "delivery". | Add a delivery stop before retrying. |
| Driver did not receive SMS | Carrier phone is invalid or Twilio delivery failed. | Check the response flags and message audit logs with support. Email is opt-in only and does not replace failed SMS automatically. |
| Dashboard has no truck marker yet | The driver has not accepted or checked in with GPS. | Ask the driver to open the link and tap the current milestone action. For continuous loads, confirm the driver app is tracking and posting to background-ping.php. |
403 on background ping | Tenant continuous add-off is disabled, or the load is still ping mode. | Enable the add-on in Settings Hub and confirm tracking_mode: "continuous" on the load snapshot. |
| Continuous trail empty but milestones show | Driver app not installed, permissions denied, or background pings failing. | Verify token, app deep link, and Always/background location permission on the device. |
Security notes
Always call the production endpoint over HTTPS from trusted server-side code.
Store tokens in environment variables or a secrets manager. Do not embed them in browser JavaScript.
Retry network failures, but do not blindly retry 409 or invalid payload errors.
Use the same load number your operations team recognizes in the TMS.