> ## 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 may return an `error` object. Treat `error.message` as the user-facing failure reason.

```json theme={null}
{
  "error": {
    "message": "Invalid Hellotracks API key."
  }
}
```

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. |
| `429`  | Rate limit reached.                                     |
| `500`  | Hellotracks API is temporarily unavailable.             |

## 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 or deleted jobs. 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`                                                                |