> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.hellotracks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Welcome to the Hellotracks API - Build powerful fleet management and job dispatch solutions

<Note>
  **Last Updated:** June 29, 2026
  **Current API Version:** 2\
  **Questions?** Contact [api@hellotracks.com](mailto:api@hellotracks.com)
</Note>

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:

<CardGroup cols={2}>
  <Card title="Get Started" icon="rocket" href="#quick-start">
    You're here! Learn the basics, authentication, and common patterns.
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/authentication">
    Detailed endpoint documentation organized by feature area.
  </Card>
</CardGroup>

### 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 across jobs, members, places, mileage, timesheets, and more

## 🚀 Quick Start

### 1. Get Your API Key

1. Log in to [https://live.hellotracks.com](https://live.hellotracks.com)
2. Navigate to **More** → **API & Integrations**
3. Enable APIs in the API section
4. Copy your API key

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

### 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`.

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Job Management" icon="briefcase" href="/api-reference/endpoint/createjobs">
    Create, assign, and track jobs for your field workers
  </Card>

  <Card title="Route Optimization" icon="route" href="/api-reference/endpoint/routeoptimization">
    Optimize routes to minimize travel time and distance
  </Card>

  <Card title="Location Tracking" icon="location-dot" href="/api-reference/endpoint/gettracks">
    Retrieve real-time and historical location data
  </Card>

  <Card title="Reports" icon="chart-line" href="/api-reference/endpoint/createreport">
    Generate comprehensive reports (jobs, mileage, timesheet, etc.)
  </Card>
</CardGroup>

## 🔐 Authentication

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

```bash theme={null}
--header 'API-Key: ABCDEF.ABCDEFGHIJKLMNOPQRSTUVWXYZ123456'
```

See the [Authentication](/api-reference/authentication) page for complete details.

## 📡 API Basics

### Base URL

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

### Request Format

`/api` requests use **POST** with a JSON body:

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

### Response Format

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

```json theme={null}
{
  "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

| 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        | Requested user/account could not be found |
| -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    | Force Logout        | Session is no longer valid                |
| -99    | Unknown Request     | Unknown or unsupported request            |

<Tip>
  Always check the `status` field in responses, even when HTTP status is 200.
</Tip>

## 🎯 Best Practices

### Rate Limiting & Performance

<Warning>
  **Don't poll aggressively!** Use [Webhooks](/api-reference/webhooks) for real-time updates instead.
</Warning>

* **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:

```javascript theme={null}
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](/api-reference/endpoint/createjobs) with location and details
2. Optional: [Auto-assign](/api-reference/endpoint/autoassign) to optimize worker allocation
3. Optional: [Optimize route](/api-reference/endpoint/routeoptimization) for each worker
4. Workers receive notifications on their mobile apps

### Track Job Progress

1. [Get jobs](/api-reference/endpoint/getjobs) for a specific day/worker
2. Check status timestamps (`tsAccepted`, `tsCheckIn`, `tsDoneSuccess`, etc.)
3. Or use [Webhooks](/api-reference/webhooks) for real-time updates

### Generate Reports

1. [Create report](/api-reference/endpoint/createreport) with desired type and date range
2. Specify a format supported by the selected report type (for example xlsx, csv, pdf, geojson, or zip)
3. Download binary response and save as file

## 📖 Key Resources

<CardGroup cols={2}>
  <Card title="Job Object Reference" icon="clipboard-list" href="/api-reference/job-object">
    Complete field reference for Job objects (50+ fields)
  </Card>

  <Card title="Member Object Reference" icon="user" href="/api-reference/member-object">
    Complete field reference for Member/Account objects
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks">
    Real-time notifications for events
  </Card>

  <Card title="Authentication Details" icon="key" href="/api-reference/authentication">
    Comprehensive authentication guide
  </Card>
</CardGroup>

## 💡 Need Help?

* **Email Support:** [api@hellotracks.com](mailto: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:

```json theme={null}
{
  "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.

***

<Note>
  Ready to build? Head to the [API Reference](/api-reference/authentication) tab to explore all available endpoints!
</Note>