Skip to main content
Last Updated: October 8, 2025
Current API Version: 2
Questions? Contact api@hellotracks.com
Welcome to the Hellotracks API documentation! This API enables you to integrate Hellotracks’ powerful fleet management, job dispatch, and location tracking capabilities into your applications.

πŸ“š Documentation Structure

This documentation is organized into two main sections:

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

  1. Log in to https://live.hellotracks.com
  2. Navigate to More β†’ API & Integrations
  3. Enable APIs in the API section
  4. 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 the POST method with JSON payloads:
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

πŸ” Authentication

Every API request requires authentication via the API-Key header:
--header 'API-Key: ABCDEF.ABCDEFGHIJKLMNOPQRSTUVWXYZ123456'
See the Authentication page for complete details.

πŸ“‘ API Basics

Base URL

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

Request Format

All requests use POST method with JSON body:
{
  "data": {
    // Endpoint-specific parameters go here
  },
  "ver": 2  // Optional, defaults to 2 (current version)
}

Response Format

All responses return JSON with a status field:
{
  "status": 0,  // 0 = success, non-zero = error
  // Additional response data here
}

The API is Stateless

Each request is independent. No session management is required.

βœ… Status Codes

HTTP Status Codes

CodeTypeDescription
200OKRequest successfully processed
500, 502, 503Server ErrorTemporary server issues - retry with backoff
504TimeoutRequest took too long - try reducing data size

Application Status Codes

The status field in the response indicates operation success:
StatusMeaningDescription
0SuccessRequest completed successfully
1AuthenticationInvalid or missing API key
2Permission DeniedAccount lacks required permissions
3Data ErrorInvalid or malformed request data
4Not FoundRequested resource doesn’t exist
5ThrottlingRate 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 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 } })
  });
  
  const result = await response.json();
  
  if (result.status !== 0) {
    // Handle application error
    console.error('API Error:', result.status, result.error);
  } 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

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

Track Job Progress

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

Generate Reports

  1. Create report with desired type and date range
  2. Specify format (xlsx, csv, pdf, geojson, zip)
  3. Download binary response and save as file

πŸ“– Key Resources

πŸ’‘ 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:
{
  "data": { /* ... */ },
  "ver": 2
}
If omitted, 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!
⌘I