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

# No-code connectors

> Use the Hellotracks REST API with Zapier, Make, n8n, and other no-code automation tools.

Hellotracks no-code connectors use a REST API under `/v1`. This API is designed for automation tools such as Zapier, Make, and n8n.

No-code endpoints use REST methods, query strings for filters, and JSON request bodies for create and update actions.

## Base URL

```http theme={null}
https://api.hellotracks.com/v1
```

Use the production base URL above for public Zapier, Make, and n8n workflows.

## Authentication

Create an API key in Hellotracks under **More -> API & Integrations**. Send the key in the `API-Key` header.

```bash theme={null}
curl "https://api.hellotracks.com/v1/auth/whoami" \
  --header "API-Key: YOUR_API_KEY" \
  --header "Accept: application/json"
```

All connector requests use JSON and include:

```http theme={null}
API-Key: YOUR_API_KEY
Accept: application/json
Content-Type: application/json
```

## Response Format

List and action responses return a `data` object. Most connector endpoints return an `items` array inside `data`.

```json theme={null}
{
  "data": {
    "items": [
      {
        "id": "69fdc0f846455e452430b4b5",
        "externalId": "SRP-4828",
        "title": "Emergency Exit Lighting Inspection",
        "progress": "scheduled"
      }
    ]
  }
}
```

Connector packages unwrap `data.items` before returning records to Zapier, Make, or n8n.

## Error Format

Failed requests return an `error` object. Use `error.code` to handle the failure in code and show `error.message` to people. `meta` echoes the request path and method.

```json theme={null}
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid Hellotracks API key."
  },
  "meta": {
    "path": "/v1/jobs",
    "method": "GET"
  }
}
```

Error codes include `invalid_request`, `invalid_format`, `invalid_data`, `invalid_api_key`, `forbidden`, `not_found`, `already_exists`, `throttled`, `not_ready` and `unknown_error`.

Common HTTP statuses:

| Status | Meaning |
| - | - |
| `400` | Invalid request data. |
| `401` | Missing or invalid API key. |
| `403` | API key does not have access to the requested resource. |
| `404` | Unknown route or resource. |
| `409` | The record already exists. |
| `429` | Rate limit reached. |
| `500` | Hellotracks API is temporarily unavailable. |
| `503` | Not ready yet; retry later. |

## Authentication Test

Use this endpoint to validate that an API key works.

```http theme={null}
GET /auth/whoami
```

Example:

```bash theme={null}
curl "https://api.hellotracks.com/v1/auth/whoami" \
  --header "API-Key: YOUR_API_KEY"
```

## Jobs

### Watch or list jobs

Use `GET /jobs` for polling triggers, job dropdowns, and lookup flows.

```http theme={null}
GET /jobs
```

Query parameters:

| Parameter | Type | Description |
| - | - | - |
| `createdSince` | timestamp in milliseconds | Return jobs created since this timestamp. Used by "New Job" polling triggers. |
| `updatedSince` | timestamp in milliseconds | Return jobs changed since this timestamp. Used by "Updated Job" and completed-job polling triggers. |
| `progress` | string | Optional progress filter, for example `scheduled`, `success`, or `failed`. |
| `includeArchived` | boolean | Include archived jobs. Deleted jobs are never returned. Connectors usually send `true` for lookups and polling. |
| `limit` | number | Maximum number of jobs to return. Zapier uses `100` for polling and `1` for exact lookup. |
| `skip` | number | Offset for pagination. |
| `externalId` | string | Find a job by external dedupe ID. |
| `assigneeUsername` | string | Filter jobs assigned to a member username. |

Examples:

```bash theme={null}
curl "https://api.hellotracks.com/v1/jobs?updatedSince=0&includeArchived=true&limit=100" \
  --header "API-Key: YOUR_API_KEY"
```

```bash theme={null}
curl "https://api.hellotracks.com/v1/jobs?externalId=SRP-4828&includeArchived=true&limit=1" \
  --header "API-Key: YOUR_API_KEY"
```

### Get a job

Use `GET /jobs/{id}` when you already have the Hellotracks job ID.

```http theme={null}
GET /jobs/{id}
```

Example:

```bash theme={null}
curl "https://api.hellotracks.com/v1/jobs/69fdc0f846455e452430b4b5" \
  --header "API-Key: YOUR_API_KEY"
```

### Create a job

Use `POST /jobs` to create a job. If `externalId` matches an existing job, Hellotracks uses it as a stable dedupe key and may update the existing job.

```http theme={null}
POST /jobs
```

Request body:

```json theme={null}
{
  "externalId": "SRP-4828",
  "title": "Emergency Exit Lighting Inspection",
  "address": "South Road, San Francisco, CA",
  "notes": "Inspect emergency lighting after reported outage.",
  "date": "2026-05-10",
  "assigneeUsername": "worker@example.com",
  "priority": 7,
  "contact": {
    "name": "Olivia Martinez",
    "phone": "+14155556789",
    "email": "olivia@example.com"
  },
  "timeWindow": {
    "start": "09:00",
    "end": "17:00"
  }
}
```

Supported connector fields:

| Field | Type | Description |
| - | - | - |
| `externalId` | string | Stable ID from the source app. Use this for dedupe and later lookups. |
| `title` | string | Job title. Required by the public connectors when creating a job. |
| `address` | string | Human-readable job address. Preferred for no-code connectors. |
| `notes` | string | Job notes or instructions. |
| `date` | string | Job date in `YYYY-MM-DD` format. |
| `assigneeUsername` | string | Hellotracks member username, often the member email or login name. |
| `priority` | integer | Optional priority from `0` to `10`. |
| `contact.name` | string | Contact name. |
| `contact.phone` | string | Contact phone. |
| `contact.email` | string | Contact email. |
| `timeWindow.start` | string | Start time in `HH:mm` format. |
| `timeWindow.end` | string | End time in `HH:mm` format. |
| `placeId` | string | Optional advanced field for existing Hellotracks places. Prefer `address` in no-code workflows unless you already have a valid place ID. |

### Update a job

Use `PATCH /jobs` to update an existing job. Send the Hellotracks job `id` in the JSON body and include only the fields you want to change.

```http theme={null}
PATCH /jobs
```

Request body:

```json theme={null}
{
  "id": "69fdc0f846455e452430b4b5",
  "title": "Emergency Exit Lighting Inspection - Updated",
  "notes": "Bring a replacement battery pack.",
  "assigneeUsername": "worker@example.com"
}
```

### Archive a job

Use archive when the job should no longer appear in active schedules but should remain recoverable in Hellotracks.

```http theme={null}
POST /jobs/{id}/archive
```

Example:

```bash theme={null}
curl -X POST "https://api.hellotracks.com/v1/jobs/69fdc0f846455e452430b4b5/archive" \
  --header "API-Key: YOUR_API_KEY"
```

### Delete a job

Use delete only for disposable or intentionally removed jobs.

```http theme={null}
DELETE /jobs/{id}
```

Example:

```bash theme={null}
curl -X DELETE "https://api.hellotracks.com/v1/jobs/69fdc0f846455e452430b4b5" \
  --header "API-Key: YOUR_API_KEY"
```

## Job Object

Connector responses include stable job fields.

```json theme={null}
{
  "id": "69fdc0f846455e452430b4b5",
  "externalId": "SRP-4828",
  "title": "Emergency Exit Lighting Inspection",
  "address": "South Road, San Francisco, CA",
  "date": "2026-05-10",
  "progress": "scheduled",
  "createdAt": 1777540000000,
  "updatedAt": 1777540060000,
  "assignee": {
    "id": "ce2fg4",
    "username": "worker@example.com",
    "email": "worker@example.com",
    "name": "Worker Name"
  },
  "contact": {
    "name": "Olivia Martinez",
    "phone": "+14155556789",
    "email": "olivia@example.com"
  }
}
```

## Members

Use members for assignment lookups, dropdowns, and exact-match searches.

```http theme={null}
GET /members
```

Query parameters:

| Parameter | Type | Description |
| - | - | - |
| `query` | string | Search text. Can be an email, username, name, or UID. |
| `max` | number | Maximum number of members to return. Connectors use `50`. |

Example:

```bash theme={null}
curl "https://api.hellotracks.com/v1/members?query=worker%40example.com&max=50" \
  --header "API-Key: YOUR_API_KEY"
```

Member response fields:

| Field | Type | Description |
| - | - | - |
| `id` | string | Hellotracks member UID. |
| `username` | string | Member username. |
| `email` | string | Member email address. |
| `name` | string | Member display name. |

## Connector Behavior

Zapier, Make, and n8n use the same production `/v1` contract:

| Connector capability | API request |
| - | - |
| Validate connection | `GET /auth/whoami` |
| New Job trigger | `GET /jobs?createdSince=...&includeArchived=true&limit=100` |
| Updated Job trigger | `GET /jobs?updatedSince=...&includeArchived=true&limit=100` |
| Completed Job trigger | `GET /jobs?updatedSince=...&includeArchived=true&limit=100`, filtered to `progress: "success"` |
| Create Job action | `POST /jobs` |
| Update Job action | `PATCH /jobs` with `id` in the JSON body |
| Archive Job action | `POST /jobs/{id}/archive` |
| Delete Job action | `DELETE /jobs/{id}` |
| Find Job search | `GET /jobs?externalId=...&includeArchived=true&limit=1` |
| Find Member search | `GET /members?query=...&max=50` |


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