Helix Field API

Getting started

Every request goes to the base URL above, followed by the endpoint's path. The version is part of the path, so a request to /api/public/v1/me always gets version 1.

Get an API key

1. An admin of the company signs in to the Helix Field office app and opens Settings > Integrations.
2. Under Make a key for, pick Zapier or Your own software and press Make key.
3. Copy the key straight away. It is shown once and never again; Helix Field keeps only a fingerprint of it, so a lost key cannot be looked up. Revoke it and make another.

A key belongs to the company, not to a person, and everything it creates is recorded against the key. Keys start with hf_live_. A company can have up to ten keys that are not revoked. The Integrations screen lists each key by its first characters, the day it was made and the day it was last used, and an admin can revoke any of them there. A revoked key stops working at once, and the webhook subscriptions it made are turned off with it.

Make a first call

GET /me answers with the company the key belongs to. It is the call to make to check a key.

curl https://app.helixfielddispatch.com/api/public/v1/me \
  -H "Authorization: Bearer $HELIX_API_KEY"

{
  "company": "Helix Field Demo",
  "company_id": "55cc855f-ba9d-482c-bd91-9840b36e753c",
  "key_name": "Your own software",
  "api_version": "v1",
  "events": ["booking.received", "customer.created", "invoice.paid", "job.completed", "job.created"]
}

Authentication

Send the key in one of these two headers on every request:

• Authorization: Bearer hf_live_...
• X-API-Key: hf_live_..., for clients that cannot set the first one

A key in the URL is not read. A request that carries its key only in the query string is answered 401, which keeps keys out of server logs and browser history.

A missing key, a key that does not start with hf_live_, an unknown key and a revoked key all get the same answer, so the response never says which of these it was:

HTTP/1.1 401 Unauthorized
{"detail": "A valid API key is required"}

When the company's Helix Field account is locked (its subscription was canceled or stayed unpaid past the grace period, or the account was closed), every request with its key is answered 402, as the office app is:

HTTP/1.1 402 Payment Required
{"detail": "This company's Helix account is not active"}

Requests and responses

• Bodies are JSON. Send Content-Type: application/json with a body. Fields this page does not list are ignored.
• Ids are UUID strings, such as "6505eb45-3350-4c08-b6ee-45f2d2cc4319".
• Times are ISO 8601, written without an offset and to the second, such as "2026-10-16T07:52:08". When something happened (created_at, completed_at, occurred_at) is in UTC; created_at on a webhook subscription also carries fractions of a second. A job's scheduled_date is the company's own clock time as it was booked, and an invoice's issued_date and due_date are days on the company's calendar, written at midnight.
• Money is a string with two decimals, such as "185.00", so no amount passes through a floating point number.
• Fields with no value are present and null; lists with nothing in them are [].

Lists

Every list endpoint returns a JSON array, newest first by the time the record was created. limit sets how many come back: 25 when it is left out, at most 100. A number below 1 is read as 1 and a number above 100 as 100; a value that is not a whole number is a 422.

There are no pages and no cursor: a list returns the newest records up to limit. A list never includes records the company has removed.

Errors

An error is a status code and a JSON body with a detail; a 429 is the one exception (see Rate limits). Most details are one sentence written to be shown to a person:

{"detail": "Customer not found"}

When the request itself is malformed (a required field is missing, a field is too long or of the wrong type, or the body is not valid JSON), detail is a list instead, one entry per problem. loc says where the problem is; the value that was sent is never echoed back.

{"detail": [
  {"type": "missing", "loc": ["body", "first_name"], "msg": "Field required"}
]}

Rate limits

The endpoints that write have a limit per minute, counted per calling IP address:

The other endpoints have no limit of their own. A request over the limit is answered 429 with this body, and nothing is saved:

{"error": "Rate limit exceeded: 60 per 1 minute"}

No Retry-After header is sent. Wait for the minute to pass and send the request again.

Endpoints

Paths are relative to https://app.helixfielddispatch.com/api/public/v1.

The company and key making the request. Use it to test a key.

The example is under Getting started.

Every webhook event with the sentence the office app shows for it.

[
  {"event": "booking.received", "description": "A booking request arrived from the online form."},
  {"event": "customer.created", "description": "A customer was added."},
  {"event": "invoice.paid", "description": "An invoice was paid in full."},
  {"event": "job.completed", "description": "A job was completed by the crew."},
  {"event": "job.created", "description": "A job was created."}
]

The company's customers, newest first, as customer objects.

curl "https://app.helixfielddispatch.com/api/public/v1/customers?email=dana.reyes@example.com" \
  -H "Authorization: Bearer $HELIX_API_KEY"

[
  {
    "id": "6505eb45-3350-4c08-b6ee-45f2d2cc4319",
    "name": "Dana Reyes",
    "first_name": "Dana",
    "last_name": "Reyes",
    "company_name": null,
    "email": "dana.reyes@example.com",
    "phone": "405-555-0134",
    "customer_type": "commercial",
    "tags": ["Spring campaign"],
    "created_at": "2026-10-16T07:52:08"
  }
]

Adds a customer and answers 201 with the new customer object. A customer.created webhook is sent for it.

curl https://app.helixfielddispatch.com/api/public/v1/customers \
  -H "Authorization: Bearer $HELIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Dana", "last_name": "Reyes", "email": "Dana.Reyes@example.com",
       "phone": "405-555-0134", "customer_type": "commercial", "tags": ["Spring campaign"]}'

{
  "id": "6505eb45-3350-4c08-b6ee-45f2d2cc4319",
  "name": "Dana Reyes",
  "first_name": "Dana",
  "last_name": "Reyes",
  "company_name": null,
  "email": "dana.reyes@example.com",
  "phone": "405-555-0134",
  "customer_type": "commercial",
  "tags": ["Spring campaign"],
  "created_at": "2026-10-16T07:52:08"
}

Replaces the customer's tags with the list sent and answers 200 with the customer object. A tag left out of the list comes off the customer, an empty list removes every tag, and a name the company does not have yet is created. No webhook is sent.

A customer_id that is not one of the company's customers, or belongs to a removed customer, is answered 404 with "Customer not found".

curl -X PUT https://app.helixfielddispatch.com/api/public/v1/customers/6505eb45-3350-4c08-b6ee-45f2d2cc4319/tags \
  -H "Authorization: Bearer $HELIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["Net 30", "VIP"]}'

The company's jobs, newest first, as job objects.

curl "https://app.helixfielddispatch.com/api/public/v1/jobs?status_filter=completed&limit=10" \
  -H "Authorization: Bearer $HELIX_API_KEY"

Creates a job for an existing customer and answers 201 with the new job object. The job's status is scheduled; without a scheduled_date it has no date, and the office books it from Helix Field. A job.created webhook is sent for it. At a company with a single active user, the job is assigned to that person, the same as a job made in the office app, unless the company has turned that off in its Job Settings.

curl https://app.helixfielddispatch.com/api/public/v1/jobs \
  -H "Authorization: Bearer $HELIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "6505eb45-3350-4c08-b6ee-45f2d2cc4319", "title": "Spring opening",
       "job_type": "maintenance", "scheduled_date": "2026-10-20T09:00:00", "description": "Open the pond"}'

{
  "id": "6e704563-572e-4fc0-8826-fc5140892025",
  "job_number": "JOB-AA107B31",
  "title": "Spring opening",
  "status": "scheduled",
  "job_type": "maintenance",
  "service_id": null,
  "service_name": null,
  "customer_id": "6505eb45-3350-4c08-b6ee-45f2d2cc4319",
  "customer_name": "Dana Reyes",
  "property_id": "4bf224ef-3402-4fec-97d8-628fc57245fc",
  "scheduled_date": "2026-10-20T09:00:00",
  "scheduled_start_time": null,
  "completed_at": null
}

The company's invoices, newest first, as invoice objects.

[
  {
    "id": "6c01eb96-503e-4e40-b0ec-c588505b5f97",
    "invoice_number": "INV-1001",
    "status": "draft",
    "customer_id": "6505eb45-3350-4c08-b6ee-45f2d2cc4319",
    "customer_name": "Dana Reyes",
    "job_id": null,
    "total": "185.00",
    "paid_amount": "0.00",
    "paid_date": null,
    "issued_date": "2026-10-16T00:00:00",
    "due_date": "2026-11-15T00:00:00"
  }
]

Booking requests sent through the company's online booking form, newest first, as booking request objects. Takes limit: 25 by default, 1 to 100. Every request is listed whether the office has accepted it, declined it, marked it as spam or not answered it yet; the object does not say which.

The company's webhook subscriptions that are switched on, oldest first, made through any of its keys, as subscription objects. secret is always null here.

Subscribes a URL to one event and answers 201 with the subscription, including its secret. The secret signs every delivery; it is in this answer and nowhere else, so keep it. Each call makes a new subscription, so the same URL subscribed twice receives every delivery twice.

curl https://app.helixfielddispatch.com/api/public/v1/hooks \
  -H "Authorization: Bearer $HELIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "job.created", "target_url": "https://hooks.example.com/helix/jobs"}'

{
  "id": "0cc1e630-f74f-43de-b15c-47b4db15e5a2",
  "event": "job.created",
  "target_url": "https://hooks.example.com/helix/jobs",
  "secret": "your-signing-secret-shown-only-here",
  "created_at": "2026-10-16T07:52:40.330158"
}

Removes the subscription for good and answers 204 with no body. Nothing more is sent to it, including retries that were still owed. The answer is 204 as well when the subscription was already removed or the id is unknown, so an unsubscribe can be repeated safely.

curl -X DELETE https://app.helixfielddispatch.com/api/public/v1/hooks/0cc1e630-f74f-43de-b15c-47b4db15e5a2 \
  -H "Authorization: Bearer $HELIX_API_KEY"

Objects

The list endpoints, the create endpoints and the data of a webhook all use these shapes.

Customer

Job

Invoice

Booking request

Webhook subscription

Webhooks

Subscribe a URL with POST /hooks and Helix Field posts to it each time the event happens, in the ways the table below lists. The office can see every subscription under Settings > Integrations, with when it last sent, and can remove one there.

Events

Delivery

Each delivery is an HTTPS POST to the subscription's target_url with a JSON body:

{"data":{"company_name":null,"created_at":"2026-10-16T07:52:08","customer_type":"commercial","email":"dana.reyes@example.com","first_name":"Dana","id":"6505eb45-3350-4c08-b6ee-45f2d2cc4319","last_name":"Reyes","name":"Dana Reyes","phone":"405-555-0134","tags":["Spring campaign"]},"event":"customer.created","occurred_at":"2026-10-16T07:52:08"}

The body is compact JSON with its keys in alphabetical order. It comes with these headers:

A delivery counts as received when the URL answers with any 2xx status within 10 seconds. Redirects are not followed, so a 3xx answer counts as a failure.

Verifying a signature

The signature is an HMAC SHA256 of the exact bytes of the body, keyed with the subscription's secret. Compute it over the raw body as received, before parsing it, and compare it with the header in constant time. A delivery whose signature does not match did not come from Helix Field.

import hashlib
import hmac


def is_from_helix(secret: str, body: bytes, signature_header: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode("utf-8"), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

const crypto = require("crypto");

function isFromHelix(secret, rawBody, signatureHeader) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader || "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Retries and turning off

• The first attempt is made as soon as the change that caused the event is saved.
• A failed delivery is tried again, up to five attempts in all. The waits after each failure are at least 5 minutes, 30 minutes, 2 hours and 8 hours. Retries are sent by a pass that runs once an hour, so a retry goes out on the first pass after its wait, up to about an hour later. After the fifth failed attempt that delivery is given up.
• A URL that answers 410 Gone is asking not to be called again: its subscription is turned off at once.
• A subscription whose deliveries fail 25 times in a row is turned off. Any delivery that succeeds sets the count back to zero.
• A subscription is also turned off when the key that made it is revoked.
• While a company's Helix Field account is locked, its owed retries are given up rather than kept.

A subscription that is turned off receives nothing more and no longer appears in GET /hooks. It is not turned back on; subscribe again with POST /hooks.