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

# JSON API overview

> The Hellotracks JSON API: POST requests to /api with a JSON body. Build an integration in code, one JSON request per action.

> [!NOTE]
>
> **Last Updated:** June 29, 2026
> **Current API Version:** 2\
> **Questions?** Contact [api@hellotracks.com](mailto: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.

> [!NOTE]
>
> Building a tool or automation on plain REST resources? See the [REST API](https://api-docs.hellotracks.com/v1/overview.md). Working from a terminal or with an AI agent? See the [CLI](https://api-docs.hellotracks.com/cli/overview.md).

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

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

> [card] [Job Management](https://api-docs.hellotracks.com/api-reference/endpoint/createjobs.md)
>
> Create, assign, and track jobs for your field workers

> [card] [Route Optimization](https://api-docs.hellotracks.com/api-reference/endpoint/routeoptimization.md)
>
> Optimize routes to minimize travel time and distance

> [card] [Location Tracking](https://api-docs.hellotracks.com/api-reference/endpoint/gettracks.md)
>
> Retrieve real-time and historical location data

> [card] [Reports](https://api-docs.hellotracks.com/api-reference/endpoint/createreport.md)
>
> Generate comprehensive reports (jobs, mileage, timesheet, etc.)

## 🔐 Authentication

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

```bash theme={null}
--header 'API-Key: YOUR_KEY_ID.YOUR_SECRET'
```

See the [Authentication](https://api-docs.hellotracks.com/api-reference/authentication.md) 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": {
    "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.

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

> [!TIP]
>
> Always check the `status` field in responses, even when HTTP status is 200.

## 🎯 Best Practices

### Rate Limiting & Performance

> [!WARNING]
>
> **Don't poll aggressively!** Use [Webhooks](https://api-docs.hellotracks.com/api-reference/webhooks.md) 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:

```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, 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

1. [Create jobs](https://api-docs.hellotracks.com/api-reference/endpoint/createjobs.md) with location and details
2. Optional: [Auto-assign](https://api-docs.hellotracks.com/api-reference/endpoint/autoassign.md) to optimize worker allocation
3. Optional: [Optimize route](https://api-docs.hellotracks.com/api-reference/endpoint/routeoptimization.md) for each worker
4. Workers receive notifications on their mobile apps

### Track Job Progress

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

### Generate Reports

1. [Create report](https://api-docs.hellotracks.com/api-reference/endpoint/createreport.md) 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

> [card] [Job Object Reference](https://api-docs.hellotracks.com/api-reference/job-object.md)
>
> Complete field reference for Job objects (50+ fields)

> [card] [Member Object Reference](https://api-docs.hellotracks.com/api-reference/member-object.md)
>
> Complete field reference for Member/Account objects

> [card] [Webhooks](https://api-docs.hellotracks.com/api-reference/webhooks.md)
>
> Real-time notifications for events

> [card] [Authentication Details](https://api-docs.hellotracks.com/api-reference/authentication.md)
>
> Comprehensive authentication guide

## 💡 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**. There is no version to send: requests always use the current version. We maintain backward compatibility and will announce breaking changes well in advance.

***

> [!NOTE]
>
> Ready to build? Start with [Authentication](https://api-docs.hellotracks.com/api-reference/authentication.md), then pick an endpoint from the menu.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.