Introduction

​

📚 Documentation Structure

​

API Reference Sections

• 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

​

2. Make Your First Request

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

--header 'API-Key: ABCDEF.ABCDEFGHIJKLMNOPQRSTUVWXYZ123456'

​

📡 API Basics

​

Base URL

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

​

Request Format

{
  "data": {
    // Endpoint-specific parameters go here
  },
  "ver": 2  // Optional, defaults to 2 (current version)
}

​

Response Format

{
  "status": 0,  // 0 = success, non-zero = error
  // Additional response data here
}

​

The API is Stateless

​

✅ Status Codes

​

HTTP Status Codes

​

Application Status Codes

​

🎯 Best Practices

​

Rate Limiting & Performance

• 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

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

​

🔗 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

{
  "data": { /* ... */ },
  "ver": 2
}