CP CheckPointDeveloper Connector Docs
TMS Connector API

Send load JSON into CheckPoint in minutes.

Use one secure API call to create a live outside-carrier tracking workflow. CheckPoint stores the load, sends the driver a tokenized tracking link, records each milestone check-in, advances the next stop automatically, and updates the dispatcher dashboard.

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.

Production base URL 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

TMS inbound connector

One POST per load to initialize tracking, driver SMS, and stop workflow.

Shipper visibility feed

Poll active shipments with HMAC-signed GET requests — no driver PII in the payload.

Driver mobile app

Token-authenticated POST endpoints for load context, milestone check-in, background GPS, and POD photos.

Asset GPS (admin)

Per-company Samsara / Motive ELD keys in the CheckPoint admin UI — separate from the TMS bearer token. See Asset GPS.

Recommended reading order

  1. Skim the API reference — pick your integration path (TMS, shipper, or driver app).
  2. Complete the 5-minute quickstart with a test bearer token.
  3. Review Authentication, the JSON contract, and error codes.
  4. Download the full machine-readable integration package: Export Integration JSON (endpoints, auth, payload contract, errors, examples).
  5. 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.

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.

1Build the backend call

Your TMS server reads the load, adds the bearer token, and posts JSON to CheckPoint.

2Choose driver handoff

Use direct-driver when you have a phone, or private-link when the carrier should enter it.

3Validate before send

Normalize E.164 phone numbers, stop order, milestone type, and location identity.

4Operate from events

Store the response, expose API errors in TMS logs, and subscribe to Integration Events when needed.

1. Get token

Create an API client in CheckPoint and copy the bearer token once.

2. POST JSON

Send load, driver, carrier, and ordered stop data to the initialize endpoint.

3. Track load

CheckPoint texts the driver immediately, or returns a private assignment link when the carrier should enter the driver phone.

Your TMS should build
  • Server-side token storage and POST request.
  • Payload validation and clear connector logs.
  • A Send to CheckPoint action in the TMS load screen.
CheckPoint owns after receipt
  • Driver tracking links, GPS check-ins, and next-stop advancement.
  • Private driver assignment email and token page.
  • Dashboard visibility, notifications, and outbound Integration Events.
Minimal cURL request
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.

Row model

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.

Column scope

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.

Stop type values: set 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.
Developer note: use JSON for server-to-server TMS connectors. Use CSV when an operations user needs a spreadsheet import/export workflow in the CheckPoint web app.

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.

Matches Send button

Same accent glow, shield icon, pill shape, and typography as the TMS action button below — not a separate logo treatment.

Files

/images/checkpoint-brand-badge.svg (vector, transparent background). Use SVG in docs or export to PNG from your design tool for pixel-perfect output.

Grab it

Public developer asset — no auth required.

Download SVG
Direct URL:https://exspeeditecheckpoint.com/images/checkpoint-brand-badge.svg

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.

Icon concept

A shield-checkpoint mark with a forward arrow: security, handoff, and live dispatch motion in one symbol.

Color system

Dual theme: futuristic uses Manning red #db111f on portal black #06080f; exspeedite uses sage green #4d8e31. Accent is CSS var(--cp-accent). Electric blue #38bdf8 remains secondary on dark theme.

Interaction

Rounded pill, glowing circular icon, hover lift, and light sweep. Use this as the single visible CheckPoint brand object inside the TMS.

Copy the button HTML, CSS, and click handler
Button HTML
<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>
Button CSS
.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;
}
Button click handler pattern
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);
  }
}
Important: the TMS button should call your Expedite-C backend. Do not put the CheckPoint bearer token in the browser or desktop UI. The backend should make the authenticated POST to CheckPoint.

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.

Plain-text fallback shape
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.
Design rule: every CheckPoint-owned email should use the same deep navy background, cyan/blue glow, rounded glass panels, clear load/carrier cards, and one primary CTA button. Avoid exposed long URLs in HTML whenever a button can carry the link.

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.

HeaderValueNotes
AuthorizationBearer YOUR_CHECKPOINT_TOKENRequired. Store securely server-side.
Content-Typeapplication/jsonRequired for JSON payloads.
Do not send this from a browser. Keep the bearer token inside server-side connector code, middleware, or an integration service.

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.

Endpoint

GET /api/v1/shipper/active-shipments.php
GET /v1/shipper/active-shipments.php

Credential ownership

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.

HeaderRequiredPurpose
X-Shipper-UUIDYesGlobal shipper UUID issued by CheckPoint.
X-TimestampYesUTC timestamp. Requests older than five minutes are rejected.
X-SignatureYesHex HMAC-SHA256 of the canonical string.
Canonical string
METHOD + "\n" +
PATH + "\n" +
CANONICAL_QUERY + "\n" +
X_TIMESTAMP + "\n" +
SHA256_HEX(BODY)
Secret handling: Carrier workspaces never see the shipper API secret. CheckPoint shows the raw shipper API secret once in the Shipper Portal on rotation, stores only 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 HMAC request
<?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);
Optional load binding fields
FieldTypeDescription
global_shipper_uuidstringBinds an active load to the global shipper API.
shipper_referencestringPO, BOL, order, or shipper shipment reference returned in the response.
shipper_visibility_enabledbooleanPer-load visibility kill switch. Defaults on when a global shipper UUID is provided.
Shipper visibility response and HMAC errors
Response shape
{
  "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"
}
HTTPError codeMeaning
401MISSING_HMAC_HEADERSMissing shipper UUID, timestamp, or signature header.
401INVALID_SHIPPER_UUIDThe shipper UUID is not valid UUID format.
401EXPIRED_HMAC_TIMESTAMPThe timestamp is outside the five-minute replay window.
401SHIPPER_NOT_ACTIVEThe global shipper is disabled or not found.
403INVALID_HMAC_SIGNATUREThe signature is not a 64-character lowercase hex HMAC.
403HMAC_SIGNATURE_MISMATCHThe 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.

Admin page

GPS Integrations — Settings → GPS Integrations. Requires Admin role (dispatchers cannot open this page).

Supported providers (V1)

Samsara — connection, vehicle sync, ELD refresh, auto/manual mapping.
Motive — same workflow: API key, sync, refresh, auto/manual mapping.
PeopleNet — planned; contact CheckPoint support.

TMS handoff (Expedite)

Expedite TMS — Motive / Samsara GPS handoff — copy-paste spec for initialize fields, auth split, and admin setup. No ELD API keys in TMS code.

Schema reference

checkpoint_schema.html → GPS Provider Integrationsgps_provider_connections, gps_vehicle_mappings, gps_vehicle_telemetry, and per-company app_credentials rows (gps_samsara, gps_motive, gps_provider).

Architecture doc

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 typeCompanies visibleOverview tableSecrets shown?
Client admin — one companyThat company only (e.g. Wilson)HiddenNever — only “token saved” yes/no
Client admin — multiple assigned companiesOnly companies checked in User AccessThose assigned companies onlyNever
Platform admin (is_platform_admin)All companies in CheckPointAll tenantsNever
Dispatcher403 — page blocked
Isolation rule: Manning does not appear for a Wilson-only login unless User Access explicitly grants Manning to that admin. Company scope comes from admin_user_company_access (see schema). Saving credentials requires a single-company workspace — not “All Companies”.

Related admin pages

PagePurpose
/gps-integrations.phpPer-company Samsara / Motive API setup, vehicle mapping, ELD refresh.
/gps-live-map-setup.phpGuided wizard: connect provider → sync fleet → map color → live map.
POST /v1/dashboard/refresh-provider-gps.phpAdmin session — refreshes all verified Samsara and Motive connections for the selected workspace(s).
/user-access.phpControls which companies a login can see in the workspace switcher and GPS overview.
/company-profile.phpTMS bearer tokens for initialize.php (separate from ELD provider keys).
/settings.phpSettings hub link to GPS Integrations.
/dashboard.phpLive 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:

FieldPurpose
tms_vehicle_idPrimary TMS tractor / power-unit ID for provider vehicle mapping.
power_unitSecondary matching key when display name differs from TMS ID.
Driver tracking unchanged: Asset GPS does not replace milestone SMS, web check-in, or the continuous driver app add-on. Send 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.

Endpoint

GET /v1/auth/tms-launch.php — returns 302 to /dashboard.php on success.

Admin setup

Company Profile → API client → Generate TMS Launch Secret. Separate from the initialize bearer token.

Full spec

Expedite TMS Live Map launch spec — HMAC canonical string, replay window, audit log, Expedite office fields.

QA helper

/dev/tms_launch_test_url.php — admin-only signed URL builder for QA (after secret is generated).

Query parameters

ParamRequiredNotes
company_idYesCheckPoint workspace ID (e.g. Small Town Trucking = 5).
tsYesUnix timestamp; must be within 120 seconds of server time.
clientYesV1: expedite — must match tms_launch_client_key on the API client row.
sigYesLowercase hex HMAC-SHA256 (64 chars). Key = SHA-256(raw_launch_secret).
nonceNoOptional replay guard; reused nonce within 10 minutes is rejected.
source, userNoAudit labels only (e.g. expedite_mobile_com, dispatcher username).
redirectNoRelative path only; default /dashboard.php.
Never in the URL: initialize bearer token, ELD API keys, or raw launch secret. Expedite stores CHECKPOINT_LAUNCH_SECRET server-side and signs each link at click time.

Expedite signing (PHP)

Signed launch URL
$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.

Outbound visibility: EXSPEEDITE receives HTTPS callbacks (not customer Integration Events). Configure URL and Bearer token under Settings Hub → EXSPEEDITE Callbacks. Event names match ExpediteCallbackService::eventCatalog() in the repo.
TopicEXSPEEDITE behavior
Required at initializeload_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 optionaltms_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 responseAlways includes correlation_id and tracking_session_id (trk_…). First init → status: "initialized". Repeat POST for same active load_numberstatus: "reinitialized" (equipment/stop refresh; same session id and customer links).
Validation errorsHTTP 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 changeRe-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.

Expandable reference: open only what you need
Top-level load fields
FieldTypeRequiredDescription
load_numberstringRequiredYour TMS load, shipment, or pro number. Must be unique while active for this tenant.
carrier_namestringRequiredCarrier or vendor name shown to dispatchers.
driver_assignment_modestringOptionalUse direct_driver when you have the driver phone. Use private_link when the carrier or driver should enter the phone privately.
tracking_modestringOptionalping (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_secondsintegerOptionalOnly when tracking_mode is continuous. Seconds between GPS breadcrumbs (10–900). Omit to use tenant default (usually 60).
carrier_contact_emailstringConditionalRequired for private_link. CheckPoint emails this recipient the private driver assignment link.
driver_namestringConditionalRequired for direct_driver. Optional for private_link because the private page collects it.
driver_phonestringConditionalRequired 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_emailstringOptionalDriver email for reference only. SMS failure does not trigger an automatic email.
tms_vehicle_id / power_unitstringOptionalTMS 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_numbersstring or arrayOptionalExtra load identifiers such as BOL, PO, shipment, order, or customer reference numbers.
commodity_descriptionstringOptionalPlain-English freight description. Use special_properties for hazmat, reefer, fragile, odor-sensitive, or stackability details.
total_weight_lbsnumberOptionalTotal freight weight in pounds.
piece_count / pallet_countintegerOptionalPiece, pallet, or skid quantities. Use freight_dimensions for dimensions or cube.
freight_class / nmfc_numberstringOptionalLTL freight class and NMFC when relevant.
trailer_type / equipment_specsstringOptionalDry van, reefer, flatbed, length, air-ride, liftgate, or other equipment requirements.
driver_assist / securement_requirements / onboard_toolsstringOptionalDriver assist, tarping, chains/straps, pallet jack, PPE, or other handling requirements.
detention_layover_terms / tracking_expectations / routing_hos_notesstringOptionalOperational context such as free time, ping/photo expectations, routing, HOS, or team-driver needs.
required_paperwork / special_instructionsstringOptionalSigned BOL, POD, seals, weight tickets, no-stacking rules, security protocols, damage reporting, or site rules.
broker_name / broker_contactstringOptionalDispatcher/internal broker context for load questions. CheckPoint does not expose these fields to driver, public share, or customer-facing Integration Events payloads.
user1 ... user10stringOptionalTenant-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_emailsarray or comma-separated stringOptionalEmail recipients for requested notifications. Multiple recipients are allowed.
email_notificationsobjectOptionalControls which email events are sent. If omitted or all false, no emails are sent.
stopsarrayRequiredOrdered 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.

Private assignment payload
{
  "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.

FieldValueNotes
tracking_mode"continuous"Per load. Omit or use ping for standard web workflow.
background_ping_interval_seconds10–900Optional 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.

Continuous dispatch payload
{
  "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.

FieldTypeMeaning
email_notifications.loadbooleanEmail when the load is created in CheckPoint.
email_notifications.pickupbooleanEmail when the driver checks in at pickup.
email_notifications.stopoffsbooleanEmail when the driver checks in at transit/stop-off stops.
email_notifications.checkpointsbooleanEmail for every driver checkpoint, regardless of milestone type.
email_notifications.deliveredbooleanEmail when the driver checks in at final delivery.
Stop fields and validation notes
FieldTypeRequiredDescription
stop_sequenceintegerRequired1-based order. Use 1, 2, 3 without gaps.
milestone_typestringRequiredOne 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_namestringRequiredFacility, 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.
address1stringOptionalStreet address used for map stop context when provided.
citystringRequiredStop city.
statestringRequiredTwo-letter state or region abbreviation recommended.
zipstringOptionalPostal code.
scheduled_atstringOptionalISO 8601 timestamp recommended, for example 2026-06-25T14:00:00Z.
time_window_start / time_window_endstringOptionalExact appointment or receiving window. If start is omitted, CheckPoint uses scheduled_at as the window start.
appointment_typestringOptionalAppointment process such as appointment, fcfs, or call_for_appointment.
load_unload_typestringOptionalLive load/unload, drop trailer, preloaded, or similar stop handling context.
facility_hours / appointment_processstringOptionalReceiving hours, call-ahead, check-in, or appointment scheduling notes.
dock_instructions / access_rules / stop_restrictions / driver_instructionsstringOptionalDock, gate, access, PPE, parking, security, and site-specific instructions safe for the driver workflow.
Recommended connector standard: send at least one pickup and one delivery, keep stop sequences consecutive, and mark every intermediate stop-off as transit. CheckPoint supports multiple pickups and multiple deliveries when trucking operations need them.
Custom field safety: 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.
Connector validation checklist: before posting to CheckPoint, confirm 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.

Milestone SMS · 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".

Live GPS Trail · 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)

FieldValuesWhen to use
tracking_modeping | continuousPer load at dispatch. Default ping if omitted.
background_ping_interval_seconds10–900Only for continuous. Optional override of tenant default (60s typical).

Initialize response fields (store in TMS audit log)

FieldAlways?Meaning
tracking_modeYesEcho of stored mode: ping or continuous.
tracking_urlDirect driverMilestone web check-in link (first stop). Same for both modes.
driver_app_urlContinuous onlyDeep link checkpoint://track?token=… for Android app sync.
driver_app_sms_sentContinuous onlytrue when CheckPoint texted the app sync link to the driver.
sms_sentDirect driverFirst milestone SMS sent (both modes).
What your TMS does NOT do: post background GPS, build driver pages, or manage milestone taps. Send tracking_mode at initialize; CheckPoint and the driver app handle the rest.
Ping mode initialize (default)
{
  "load_number": "EXS-104901",
  "carrier_name": "Manning Transfer",
  "driver_name": "John Driver",
  "driver_phone": "+17634446474",
  "tracking_mode": "ping",
  "stops": [ /* … */ ]
}
Continuous mode initialize
{
  "load_number": "EXS-104902",
  "carrier_name": "Manning Transfer",
  "driver_name": "John Driver",
  "driver_phone": "+17634446474",
  "tracking_mode": "continuous",
  "background_ping_interval_seconds": 60,
  "stops": [ /* … */ ]
}
HTTP 200 response — continuous + app sync
{
  "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

HTTPerror_codeMeaningFix
400CONTINUOUS_TRACKING_DISABLEDTenant Live GPS add-on is off but request sent continuous.Enable add-on in CheckPoint Settings Hub, or send ping.
400INVALID_BACKGROUND_INTERVALbackground_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.

TMS connector scope: your initialize call only needs 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)

EndpointMethodPurpose
/v1/tracking/load-info.phpPOST JSONLoad context, stops, and tracking block (interval, flags, tracking_stopped, links.web_checkin).
/v1/tracking/background-ping.phpPOST JSONRecord background GPS in track_background_pings. Returns ping_id and resolved interval.
/v1/tracking/ping.phpPOST JSONSame milestone web check-in as ping-mode loads (optional on continuous loads for POD/milestones).
load-info request / tracking block
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=..."
  }
}
background-ping request
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

HTTPMeaning
200Ping stored. Body includes ping_id and background_ping_interval_seconds for client timer.
401Invalid or expired token.
403Tenant add-off disabled, or load is ping mode.
409Load 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.

Full JSON payload
{
  "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"
    }
  ]
}

Responses and errors

Success response

HTTP 200 direct-driver 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"
}
HTTP 200 private-link response
{
  "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

Example error
{
  "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
HTTPError codeMeaningRecommended action
200noneLoad accepted and initialized.Store the response for audit. Direct-driver mode attempts SMS immediately; private-link mode returns assignment_url.
400MISSING_MANDATORY_FIELDSOne 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.
400INVALID_DRIVER_ASSIGNMENT_MODEdriver_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.
400INVALID_DRIVER_PHONEDirect-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.
400INVALID_STOPS_PAYLOADstops 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.
400INVALID_STOP_SEQUENCEA 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.
400INVALID_STOP_MILESTONE_TYPEA 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.
400MISSING_STOP_LOCATION_NAMEA stop has a blank location_name.Send the facility, shipper, consignee, or a safe fallback such as Pickup Stop, Transit Stop, or Delivery Stop.
400MISSING_STOP_CITY_STATEA 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.
401INVALID_BEARER_TOKENBearer token missing, inactive, or invalid.Verify the token generated for the client workspace.
400CONTINUOUS_TRACKING_DISABLEDtracking_mode: continuous requested but tenant Live GPS add-on is disabled.Enable Continuous Background GPS in Settings Hub, or default to ping.
400INVALID_BACKGROUND_INTERVALbackground_ping_interval_seconds is missing, non-numeric, or below minimum (10).Omit the field or send an integer from 10 through 900.
200reinitializedSame 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.
500SERVER_ERRORUnexpected server failure.Retry later and contact support with the load number and timestamp.
Copy/paste connector rule: treat HTTP 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.

When they fire

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.

Customer-safe context

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.

Internal fields: 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.
Secure JSON webhook shape
{
  "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.

ValidateToken, required fields, direct-driver phone, and stops are checked.
CreateThe active load, stops, and tracking token are stored. tracking_mode defaults to ping.
NotifyDirect-driver mode sends SMS now. Private-link mode sends SMS after private assignment. Email is sent only when requested.
TrackPing mode: driver uses web link. Continuous mode (add-on): driver app may send background GPS between milestones.
AdvanceEach driver milestone check-in sends the next stop link automatically.
CompleteThe final delivery check-in or manual close expires the token, stops background tracking, and closes the load.

Testing checklist

Use this checklist before moving a connector from sandbox testing to production traffic.

Send a multi-stop load with pickup, Stop / Stop-off, and delivery, then confirm HTTP 200.
For direct-driver mode, confirm the driver phone receives the first CheckPoint link.
For private-link mode, confirm assignment_url opens the private assignment page and SMS is only sent after assignment.
Open the link and verify the driver sees the correct current stop.
Complete pickup and confirm the next-stop SMS is sent.
Complete final delivery and confirm the load becomes completed.
Verify the dispatcher dashboard shows the latest milestone and map marker.
If using continuous mode: confirm tenant add-on is enabled, dispatch with tracking_mode: "continuous", and verify background pings appear on Trail/History (teal dots).
If using continuous mode: confirm load-info.php returns tracking.background_tracking_active: true and background-ping.php returns HTTP 200 for a valid token.

Troubleshooting

SymptomLikely causeFix
401 INVALID_BEARER_TOKENThe 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_FIELDSA 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_PHONEThe 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_PAYLOADstops 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_TYPEA 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_SEQUENCEA 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_STATEA 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 returneddriver_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 reinitializedActive load updated in place (tractor swap, stop refresh).Keep the same CheckPoint session; update TMS display from response fields only.
400 MISSING_DELIVERY_STOPNo stop with milestone_type: "delivery".Add a delivery stop before retrying.
Driver did not receive SMSCarrier 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 yetThe 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 pingTenant 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 showDriver app not installed, permissions denied, or background pings failing.Verify token, app deep link, and Always/background location permission on the device.

Security notes

Use HTTPS only

Always call the production endpoint over HTTPS from trusted server-side code.

Protect bearer tokens

Store tokens in environment variables or a secrets manager. Do not embed them in browser JavaScript.

Retry carefully

Retry network failures, but do not blindly retry 409 or invalid payload errors.

Keep load IDs stable

Use the same load number your operations team recognizes in the TMS.