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"
customers:readRead customers and propertiescustomers:writeAdd customersrequests:writeSend in service requests (for your website)visits:readRead visits and the scheduleinvoices:readRead invoicespayments:readRead payments
Endpoints
| Call | Scope | What |
|---|---|---|
| GET /api/v1/me | any key | The company this key belongs to and its scopes |
| GET /api/v1/customers | customers:read | Customers with contacts. Filters: status, updated_since |
| GET /api/v1/customers/{id} | customers:read | One customer with contacts and properties |
| POST /api/v1/customers | customers:write | Add a customer (lead or active) with a contact and a property |
| GET /api/v1/properties | customers:read | Properties. Filters: customer_id, updated_since |
| GET /api/v1/properties/{id} | customers:read | One property |
| POST /api/v1/requests | requests:write | A service request from your website; it becomes a lead |
| GET /api/v1/visits | visits:read | Visits. Filters: date_from, date_to, status, crew_id, customer_id, updated_since |
| GET /api/v1/visits/{id} | visits:read | One visit |
| GET /api/v1/invoices | invoices:read | Invoices with lines. Filters: status, customer_id, updated_since |
| GET /api/v1/invoices/{id} | invoices:read | One invoice |
| GET /api/v1/payments | payments:read | Payments 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.
customer.createdA customer is addedvisit.completedA visit is doneinvoice.paidAn invoice is paid in fullestimate.acceptedAn estimate is acceptedpayment.receivedA payment comes inrequest.createdA service request comes in
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));
}