JSON API overview - Hellotracks developer docs

Last Updated: June 29, 2026 Current API Version: 2
Questions? Contact api@hellotracks.com

Every endpoint is a POST to https://api.hellotracks.com/api/<name> with a JSON body. It covers jobs, dispatch and routing, live locations, members, places, reports and webhooks, and most existing integrations use it.

Building a tool or automation on plain REST resources? See the REST API. Working from a terminal or with an AI agent? See the CLI.

🚀 Quick Start

1. Get Your API Key

Log in to https://live.hellotracks.com
Navigate to More → API & Integrations
Enable APIs in the API section
Copy your API key

Keep your API key secure! Never commit it to version control or expose it in client-side code.

2. Make Your First Request

/api requests use the POST method with JSON payloads. Connector endpoints under /v1 use REST methods such as GET, POST, PATCH, PUT, and DELETE.

curl -X POST https://api.hellotracks.com/api/getjobs \
  --header 'API-Key: YOUR_API_KEY_HERE' \
  --header 'Content-Type: application/json' \
  -d '{
    "data": {
      "day": 20251008,
      "worker": "*"
    }
  }'

3. Explore Common Use Cases

Job Management

Create, assign, and track jobs for your field workers

Route Optimization

Optimize routes to minimize travel time and distance

Location Tracking

Retrieve real-time and historical location data

Reports

Generate comprehensive reports (jobs, mileage, timesheet, etc.)

🔐 Authentication

Every API request requires authentication via the API-Key header:

--header 'API-Key: YOUR_KEY_ID.YOUR_SECRET'

See the Authentication page for complete details.

📡 API Basics

Base URL

https://api.hellotracks.com/api/

Request Format

/api requests use POST with a JSON body:

{
  "data": {
    "day": 20251008
  }
}

Endpoint-specific parameters go inside data.

Response Format

Most /api responses return JSON with a status field. Report generation streams the requested file content on success.

{
  "status": 0
}

status is 0 on success and negative on errors (see below); errors also carry an errorMsg. Endpoint-specific fields come next to status.

The API is Stateless

Each request is independent. No session management is required.

✅ Status Codes

HTTP Status Codes

Code	Type	Description
200	OK	Request successfully processed
500, 502, 503	Server Error	Temporary server issues - retry with backoff
504	Timeout	Request took too long - try reducing data size

Application Status Codes

The status field in the response indicates operation success:

Status	Meaning	Description
0	Success	Request completed successfully
-1	Format Error	Invalid or malformed request data
-2	User Unknown	Login with an unknown username
-3	Authentication	Invalid username/password or login token
-4	User Already Exists	Username already exists
-5	Permission Denied	Account lacks required permissions
-6	Unregistered	Device or account is unregistered
-7	Not Ready	Temporary not-ready state; retry later
-8	Invalid API Key	Invalid, missing, or disabled API key
-9	Throttling	Rate limit exceeded - slow down requests
-10	Clock Mismatch	Clock mismatch in request timestamp
-11	Data Error	Request data is incorrect
-12	Unknown Account	A requested user/account could not be found, or the session is no longer valid
-99	Unknown Request	Unknown or unsupported request

Always check the status field in responses, even when HTTP status is 200.

🎯 Best Practices

Rate Limiting & Performance

Don’t poll aggressively! Use Webhooks for real-time updates instead.

Reasonable Polling: If polling is necessary, use 30-60 second intervals minimum
Batch Operations: Use batch endpoints (e.g., create multiple jobs at once) when possible
Webhooks: Subscribe to webhooks for instant notifications about job, clock, check-in/out, and alert events.
Pagination: Use the sort parameter with limit and skip for large datasets

Error Handling

Implement robust error handling:

try {
  const response = await fetch('https://api.hellotracks.com/api/getjobs', {
    method: 'POST',
    headers: {
      'API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ data: { day: 20251008, worker: '*' } })
  });
  
  const result = await response.json();
  
  if (result.status !== 0) {
    // Handle application error
    console.error('API Error:', result.status, result.errorMsg);
  } else {
    // Success - process result
    console.log('Jobs:', result.jobs);
  }
} catch (error) {
  // Handle network/HTTP error
  console.error('Network error:', error);
}

Date Formats

Day Format: YYYYMMDD integer (e.g., 20251008 for October 8, 2025)
Timestamps: Unix timestamps in milliseconds (e.g., 1619568000000)
Time Windows: HHMM format (e.g., 1430 for 2:30 PM)

Timezone Handling

All date/time values are interpreted in the account’s configured timezone. Make sure your account timezone matches your operational timezone in the Hellotracks web app.

🔗 Common Workflows

Create and Assign Jobs

Create jobs with location and details
Optional: Auto-assign to optimize worker allocation
Optional: Optimize route for each worker
Workers receive notifications on their mobile apps

Track Job Progress

Get jobs for a specific day/worker
Check status timestamps (tsAccepted, tsCheckIn, tsDoneSuccess, etc.)
Or use Webhooks for real-time updates

Generate Reports

Create report with desired type and date range
Specify a format supported by the selected report type (for example xlsx, csv, pdf, geojson, or zip)
Download binary response and save as file

📖 Key Resources

Job Object Reference

Complete field reference for Job objects (50+ fields)

Member Object Reference

Complete field reference for Member/Account objects

Webhooks

Real-time notifications for events

Authentication Details

Comprehensive authentication guide

💡 Need Help?

Email Support: api@hellotracks.com
Feature Requests: Contact us to discuss your integration needs
Bug Reports: Email us with request/response details

🔄 API Versioning

The current API version is 2. There is no version to send: requests always use the current version. We maintain backward compatibility and will announce breaking changes well in advance.

Ready to build? Start with Authentication, then pick an endpoint from the menu.

​🚀 Quick Start

​1. Get Your API Key

​2. Make Your First Request

​3. Explore Common Use Cases

Job Management

Route Optimization

Location Tracking

Reports

​🔐 Authentication

​📡 API Basics

​Base URL

​Request Format

​Response Format

​The API is Stateless

​✅ Status Codes

​HTTP Status Codes

​Application Status Codes

​🎯 Best Practices

​Rate Limiting & Performance

​Error Handling

​Date Formats

​Timezone Handling

​🔗 Common Workflows

​Create and Assign Jobs

​Track Job Progress

​Generate Reports

​📖 Key Resources

Job Object Reference

Member Object Reference

Webhooks

Authentication Details

​💡 Need Help?

​🔄 API Versioning

🚀 Quick Start

1. Get Your API Key

2. Make Your First Request

3. Explore Common Use Cases

🔐 Authentication

📡 API Basics

Base URL

Request Format

Response Format

The API is Stateless

✅ Status Codes

HTTP Status Codes

Application Status Codes

🎯 Best Practices

Rate Limiting & Performance

Error Handling

Date Formats

Timezone Handling

🔗 Common Workflows

Create and Assign Jobs

Track Job Progress

Generate Reports

📖 Key Resources

💡 Need Help?

🔄 API Versioning