Migrate from the Legacy CarrierOk API
If your integration calls a …gateway.dev host with an X-Api-Key header — the API documented at docs.carrier-ok.com — this page moves you to the current platform. Both hosts run the same backend, so the migration is two lines: the base URL and the auth header. Your response parsing does not change.
No forced cutover today
Create a developer account and mint a key
Sign up at developers.carrierok.com — a free sandbox key (sk_test_, fixture data, no card) lets you verify the integration first; activating live access mints an sk_live_key. If you're on an existing legacy contract or volume plan, email support@carrierok.com before cutting over so billing transitions instead of doubling.
Swap the base URL and auth header
Two changes: the host, and the header. Note the legacy /api path prefix is dropped on the new host.
# Legacy
curl "https://carrier-okay-…uc.gateway.dev/api/v2/profile?dot_number=568253" \
-H "X-Api-Key: YOUR_LEGACY_KEY"
# Current — same endpoint, same response shape
curl "https://api.carrierok.com/v2/profile?dot_number=568253" \
-H "Authorization: Bearer sk_live_YOUR_KEY"{
"items": [
{
"dot_number": "568253",
"legal_name": "EXAMPLE LOGISTICS INC",
"...": "same 320+-field shape you already parse"
}
],
"total_count": 1
}Map your endpoints
Every legacy endpoint has a same-named equivalent. Query parameters (all ten profile search keys), request bodies, and response shapes are unchanged:
| Endpoint | Legacy (…gateway.dev) | Current (api.carrierok.com) |
|---|---|---|
| Profile | /api/v2/profile | /v2/profile |
| Profile Lite | /api/v2/profile-lite | /v2/profile-lite |
| Autocomplete | /api/v2/autocomplete | /v2/autocomplete |
| Monitoring — add | /api/v2/monitoring/add | /v2/monitoring/add |
| Monitoring — remove | /api/v2/monitoring/remove | /v2/monitoring/remove |
| Monitoring — list | /api/v2/monitoring/list | /v2/monitoring/list |
Endpoint reference: Profiles · Monitoring. The Google Sheet field reference linked from the legacy docs is superseded by the data dictionary.
Verify, cut over, retire the old key
Point your existing test suite (or a handful of known DOT numbers) at the new host and diff the responses — they should be byte-shape identical. Cut production traffic over, watch your error rates for a day, then stop using the legacy credentials. Rate-limit behavior on the new host is documented in rate limits & errors — 429s carry a Retry-After header.
FAQ
Do my existing legacy CarrierOk API keys stop working?
No — legacy X-Api-Key credentials keep working at the legacy host for now. Migration is recommended: the new platform adds self-serve key management, a free sandbox, usage visibility, and the docs, OpenAPI spec, and data dictionary at developers.carrierok.com. A sunset date for the legacy host will be communicated to affected customers in advance.
Does the response format change when I migrate?
No. Both hosts are served by the same backend — /v2/profile, /v2/profile-lite, /v2/autocomplete, and the monitoring endpoints return the same JSON shape. Your existing parsing code works unchanged; only the base URL and auth header differ.
What happens to my existing plan and billing?
New keys use the portal's self-serve billing ($50 activation applied as API credit, then pay-as-you-go). If you're on an existing legacy contract or volume plan, contact support@carrierok.com before cutting over so billing is transitioned rather than doubled.
Where did the API documentation move?
The legacy Postman-published docs at docs.carrier-ok.com describe the legacy host and auth. Current documentation — including the 320+-field data dictionary and a typed OpenAPI spec — lives at developers.carrierok.com/docs.