Developers

Turf52 API and webhooks

Read and add your company's data from your website or another tool, and get a message the moment something happens. Owners make keys and webhooks in Settings > Developers.

Keys

Send your key in the Authorization header. Keys start with t52_, belong to one company, and only do what was ticked when they were made. 120 requests a minute per key.

curl https://turf52.com/api/v1/customers?limit=10 \
  -H "Authorization: Bearer t52_your_key_here"

Endpoints

CallScopeWhat
GET /api/v1/meany keyThe company this key belongs to and its scopes
GET /api/v1/customerscustomers:readCustomers with contacts. Filters: status, updated_since
GET /api/v1/customers/{id}customers:readOne customer with contacts and properties
POST /api/v1/customerscustomers:writeAdd a customer (lead or active) with a contact and a property
GET /api/v1/propertiescustomers:readProperties. Filters: customer_id, updated_since
GET /api/v1/properties/{id}customers:readOne property
POST /api/v1/requestsrequests:writeA service request from your website; it becomes a lead
GET /api/v1/visitsvisits:readVisits. Filters: date_from, date_to, status, crew_id, customer_id, updated_since
GET /api/v1/visits/{id}visits:readOne visit
GET /api/v1/invoicesinvoices:readInvoices with lines. Filters: status, customer_id, updated_since
GET /api/v1/invoices/{id}invoices:readOne invoice
GET /api/v1/paymentspayments:readPayments and the invoices they paid. Filters: customer_id, created_since

Add a customer:

curl https://turf52.com/api/v1/customers \
  -H "Authorization: Bearer t52_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jamie Rivera",
    "status": "lead",
    "contact": { "email": "[email protected]", "phone": "913-555-0100" },
    "property": { "line1": "1200 Elm St", "city": "Olathe", "state": "KS", "postal_code": "66061" }
  }'

Send in a request from your website's own form:

POST /api/v1/requests
{
  "name": "Jamie Rivera",
  "email": "[email protected]",
  "address": { "line1": "1200 Elm St", "city": "Olathe", "state": "KS" },
  "services_wanted": ["Core aeration"],
  "message": "Front and back yard"
}

Money is in cents (total_cents: 4500 is $45.00). Times are ISO 8601 in UTC; visit dates are calendar days in the company's time zone. Gate codes and access notes aren't in the API.

Lists and errors

Lists come oldest first, up to limit (1 to 100, default 50). To get the next page, pass the last id you got as starting_after.

{
  "object": "list",
  "url": "/api/v1/customers",
  "has_more": true,
  "data": [ { "id": "…", "object": "customer", "name": "Jamie Rivera", … } ]
}

Errors have a status code and a reason you can show someone:

HTTP 403
{ "error": { "code": "forbidden", "message": "This key doesn't have the invoices:read scope." } }

Codes: unauthorized (401), forbidden (403), not_found (404), invalid_request (400), rate_limited (429), server_error (500).

Webhooks

Add an https address in Settings > Developers and pick the events. Each event is a JSON POST, usually within a minute. Anything other than a 2xx answer is retried after 1 minute, 5 minutes, 30 minutes, 2, 6, 12 and 24 hours. An address that keeps failing for 3 days is turned off, and you'll see why in Settings.

POST https://example.com/turf52-hook
Turf52-Signature: t=1795110000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
Turf52-Event-Id: 3b0e…
Turf52-Event-Type: visit.completed

{
  "id": "3b0e…",
  "object": "event",
  "type": "visit.completed",
  "created": "2027-04-02T15:04:05.000Z",
  "data": { "object": { "id": "…", "object": "visit", "status": "completed", … } }
}

The object is the same shape the API returns. The same event can arrive twice in rare cases; use the event id to ignore repeats.

Checking signatures

Every message is signed with the endpoint's secret (whsec_…). Compute HMAC-SHA256 of <t>.<raw body> with the secret and compare it to v1. Reject messages more than 5 minutes old.

import { createHmac, timingSafeEqual } from "node:crypto";

function isFromTurf52(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return expected.length === parts.v1?.length && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}