Developers · API v1.4.1
Your systems get the same freight record your dispatchers see. A REST API to read and write it, signed webhooks when something changes, and a connector that lets your AI assistant do the work.
Docs: API reference · AI assistants
REST API
A key acts as the user who created it, inside that user’s company, with the same role and plan limits. A carrier that isn’t bookable in the app isn’t bookable through the API either: the load isn’t created, and you get a 400 with a stable code that says why.
| Method | Path under /api/v1 | What it does | Key needs |
|---|---|---|---|
| GET | /ping | Check a key: which company, which user, which scopes | read |
| GET | /verifications | List verifications, with status and Trust score filters | read |
| GET | /verifications/{id} | One verification in full | read |
| POST | /verifications | Create and start a verification. Uses one credit | verifications:create |
| GET | /carriers | Your carrier roster, filter by verdict | read |
| GET | /carriers/{id} | Authority, insurance on file, history and change log | read |
| GET | /customers | Customers, with an updatedAfter filter for incremental sync | read |
| GET | /customers/{id} | Contacts, addresses and the credit profile | read |
| GET | /loads | Loads, with the same filters as the app’s load list | read |
| GET | /loads/{id} | Stops, charges, references, status history, margin | read |
| POST | /loads | Create a load. Takes an Idempotency-Key for safe retries | write |
| PATCH | /loads/{id}/status | Move a load. A 400 lists the allowed next statuses | write |
| GET | /loads/{id}/check-calls | The load’s check-call timeline | read |
| POST | /loads/{id}/check-calls | Record a location, note or ETA | write |
curl -X POST "https://api.happytactic.com/api/v1/loads" \
-H "Authorization: Bearer $HAPPYTACTIC_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c2a9e-3b7d-4c55-9e0a-1d2f3a4b5c6d" \
-d '{"partyId":"cmrpgygm900yxqyrjy42el8a3",
"originCity":"Cleveland","originState":"OH",
"destinationCity":"Savannah","destinationState":"GA",
"pickupDate":"2026-08-01","deliveryDate":"2026-08-03",
"equipmentType":"van","weight":24000,
"customerRate":1850,"carrierRate":1500}'{
"load": {
"id": "cmrr6gyru000ld16gducdz4op",
"loadNumber": "LD-R6GYRA-GIKR",
"status": "draft",
"dispatchStage": "pending",
"customerRate": 1850,
"carrierRate": 1500,
"margin": 350,
"marginPct": 18.92
},
"created": true
}Keys
Create a key under Settings → API Keys and name it for where it will live. The full key is shown once. Send it in an Authorization: Bearer or X-Api-Key header.
verifications:create scope is for company admins, because each one uses a credit and emails the carrier’s owner.Outbound webhooks
Set a URL and a signing secret under Settings → Company controls → Webhooks & services. Tick the load events you want. Polling is optional.
verification_completeA final status, or the final decision changed
verification_review_requiredStill in progress, and it turned yellow
load.status_changedEvery status move
stop.arrivedA stop’s arrival was recorded, once per stop
stop.departedA stop’s departure was recorded, once per stop
eta.changedA stop’s first ETA, then whenever it moves 15 minutes or more
locationThe truck’s position, at most one every 15 minutes per load
Each delivery carries X-Happytactic-Signature-V2, an HMAC-SHA256 of the timestamp and the raw body. Reject anything more than 300 seconds old.
A failed delivery retries after 1 minute, 5 minutes and 30 minutes, then every 30 minutes, 5 attempts in all. Answer 2xx quickly. Deduplicate load events on eventId, and verification events on verificationId plus decision.
const crypto = require('crypto');
function verifyHappytactic(secret, headers, rawBody, now = Date.now()) {
const parts = Object.fromEntries(String(headers['x-happytactic-signature-v2'] || '')
.split(',').map((p) => p.split('=').map((s) => s.trim())));
const t = Number(parts.t);
if (!Number.isInteger(t) || Math.abs(Math.floor(now / 1000) - t) > 300) return false;
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
return /^[a-f0-9]{64}$/.test(parts.v2 || '') &&
crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(parts.v2, 'hex'));
}AI assistants connector
Claude, ChatGPT, Cursor and Claude Code connect with your API key. 28 tools. Each load, carrier, customer and verification tool matches an API endpoint, with the same validation and limits.
Things you can type
ChatGPT’s write tools depend on your ChatGPT plan and workspace settings. Start there with a read-only key.
Set it up: AI assistants guide| Key permission | Lets the assistant | Who can give it |
|---|---|---|
| Read | Look up loads, check calls, customers, carriers, verifications, today’s pickups and deliveries | Anyone |
| Write | Create loads, change load statuses, add check calls | Owner or admin |
| Create and start verifications | Start verifications. Each uses a credit and emails the carrier’s owner | Owner or admin |
| Set up my account | Company details and defaults, customers and contacts, invite teammates | Owner or admin |
Changelog
Load answers no longer include tracking and driver check-in link secrets. Reference expanded with real response samples and more load filters and fields. New AI assistants page.
POST /v1/verifications is back behind its own key permission. It runs the same path as New verification in the app. AI assistants can connect with the same keys.
Idempotency-Key on POST /v1/loads. Webhook signature v2 with a timestamp. Load webhooks. API keys expire, 1 year by default.
Older versions are in the full changelog. Prefer connecting through a named product? See the integrations board.
Questions brokers ask
https://api.happytactic.com/api/v1. JSON over HTTPS. The current version is v1.4.1, and the full reference with its changelog is at app.happytactic.com/docs/api.
In the app, under Settings → API Keys. The full hkpt_ key is shown once, when you create it. Keys are read-only unless you allow write access, and only the account owner or an admin can create a write key. Starting verifications needs its own permission, for company admins only.
Yes. POST /api/v1/verifications takes an MC or DOT number and the dispatcher’s details, and runs the same path as New verification in the app: credit check, daily limit, checks and the owner’s emails. Each one uses a credit. Read the result with GET /api/v1/verifications/{id} or take the decision webhook.
Each GET endpoint allows 120 requests a minute and each POST or PATCH endpoint 60, counted per user. Creating verifications is limited to 10 a minute. Every response carries X-RateLimit headers, and a 429 adds Retry-After.
Use X-Happytactic-Signature-V2. Parse t and v2, reject anything more than 300 seconds old, compute HMAC-SHA256 of the timestamp, a dot and the raw body with your secret, and compare in constant time. Retries are signed again with their own timestamp, 5 attempts in all.
Claude, ChatGPT, Cursor and Claude Code, using your API key. Other assistants that support remote tools can connect too. The AI assistants guide has the steps for each one.
It can’t delete anything, change billing, your plan, payments or security settings, or make someone an admin. It can’t yet work with drivers, equipment, invoices, bills or settlements, read or upload documents, or send tenders. Starting a verification or inviting a teammate needs your yes first, and every change goes in your audit log with the key’s name.
Hotshot has no TMS, so load and customer endpoints return 403 for those keys. Verifications and carriers aren’t part of the TMS module. The same plan limits apply through the API as in the app.
API keys are in Settings once you’re in. Verification is on every plan, and the full TMS starts at Regional.