Last Updated: October 8, 2025
Current API Version: 2
Questions? Contact api@hellotracks.com
Current API Version: 2
Questions? Contact api@hellotracks.com
π Documentation Structure
This documentation is organized into two main sections:Get Started
Youβre here! Learn the basics, authentication, and common patterns.
API Reference
Detailed endpoint documentation organized by feature area.
API Reference Sections
The API Reference tab contains detailed documentation organized into these categories:- API Documentation - Authentication, data objects (Job, Member), webhooks
- Job Management - Create, read, update, delete, archive jobs
- Dispatch & Routing - Auto-assign, distribute, optimize routes
- Location - Track and retrieve location data
- Account Management - Manage team members and users
- Place Management - Manage locations and places
- Reports - Generate comprehensive reports (17 types available)
π 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
All API requests use thePOST
method with JSON payloads:
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 theAPI-Key
header:
π‘ API Basics
Base URL
Request Format
All requests use POST method with JSON body:Response Format
All responses return JSON with astatus
field:
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
Thestatus
field in the response indicates operation success:
Status | Meaning | Description |
---|---|---|
0 | Success | Request completed successfully |
1 | Authentication | Invalid or missing API key |
2 | Permission Denied | Account lacks required permissions |
3 | Data Error | Invalid or malformed request data |
4 | Not Found | Requested resource doesnβt exist |
5 | Throttling | Rate limit exceeded - slow down requests |
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 updates, location changes, etc.
- Pagination: Use the
sort
parameter withlimit
andskip
for large datasets
Error Handling
Implement robust error handling: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 format (xlsx, csv, pdf, geojson, 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. You can specify the version in your request:ver
defaults to the latest version (currently 2). We maintain backward compatibility and will announce breaking changes well in advance.
Ready to build? Head to the API Reference tab to explore all available endpoints!