TopTracking Carrier API Documentation

Base URL

Production: https://vendor.toptracking.com

Overview

The TopTracking Carrier API provides secure access to carrier-specific data and fleet information. All endpoints require API key authentication via the x-api-key header.

Authentication

All endpoints require an API key to be provided in the request header.

API Key Authentication

Include your API key in the x-api-key header with every request:

GET /carrier/v1/company/info
x-api-key: your-api-key-here

Important: Keep your API key secure and never expose it in client-side code or public repositories.

Rate Limiting

API requests are subject to rate limiting to ensure fair usage and system stability. Rate limits are applied per API key.

Rate Limit Headers

The API includes rate limit information in response headers:

X-RateLimit-Limit: Maximum number of requests allowed in the time window
X-RateLimit-Remaining: Number of requests remaining in the current window
X-RateLimit-Reset: Unix timestamp when the rate limit window resets

Rate Limit Tiers

Tier	Requests per Minute	Requests per Day	Requests per Month
Basic	60	5,000	100,000

If you exceed the rate limit, you will receive a 429 Too Many Requests response.

Common Response Codes

Status Code	Description	Error Code
200	Success	-
400	Bad Request - Invalid parameters	`bad_request`
401	Unauthorized - Invalid or missing API key	`unauthorized`
404	Not Found - Resource not found	`not_found`
429	Too Many Requests - Rate limit exceeded	`too_many_requests`
500	Internal Server Error	`internal_server_error`
503	Service Unavailable - External service unavailable	`service_unavailable`

Error Response Format

When an error occurs, the API returns a standardized JSON object with error details:

{
  "error": "bad_request",
  "errorDescription": "VIN is required"
}

Error Field Values:

bad_request - 400 Bad Request
unauthorized - 401 Unauthorized
forbidden - 403 Forbidden
not_found - 404 Not Found
too_many_requests - 429 Too Many Requests
internal_server_error - 500 Internal Server Error
service_unavailable - 503 Service Unavailable

Endpoints

Get Company Information

Retrieves basic information about the authenticated carrier company.

Endpoint: GET /carrier/v1/company/info

Headers:

x-api-key (required): Your API key

Response: 200 OK

{
  "name": "ABC Trucking Company",
  "dotNumber": "1234567",
  "isOwnerOperator": false
}

Response Fields:

name (string): Company name
dotNumber (string, nullable): US DOT number
isOwnerOperator (boolean): Indicates if this is an owner-operator company

Error Responses:

401 Unauthorized: Invalid or missing API key

{
  "error": "unauthorized",
  "errorDescription": "API key is required"
}

404 Not Found: Company not found or inactive

{
  "error": "not_found",
  "errorDescription": "Company not found or inactive for the provided API key"
}

Example Request:

curl -X GET "https://vendor.toptracking.com/carrier/v1/company/info" \
  -H "x-api-key: your-api-key-here"

Example Response:

{
  "name": "ABC Trucking Company",
  "dotNumber": "1234567",
  "isOwnerOperator": false
}

Get Vehicle Snapshots

Retrieves snapshot data for all vehicles in the carrier's fleet.

Endpoint: GET /carrier/v1/snapshots

Headers:

x-api-key (required): Your API key

Response: 200 OK

Returns an array of vehicle snapshot objects.

Example Request:

curl -X GET "https://vendor.toptracking.com/carrier/v1/snapshots" \
  -H "x-api-key: your-api-key-here"

Example Response:

[
  {
    "assetId": 12345,
    "number": "TRUCK-001",
    "vin": "1HGBH41JXMN109186",
    "location": {
      "latitude": 40.7128,
      "longitude": -74.0060,
      "timestamp": "2024-01-15T10:30:00Z"
    },
    "dotNumber": "1234567"
  },
  {
    "assetId": 12346,
    "number": "TRUCK-002",
    "vin": "1HGBH41JXMN109187",
    "location": {
      "latitude": 40.7580,
      "longitude": -73.9855,
      "timestamp": "2024-01-15T10:25:00Z"
    },
    "dotNumber": "1234567"
  }
]

Response Fields:

assetId (integer): Asset ID in Connect ELD system
number (string, nullable): Vehicle/unit number
vin (string, nullable): Vehicle Identification Number
location (object, nullable): Location information
- latitude (number): GPS latitude coordinate
- longitude (number): GPS longitude coordinate
- timestamp (string): Timestamp of the location data in UTC (ISO 8601)
dotNumber (string, nullable): DOT number associated with this vehicle

Error Responses:

401 Unauthorized: Invalid or missing API key, or company is inactive/archived
```
{
  "error": "unauthorized",
  "errorDescription": "Company not found"
}
```

503 Service Unavailable: External service is temporarily unavailable

{
  "error": "service_unavailable",
  "errorDescription": "Failed to retrieve data from Connect ELD service"
}

Get Vehicle Snapshot by Asset ID

Retrieves snapshot data for a specific vehicle/asset.

Endpoint: GET /carrier/v1/snapshots/{assetId}

Path Parameters:

assetId (integer, required): The asset/vehicle ID

Headers:

x-api-key (required): Your API key

Response: 200 OK

Returns a single vehicle snapshot object.

Example Request:

curl -X GET "https://vendor.toptracking.com/carrier/v1/snapshots/12345" \
  -H "x-api-key: your-api-key-here"

Example Response:

{
  "assetId": 12345,
  "number": "TRUCK-001",
  "vin": "1HGBH41JXMN109186",
  "location": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "timestamp": "2024-01-15T10:30:00Z"
  },
  "dotNumber": "1234567"
}

Response Fields:

assetId (integer): Asset ID in Connect ELD system
number (string, nullable): Vehicle/unit number
vin (string, nullable): Vehicle Identification Number
location (object, nullable): Location information
- latitude (number): GPS latitude coordinate
- longitude (number): GPS longitude coordinate
- timestamp (string): Timestamp of the location data in UTC (ISO 8601)
dotNumber (string, nullable): DOT number associated with this vehicle

Error Responses:

401 Unauthorized: Invalid or missing API key, or company is inactive/archived
```
{
  "error": "unauthorized",
  "errorDescription": "Company not found"
}
```

404 Not Found: Asset with the specified ID was not found

{
  "error": "not_found",
  "errorDescription": "Asset with ID 12345 not found"
}

503 Service Unavailable: External service is temporarily unavailable

{
  "error": "service_unavailable",
  "errorDescription": "Failed to retrieve data from Connect ELD service"
}

Get Tractors

Retrieves all tractors/vehicles in the carrier's fleet.

Endpoint: GET /carrier/v1/tractors

Headers:

x-api-key (required): Your API key

Response: 200 OK

Returns an array of tractor/vehicle objects.

Example Request:

curl -X GET "https://vendor.toptracking.com/carrier/v1/tractors" \
  -H "x-api-key: your-api-key-here"

Example Response:

[
  {
    "assetId": 12345,
    "number": "TRUCK-001",
    "vin": "1HGBH41JXMN109186"
  },
  {
    "assetId": 12346,
    "number": "TRUCK-002",
    "vin": "1HGBH41JXMN109187"
  }
]

Response Fields:

assetId (integer): Asset ID in Connect ELD system
number (string, nullable): Vehicle/unit number
vin (string, nullable): Vehicle Identification Number

Error Responses:

401 Unauthorized: Invalid or missing API key, or company is inactive/archived
```
{
  "error": "unauthorized",
  "errorDescription": "Company not found"
}
```

503 Service Unavailable: External service is temporarily unavailable

{
  "error": "service_unavailable",
  "errorDescription": "Failed to retrieve data from Connect ELD service"
}

Get DOT Number by VIN

Retrieves the DOT number associated with a vehicle by its VIN (Vehicle Identification Number).

Endpoint: GET /carrier/v1/vehicles/{vin}/dot-number

Path Parameters:

vin (string, required): Vehicle Identification Number

Headers:

x-api-key (required): Your API key

Response: 200 OK

{
  "vin": "1HGBH41JXMN109186",
  "dotNumber": "1234567"
}

Response Fields:

vin (string): The VIN that was queried
dotNumber (string): The DOT number associated with the VIN

Example Request:

curl -X GET "https://vendor.toptracking.com/carrier/v1/vehicles/1HGBH41JXMN109186/dot-number" \
  -H "x-api-key: your-api-key-here"

Example Response:

{
  "vin": "1HGBH41JXMN109186",
  "dotNumber": "1234567"
}

Error Responses:

400 Bad Request: VIN is required or invalid

{
  "error": "bad_request",
  "errorDescription": "VIN is required"
}

401 Unauthorized: Invalid or missing API key, or company is inactive/archived
```
{
  "error": "unauthorized",
  "errorDescription": "Company not found"
}
```

404 Not Found: DOT number not found for the specified VIN

{
  "error": "not_found",
  "errorDescription": "DOT number not found for VIN 1HGBH41JXMN109186"
}

503 Service Unavailable: External service is temporarily unavailable

{
  "error": "service_unavailable",
  "errorDescription": "Failed to retrieve data from Connect ELD service"
}

Best Practices

API Key Security

Never commit API keys to version control
Use environment variables to store API keys in your application
Rotate API keys periodically for enhanced security
Use HTTPS only - Never make API calls over unencrypted connections

Error Handling

Always implement proper error handling in your application:

Check response status codes before processing response data
Handle rate limiting - Implement exponential backoff when receiving 429 responses
Retry logic - For transient errors (503), implement retry logic with exponential backoff
Log errors - Log API errors for debugging and monitoring

Rate Limiting

Monitor rate limit headers to avoid hitting limits
Implement caching where appropriate to reduce API calls
Batch requests when possible to minimize API usage
Respect rate limits - Do not attempt to bypass or exceed rate limits

Request Optimization

Use appropriate endpoints - Use specific endpoints (e.g., by asset ID) when you only need specific data
Cache responses - Cache data that doesn't change frequently
Minimize requests - Combine multiple data needs into fewer requests when possible

Support

For API support, rate limit increases, or to report issues, please contact your TopTracking account representative.

Changelog

Version 1.0

Initial release of Carrier API
Company information endpoint
Vehicle snapshots endpoints
Tractors endpoint
DOT number lookup by VIN

Carrier API Documentation v1.0

TopTracking Carrier API Documentation

Base URL

Overview

Authentication

API Key Authentication

Rate Limiting

Rate Limit Headers

Rate Limit Tiers

Common Response Codes

Error Response Format

Endpoints

Get Company Information

Get Vehicle Snapshots

Get Vehicle Snapshot by Asset ID

Get Tractors

Get DOT Number by VIN

Best Practices

API Key Security

Error Handling

Rate Limiting

Request Optimization

Support

Changelog

Version 1.0