Smithworks API reference

How does the Smithworks API work?

Every request is an HTTPS POST of a JSON body to one address. The body names an action, and the response is JSON.

POST https://ggkagqwqfabtzuhzjznx.supabase.co/functions/v1/api
Content-Type: application/json
x-api-key: swk_…

{ "action": "zapier.me" }

The API runs on Smithworks’ own Supabase project, which is why the address is on supabase.co. Smithworks builds and operates it.

How do I get an API key?

An owner opens Settings → Zapier in the Smithworks app or at dispatch.smithworks.app and taps Create Zapier key. Keys start with swk_ and are shown once.

Send the key in the x-api-key header of every request. Each key belongs to one business. Smithworks stores only a scrambled copy, so a lost key can’t be shown again: delete it in the same screen and create a new one. Deleting a key also stops every Zap that uses it.

How do I check that a key works?

Call zapier.me. It returns the business the key belongs to.

curl https://ggkagqwqfabtzuhzjznx.supabase.co/functions/v1/api \
  -H "Content-Type: application/json" \
  -H "x-api-key: swk_…" \
  -d '{"action":"zapier.me"}'

{ "id": "6f1c…", "business": "Example Lock & Key" }

What does an error look like?

A failed request returns a JSON body with an error message and a 4xx status. The message is written for the person who set up the Zap.

{ "error": "Enter a 10-digit US phone number." }

• 400: a missing or invalid field, an unknown action, or the daily allowance used up.
• 401: the key is missing, deleted or not a Smithworks key.
• 403: the business’s plan is view-only. Only zapier.me and zapier.unsubscribe still work.
• 429: the business has received its 40 booking requests for the day.

What are the limits?

Each business can make 5,000 API calls a day, have 50 Zaps listening for events and receive 40 booking requests a day.

Requests must be smaller than 250 KB. Text fields are trimmed and cut to a set length, such as 100 characters for a name and 5,000 for notes.

How are events sent?

Smithworks uses REST hooks. A Zap subscribes to an event, and Smithworks POSTs each new record to the Zap’s address as soon as it happens.

• zapier.subscribe with event and targetUrl returns { "id": "…" }. The address must be an https address on hooks.zapier.com.
• zapier.unsubscribe with that id returns { "deleted": true }.
• zapier.samples with event returns up to three of the newest matching records, for testing a Zap.

Each delivery is a POST of one record as JSON. If the address answers 410, Smithworks removes the subscription. Other failures are tried again, waiting longer each time, up to an hour apart.

The events, and the record each one sends:

• customer.created: a customer
• request.received: a job with status requested
• quote.created: a quote
• quote.booked: a job
• job.scheduled: a job, plus rescheduled (true when an existing job moved to a new window)
• job.completed: a job
• job.cancelled: a job, plus was_request (a declined booking request) and expired (a request nobody answered)
• invoice.issued: an invoice
• payment.received: a payment

What fields does each record have?

Records use snake_case fields. Money is in dollars, times are ISO 8601 in UTC, and a field with no value is an empty string, or null for a number.

Customer: id, name, phone, email, company, alternate_phone, service_address, billing_address, notes, preferred_contact.

Jobs, quotes, invoices and payments also carry the customer as customer_id, customer_name, customer_phone and customer_email.

Job: id, status (requested, confirmed, completed or cancelled), kind, service, address, window_start, window_end, arrival_window (in the business’s time zone), duration_minutes, quoted_price, total (the invoice total, or the quoted price before there is an invoice), invoice_number, vehicle_year, vehicle_make, vehicle_model, vehicle_vin, notes. A job without an arrival window, such as a booking request made by a Zap, has empty window fields.

Quote: id, service, address, quoted_price, lines, duration_minutes, the vehicle fields, notes, updated_at.

Invoice: id, number, job_id, issued_at, issued_date (YYYY-MM-DD in the business’s time zone), subtotal, tax, total, paid, balance, lines.

Payment: id, amount, tip, method (cash, check, card or other), paid_at, invoice_id, invoice_number, invoice_total, balance (left to pay after this payment).

Each item in lines has description, quantity, unit_price and amount.

{
  "id": "5105ab0b-…",
  "number": 1042,
  "job_id": "884801a9-…",
  "customer_id": "9a067559-…",
  "customer_name": "Pat Lee",
  "customer_phone": "(512) 555-0100",
  "customer_email": "[email protected]",
  "issued_at": "2026-10-06T16:30:00.000Z",
  "issued_date": "2026-10-06",
  "subtotal": 216,
  "tax": 17.82,
  "total": 233.82,
  "paid": 0,
  "balance": 233.82,
  "lines": [
    { "description": "Car lockout", "quantity": 1, "unit_price": 125, "amount": 125 },
    { "description": "Transponder key cut", "quantity": 2, "unit_price": 45.5, "amount": 91 }
  ]
}

Which actions read data?

Five actions read without changing anything: zapier.me, zapier.services, zapier.customers, zapier.jobs and zapier.customers.find.

• zapier.services: the business’s services as { "id", "name" }.
• zapier.customers: the 100 newest customers as { "id", "name" }, where the name includes the phone number.
• zapier.jobs: the 50 latest jobs that aren’t cancelled, as { "id", "name" }, where the name gives the date, service and customer.
• zapier.customers.find with any of phone, email and name: up to 10 matching customer records, newest first. Phone and email must match exactly; the name matches any part.

Which actions change data?

Four actions write: create a customer, update a customer, add a note to a job and create a booking request. Each returns the saved record.

zapier.customer.create: name, phone (required, a 10-digit US number), email, company, notes, and a service address as street, unit, city, state and zip. Returns a customer.

zapier.customer.update: id (required) and any of the fields above. Blank fields leave the saved value as it is. Returns a customer.

zapier.job.note: jobId and note, both required. The note is added below the job’s existing notes. Returns a job.

zapier.request.create: serviceId (from zapier.services) and phone are required; name, email, address, vehicleYear, vehicleMake, vehicleModel and notes are optional. The request waits for the locksmith to accept or decline it, like one from the booking page. A phone number that matches a saved customer uses that customer. Returns a job with status requested.

{
  "action": "zapier.request.create",
  "serviceId": "c3b1…",
  "name": "Jordan Diaz",
  "phone": "(512) 555-0142",
  "address": "48 Oak Ln, Austin, TX 78704",
  "notes": "Locked out of the front door"
}

The API can’t schedule jobs, change prices, record payments or delete records.