What is the ClearPathGPS API?

A REST API that lets you read vehicle, driver, location, and event data from your ClearPathGPS account, and receive event updates through webhooks. It uses standard HTTPS and JWT bearer authentication.

Where is the API documentation?

The API reference is at api-doc.clearpathgps.com.

Log in with your ClearPathGPS credentials to view the full endpoint list, request and response schemas, and webhook examples.

What is the base URL for API calls?

All customer-facing API calls go to https://api.clearpathgps.com. The current version prefix is in the reference documentation.

The Swagger docs show URLs ending in ".internal.clearpathgps.com". Can I call those?

No. Internal URLs are for our own services and are not reachable from the public internet.

Use https://api.clearpathgps.com as the base URL and pair it with the endpoint path shown in the reference.

Do I need a VPN or IP allowlist to reach the API?

No. The API is a public HTTPS endpoint. Authentication is handled through a JWT bearer token, not a network allowlist.

How do I authenticate?

Call the auth endpoint with your API user's emailId and password in a JSON body, receive a JWT token, and include the token as a Bearer credential in the Authorization header on every subsequent request.

Should I use my main account credentials or create a separate user for my integration?

It’s up to you. You can absolutely create a dedicated user account on your ClearPathGPS account for the integration. Use that account's credentials to generate tokens. This keeps human logins and integration traffic separate.

What are the access-token and refresh-token lifetimes?

You cacn control the refresh and expiration behavior in your integration when you request tokens. Refresh the token before it expires and cache it for the interval you configure.

Is there a sandbox or test environment?

No. There is no separate sandbox. For testing, you can use your production account and point new webhooks at a staging URL you control before switching to your production endpoint.

Are there rate limits on the API?

There are no documented numerical rate limits. Vehicles report every 30 seconds, so polling more often than every 10 seconds returns the same data.

How often should I poll for current vehicle locations?

Every 10 to 30 seconds. Anything more frequent will likely not return new data. If you need faster reactivity to specific events, use a webhook instead.

Where do I find DVIR endpoints?

DVIR endpoints, including template retrieval, are in the API reference at api-doc.clearpathgps.com.

Authenticate with your ClearPathGPS credentials to view them.

Can I use Postman to test the API?

Yes. Send a POST to the auth endpoint with your JSON credentials, copy the JWT from the response, set Authorization to Bearer with that token in a new request, then call the endpoint you want to test.

Does the API support webhooks?

Yes. Webhooks let you receive event notifications in real time instead of polling.

How do I create a webhook?

Send a POST request to the webhooks endpoint with your endpoint URL and the array of event statusCodes you want to subscribe to. The response includes the webhook ID and the secret used for signature verification.

Can I create a webhook from the ClearPathGPS portal?

No. Webhooks are created and managed through the API only. There is no webhook management screen in the portal.

Are webhooks signed?

Yes. All new webhooks are signed by default with HMAC-SHA256.

Which header carries the signature?

The ClearPathGPS-Signature header carries the HMAC signature. A companion header, ClearPathGPS-Webhook-Event-Id, carries a unique event UUID for idempotency on your side.

How is the signature encoded?

As a raw hex string with no prefix. Do not expect a sha256= prefix in front of the value.

What content is signed?

The raw JSON body only. Timestamp and URL are not included in the signed content, and no X-Timestamp header is sent.

Where do I get the webhook secret?

ClearPathGPS generates the secret and returns it in the response body of the first POST /webhooks call. Copy it immediately and store it securely.

I lost my webhook secret. Can I retrieve it?

No. The secret is only returned once. If it is lost, delete the webhook and create a new one to receive a fresh secret.

What does a webhook event payload contain?

An eventType, an eventSource, and an event object with accountId, deviceId, timestamp, statusCode, statusCodeText, latitude, longitude, speedKph, address, heading, and geozoneId. See the sample payload below.

Are odometer and engine hours included in the webhook payload?

No. Odometer and engine hour readings are not part of the webhook payload today. You can use the Events API endpoint alongside the webhook to retrieve them per event.

Is PTO sensor data included in the webhook payload?

PTO status is reported through digital input status codes (Input 1 On/Off through Input 4 On/Off) on devices wired for it. Subscribe to those status codes to receive PTO activity.

Do I need to distinguish between the specific trigger conditions listed in the API doc for a given status code?

No. The trigger conditions in the doc are examples of what can produce a given status code. Use the top-level statusCode value to route events on your side.

How do I migrate from an unsigned webhook to a signed one?

Create a new webhook via POST /webhooks (signing is default), point it at your endpoint, capture the returned secret, validate signature handling against staging, and delete the old webhook once you have confirmed the new one is delivering.

If I have both an old and new webhook subscribed to the same events, will I receive duplicates?

Yes. Both webhooks receive the same events during the overlap. Delete the old webhook once you have cut over.

What happens to events queued for a webhook I delete?

The queue is dropped and no further delivery is attempted for the deleted webhook. The events themselves still live in ClearPathGPS and can be pulled via the REST API if you need to backfill.

Where do I find the full list of event status codes, including geofence arrival and departure?

The full status code list is documented at api-doc.clearpathgps.com, including the Geozones section for arrival and departure. Common codes are also listed below.

How do I test my webhook before going live?

Point a new webhook at a staging endpoint you control, validate signature verification and event handling end to end, then delete the staging webhook and create a production one pointing at your live endpoint.

Ignition_On

62465

Ignition_Off

62467

Moving

61472

Excess_Accel

63840

Braking

63792

Cornering

63799

Speeding

61722

Idle

61718

Stop

61715

Arrive (geofence)

61968

Depart (geofence)

62000

Power_On

64793

Power_Connect

64789

Power_Disconnect

64787

Low_Vehicle_Battery

64784

Service_Suspend

4101

Input 1 On / Off

62497 / 62529

Input 2 On / Off

62498 / 62530

Input 3 On / Off

62499 / 62531

Input 4 On / Off

62500 / 62532

Fault Code

63761

I can authenticate but my calls to /vehicles return empty. What should I check?

Confirm you are using credentials tied to an account that has vehicles, and confirm your API user has access to those vehicles. If both are true and the response is still empty, contact ClearPathGPS Support.

I'm getting USER_NOT_FOUND on the auth endpoint. What should I check?

Confirm you are using the correct base URL (https://api.clearpathgps.com), the correct version prefix from the reference, and that the emailId in your JSON body matches an active user on your ClearPathGPS account.

Does ClearPathGPS pause webhook delivery after repeated failures?

Yes. A circuit breaker reduces or stops delivery when your endpoint returns consecutive 4xx or 5xx errors. Once your endpoint is healthy again, contact ClearPathGPS Support to re-enable delivery.

Can I check whether my webhook delivery is paused?

No. The circuit breaker state is not exposed in GET /webhooks. If events stopped and your device is active, contact ClearPathGPS Support.

My webhook is registered but I don't see any events. What should I check?

Confirm the vehicle was active during the window, check that your statusCodes subscription includes the events you expect, check your endpoint logs for inbound POSTs, and confirm your firewall is not blocking the requests. If all four are clean, contact ClearPathGPS Support.