A map for software, and for the AI

Ask the desk.

Look up a customer, price the job, find a Thursday, send the text. Same commands the office already uses. A key lets your own tools do it too.

The HTTP API is part of the AI plan ($99 a month). An owner or admin makes a key in the app under Settings → Connectors → Custom API (the same keys are under Settings → ChalkBot). Core ($49) cannot make or use developer keys. Signing into the app is not this API. The website estimator ingest key is a different thing and stays on every plan. Every command is also in openapi.json (OpenAPI 3.1).

How a call works

Same shop the crew already uses. A key acts as a person, the areas you give it say what it can reach, and queued sends still wait out quiet hours. Nothing here invents a second CRM.

1

A key from Settings

An owner or admin makes one in Settings → Connectors → Custom API, or Settings → ChalkBot. AI plan ($99) only. It acts as the person who made it, or as a lower role they pick, and never reaches past what that person can do today. Give it an end date if you like. Revoke it and the calls stop.

2

Areas for the job

Each area is off, read or write. Messaging customers is its own switch, and moving money needs write on Payments and money. Adding pay owed to the crew needs only Crew pay. Start tight.

3

A command you already know

The paths below are the ones the app already runs. Your software hits the same commands the office does.

GET https://app.chalkcrm.com/api/clients/lookup?q=thompson
Authorization: Bearer chk_live_…

Make that Bearer token in Settings → Connectors → Custom API (or Settings → ChalkBot). AI plan only. It is shown once, so copy it then.

Four kinds of permission

Each area on a key is off, read or write. Messaging customers and moving money sit on top. A Zapier key can read the board without ever sending a text, and even a key that can send still follows STOP and your channels. Queued sends wait out quiet hours; a direct inbox reply goes at once, like one typed in the app.

read

Look at an area: customers, quotes, the schedule, invoices, the inbox, reports. A read changes nothing.

write

Create, edit, archive and delete in that area: customers, quotes, jobs, visits, invoices, notes, the price book. A command whose job is to message a customer is not part of write. It needs send as well.

send

The Can message customers switch. With write on the area, the key can send a quote or an invoice, a receipt, a reminder, a booking confirmation, an on-my-way or a follow-up, text from the inbox, mark a quote sent, make a customer's private link, and create or switch on automatic messages. Without it, a write that would have messaged somebody still saves and answers notified: false with not_notified_reason, or is refused when messaging is its whole point.

money

Write on Payments and money. The key can charge a saved card, make a checkout link, refund, remove a saved card, write off bad debt, and add, hold or mark payouts paid. Read on it only looks. To let a script log what the crew is owed without any of that, give it Crew pay instead.

Areas, roles and limits

What a key can reach is the lesser of two things: the areas ticked on the key, and what the person it acts as can do in the app today.

The thirteen areas

Each is off, read or write on the key. Write includes read.

AreaWhat it covers
ClientsCustomers, properties, notes, tags
SalesRequests, quotes, the funnel, the price book
ScheduleJobs, visits, checklists, timers
InvoicesInvoices, payments written down by hand, expenses
Payments and moneyCard charges, refunds, saved cards, payouts, payroll, time cards
Crew payAdd and change pay owed to your team on jobs. It can't mark pay as paid or move money.
MessagesText threads, the inbox, notifications
FilesPhotos and documents
SettingsBusiness settings, history, saved views, ChalkBot status
AutomationsAutomatic texts and emails, tag rules
TeamTeammates, roles, what each role can reach, sign-ins
ReportsThe Chalkboard, reports, the books, timesheets
InventoryStock, versions, places, tools and equipment (read only for now)

Crew pay at write adds a split owed on a job (POST /api/payouts or POST /api/jobs/:id/payouts), and changes, removes, archives or restores one that is still owed and was added by hand (PATCH and DELETE /api/payouts/:id). It never marks pay paid, holds it, overrides it or touches a paid row. At read it lists pay (GET /api/payouts, ?job_id= for one job) and reads one row. Keys made before areas with the write scope can add and change owed pay the same way.

A few commands cross areas: crew pay on a quote or job line and what a line costs need write on Payments and money, turning a quote or job into an invoice needs write on Invoices, and changing the tax rate or a teammate's pay needs write on Payments and money as well.

Acts as a person, or a role

A key acts as the person who made it. The owner or admin making it can pick a role in Acts as instead, like office, sales or technician. Any role but owner.

The key never reaches past its maker as they are today. If they are moved to a smaller role, the key shrinks with them, and if a role's switches are edited, the key gets the lesser of the two.

With write on Team, a key still never touches an owner, an admin, or the person who made it. It cannot make anybody an owner or admin, change a teammate's email or phone (where sign-in links go), or change what its own role can reach.

End dates and revoking

Ends on is optional. After that day every call is a 401: This API key has expired. An owner or admin can give it a new end date, change its areas or its role without making a new secret.

Revoke stops it at once and cannot be undone. Make a new key instead.

An admin cannot change a key that belongs to an owner.

Safe retries: Idempotency-Key

Send any unique string, 8 to 200 characters, as an Idempotency-Key header on a POST, PUT, PATCH or DELETE. If the call times out, send it again with the same key and the same body. Within 8 days the repeat gets the first answer back, with Idempotent-Replayed: true, and the work is not done twice.

POST https://app.chalkcrm.com/api/clients
Authorization: Bearer chk_live_...
Idempotency-Key: zap-7f3c2a91-new-lead
{ "first_name": "Rita", "phone": "864-555-0133" }

The same key with a different body is a 422 and nothing is saved. A twin that arrives while the first is still running waits for its answer, or gets a 503 to try again if it takes too long. Server errors, 401, 402, 408 and 429 are not kept, so a retry runs again. Retries are matched per API key.

History and the call log

History: a change made with a key shows in Settings → History as the person via the key, like Sam via API key 'Zapier' (chk_live_ab12345…). You can always tell a script from a person.

Call log: open a key in Settings → Connectors → Custom API to see its last 20 calls: method, path, status and time. Every change and every refusal is logged (except the per-minute cap's own 429s), and about one plain read in ten. Never a query string, a body or a header. The log keeps 30 days.

The whole list, for machines

openapi.json is every command a key may call, in OpenAPI 3.1, with the permission each one needs (sales:read, sales:write, sales:send, payments_money:money), the errors and the Idempotency-Key header. Point Claude, Cursor or a code generator at it. It is built from the same list the server checks, so it never offers a door the key cannot open.

Keys made before areas keep their old read, write, send and files scopes and reach exactly what they did, until an owner or admin changes their areas.

Before your first call

The address and the key

Every command is https://app.chalkcrm.com plus the path, with Authorization: Bearer chk_live_.... Send JSON with Content-Type: application/json. Photos are raw bytes (see Notes and photos).

GET https://app.chalkcrm.com/api/users/me
Authorization: Bearer chk_live_...

GET /api/users/me says who the key acts as, their switches, may_set_crew_pay, and the key's areas (access), role (acts_as), end date (expires_at) and call cap.

A key acts as the person who made it

Its role and the switches on Settings, Team are the ceiling, exactly as on their screens, and the key's areas narrow it from there. Pick a lower role in Acts as, or make the key as the person whose reach you want.

Key made byWhat it can do
Owner, adminEverything below, plus crew pay (on lines and in the price book), the price book's measurements, invoices from jobs, automations, catalogs.
OfficeCustomers, leads, quotes, jobs, the calendar, invoices and payments; reads pay and the books. Cannot set crew pay.
Sales, estimatorCustomers, leads, quotes, jobs, the calendar. Sees crew pay while Job prices is on; cannot change it. No invoices, pay or books.
BookkeeperReads invoices, payments, pay and the books.
Field crewTheir own day and their own visits. No money.

When something is wrong

Every refusal is JSON: { "error": "plain words", "detail": { "field": "line_items[0].measures[0].pay_per_unit_cents" } }. detail is there when there is a field to name.

400Something in the request is wrong or unknown. A field Chalk would not save is refused by name, never dropped quietly.
401No key, a revoked or expired one, or the person who made it is no longer on the team.
402The shop's Chalk subscription has lapsed. detail.billing says why.
403The key's areas do not reach that, and the message names what is missing, like This API key cannot change Sales. or This API key cannot message customers. Also when the person it acts as cannot do it in the app, the shop is not on the AI plan, or the door is never open to keys.
404Not in this shop. Ids from another shop answer the same as ids that never existed.
409A clash: a visit on top of another (send force: true), or a stale save: base_updated_at must be exactly the updated_at you read, and any other stamp is refused.
422An Idempotency-Key already used for a different change. Nothing was saved.
429Too many calls this minute. Wait for Retry-After seconds.

Money, dates, paging, pace

Money is whole cents: $3.50 is 350, a dollar a foot is 100. A decimal in a cents field is a 400. Rates are basis points: 5% is 500.

Dates are ISO: 2026-10-01 or 2026-10-01T13:00:00Z. The shop's own days follow its time zone (/api/users/me).

Paging: lists come newest first and stop at a cap. Jobs, invoices, quotes and payments take ?limit= and ?before=. A full page answers with an X-Next-Before header: pass it as before for the next page. Clients take ?limit= up to 500 and ?q=.

Pace: 240 calls a minute per key, each key counted on its own. Over that is a 429 with Retry-After.

Crew pay on a line

A 200 ft fence at $3.50 a foot, with $1.00 a foot for the crew, and no price-book item behind it. Put the pay on the line. Chalk carries it the whole way: the quote's cost card, the job it becomes, the crew on its visits, Pay > Owed, the job's profit card and Reports.

POST https://app.chalkcrm.com/api/quotes
Authorization: Bearer chk_live_...  (made by the owner or an admin)
{
  "client_id": "cli_...",
  "property_id": "prop_...",
  "title": "Fence staining - 200 ft",
  "line_items": [
    {
      "name": "Fence staining",
      "description": "Clean, brighten and stain both sides",
      "measures": [
        { "label": "Fence", "unit": "ln ft", "quantity": 200,
          "unit_price_cents": 350, "pay_per_unit_cents": 100 }
      ]
    }
  ]
}

201, total $700. GET the quote: cost_preview.measurement_pay_cents is 20000.

Where the pay can go

On a measurement: measures[].pay_per_unit_cents, split_mode (split shares it, full pays each person all of it) and unit_cost_cents (what it costs you). With or without a product_measure_id. When both are sent, the value on the line wins over the price book.

On a plain line: crew_pay_cents (flat for the line) or pay_per_unit_cents (times the line's quantity), and split_mode. Not both. A measured line takes its pay on the measurements.

One line at a time: PUT /api/quotes/:id/lines/:lineId/crew-pay (or /api/jobs/...) with pay_per_unit_cents or crew_pay_cents. 0 takes it off.

What happens to it

Convert: the job gets the lines and the pay, and the crew's share waits as "Crew" until somebody is on a visit. Put people set to "By the job" on the visit and it becomes theirs in Pay > Owed: $200 for one, $100 each for two on split. People paid by the hour or the day are paid for their time instead. The job keeps the pay it was sold with: a price-book change later never moves it.

A save that sends a line back without its pay keeps the pay. Sending the same value back is fine for any key; changing it needs a key made by the owner or an admin, or it is a 403: Only the owner or an admin can set crew pay.

Customers never see pay or cost: not on the quote page, the PDF, the email or the invoice.

Refused by name

With a key, these are a 400 naming the field: a field Chalk does not use inside line_items[] or measures[]; a product_measure_id that is not in this shop; cents that are not whole, below zero, or past the cap ($10,000 a unit, $100,000 flat); measures[] sent while measurements are off (Settings, Company, or measures_enabled); crew pay on an invoice line (the crew is paid from the job).

Crew pay on a line needs a database update, migration 0118. Until a shop has it, a pay change answers 400 and says so; everything else works as before.

What a line costs

Your materials, line by line, with no price-book item behind them. Send what each line costs you, or the named things it buys. Chalk counts it in the quote's cost card, the job's profit card and Reports, and lists it in what to buy. The customer never sees it.

POST https://app.chalkcrm.com/api/quotes
Authorization: Bearer chk_live_...
{
  "client_id": "cli_...",
  "property_id": "prop_...",
  "title": "Fence staining - 200 ft",
  "line_items": [
    {
      "name": "Fence staining", "quantity": 1, "unit_price_cents": 200000,
      "crew_pay_cents": 30000,
      "cost_breakdown": [
        { "name": "EXPERT Stain & Seal", "quantity": 3, "unit": "5-gal pail", "unit_cost_cents": 11900 },
        { "name": "Brushes and rollers", "quantity": 1, "unit": "kit", "unit_cost_cents": 1800 }
      ]
    },
    { "name": "Gate", "quantity": 2, "unit_price_cents": 5000, "unit_cost_cents": 1200 }
  ]
}

201, total $2,100. GET the quote: the fence line's line_cost_cents is 37500 (3 x $119 + $18) and the gate's is 2400 (2 x $12). cost_preview.materials_cents is 39900; with $300 crew pay and 10% overhead, cost_cents is 90900 and profit_before_profit_splits_cents is 119100.

Two ways to say it

unit_cost_cents: what one unit of the line costs you. The line costs quantity x that, to the cent.

cost_breakdown: up to 20 named items, each name, quantity (2.5 is fine), unit ("5-gal pail", default "each") and unit_cost_cents. The line costs the sum of its items, each quantity x unit cost to the cent.

Both: with a list, Chalk stores unit_cost_cents as the sum divided by the line's quantity, to the cent. Send it too and it must be that number, or it is a 400 that says the number to send. A measured line's quantity is 1.

Where it counts

The quote: cost_preview.materials_cents is price_book_materials_cents plus line_materials_cents, and GET /api/quotes/:id/materials lists every item. An optional extra counts once the customer takes it.

Nothing twice: a line linked to a price-book measurement (or a price-book item measured by its quantity, with material rules) gets its materials from the price book, as before. Its own cost is not added on top, and a list on it is a 400.

The job: convert copies the cost and the list, and the job keeps them as sold. Its profit card and Reports show "Estimated materials (from quote)" until a materials receipt is logged on the job. Then the receipts are the materials and materials_vs_estimate_cents says how they compare. Never both.

Keeping and changing it

A save that sends a line back without unit_cost_cents or cost_breakdown keeps them, and a new quantity divides the list again. cost_breakdown: [] clears the list and the line keeps its cost per unit. A new unit_cost_cents on a line that has a list is a 400: send a new list, or [] with the cost.

One line: PUT /api/quotes/:id/lines/:lineId/cost (or /api/jobs/...) with cost_breakdown and/or unit_cost_cents.

What it really cost

POST /api/jobs/:id/expenses logs what was bought for the job, in the same shape as a list: { "items": [{ "name", "quantity", "unit", "unit_cost_cents", "category" }] }, plus incurred_on, note and reimbursable if you want them. Each item is one row on the job's expenses, quantity x unit_cost_cents to the cent. category is "materials" when left out.

The first materials row replaces the quote's estimate on the job's profit, and the answer says how the receipts compare with it. Fuel, rentals and other categories are expenses, not materials, so the estimate stays.

Who, and what is refused

The owner and admins see and set the named items (cost_breakdown), line_cost_cents, materials_from, the prices on the shopping lists and the one-line endpoint, like crew pay. Everyone else gets none of that: a list from them, or a new cost typed over a line that has a list, is a 403, and the same numbers sent back are fine.

The rest of the office (Job prices on, the default for Sales and Office) keeps what it had: the cost card, the job's profit and a plain line's unit_cost_cents. The field crew (Job prices off) is sent none of it and their saves keep it. The customer never sees it: not on their page, the PDF, emails, texts or invoices. ChalkBot only tells it to a role that sees the books.

A 400 names the field: an item field Chalk does not use, a missing name, cents that are not whole or below zero, a quantity of 0, more than 20 items, a list on an invoice line, a list and a cost on the line's measurements at once. The list needs migration 0122; until a shop has it, a list answers 400 and says so, and unit_cost_cents still counts.

A timed offer on a quote

Money off that lasts a set time once the quote is sent: "$150 off if you book by Friday", "10% off for two weeks". The customer's page shows it with a countdown, and when the clock runs out it drops off by itself and the total goes back up. Approve while it runs and it is locked in for good.

POST https://app.chalkcrm.com/api/quotes
Authorization: Bearer chk_live_...
{
  "client_id": "cli_...",
  "property_id": "prop_...",
  "title": "Fence staining - 200 ft",
  "line_items": [ { "name": "Fence staining", "quantity": 1, "unit_price_cents": 200000 } ],
  "timed_discount_kind": "percent",
  "timed_discount_bp": 1000,
  "timed_discount_hours": 3,
  "timed_discount_unit": "days",
  "timed_discount_reason": "Book this week"
}

201, total_cents 180000 while it runs. GET the quote: quote.timed_discount is { "kind": "percent", "bp": 1000, "hours": 3, "unit": "days", "until": "...", "active": true, "off_cents": 20000, "portal_total_cents": 180000, "remaining_ms": 259199000, "countdown": "2d 23h", "reason": "Book this week" }. Send it, and the customer sees "Book this week 2d 23h" in a green pill with $1,800.00 at the bottom.

The fields

timed_discount_kind: "amount" or "percent". null takes the offer off.

How much: an amount offer takes timed_discount_cents (whole cents, more than 0: $150 is 15000). A percent offer takes timed_discount_bp (basis points, 1 to 10000: 1000 is 10%). The percent is of the work, not of a card fee line. Either one is held to what the work comes to.

How long: timed_discount_hours is the number (a whole number, 1 or more) and timed_discount_unit says what it counts: "hours" (the default), "days", "weeks" or "months". The longest offer is 24 months: 17520 hours, 730 days, 104 weeks or 24 months.

timed_discount_reason: the pill's words, up to 60 characters. Left out, the pill says "Offer ends."

The clock

It starts again from zero when the quote goes to the customer (/send, /mark-sent, or PATCH status: "awaiting_response"), so an offer written days before still gets its full time. On a draft it runs from the save, which is only a preview.

until (when it ends) is Chalk's to set, so leave it out. The one a GET gave you may ride back unchanged.

PATCH: a new timed_discount_kind, timed_discount_hours or timed_discount_unit starts the clock again from now. A new amount, percent or reason keeps it. Changing "amount" to "percent" needs the new timed_discount_bp with it, and the other way round.

Approved: an offer running when the quote is approved (by the customer or /approve) is locked in and stays after the clock. One added to an already approved quote is locked in straight away.

Reading it

GET /api/quotes/:id returns quote.timed_discount: kind, cents, bp, hours, unit, until, active, off_cents, remaining_ms, countdown (the customer's pill text: "2d 23h", "4h 05m", or the end date when two weeks or more are left) and portal_total_cents (what the customer pays right now, the same as total_cents).

Once the time is up, active is false, off_cents 0, countdown "", and total_cents is back to the full price: on the GET, the customer's page, the PDF and the Quotes list.

Several discounts: discounts[]

Instead of the single fields, send every discount as a row: kind, cents or bp, reason, and for a timed row "timed": true with hours and unit. discounts[] replaces all of the quote's discounts, and [] takes them all off. Up to 20 rows. Each timed row has its own clock and its own pill.

"discounts": [
  { "kind": "amount", "cents": 10000, "reason": "Neighbor" },
  { "kind": "percent", "bp": 500, "timed": true, "hours": 2, "unit": "weeks", "reason": "Fall special" }
]

The rows GET returns can go straight back: a row sent back with the same hours and unit keeps its clock, a new length starts it again.

Ending on a set day. A timed row with "unit": "date" and an until (an ISO date and time, in the future and within 24 months) counts until that moment and is never restarted by a send or a copy: { "kind": "amount", "cents": 20000, "timed": true, "unit": "date", "until": "2026-10-24T23:59:59-04:00", "reason": "Fall special" }. Its hours is not used. The customer's page and the PDF say "Approve by Fri, Oct 24 to save $200.00" beside it.

Discounts stack: every percent is of the work before any discount (never of what another left), dollar amounts add on top, and together they never take more than the work. The app's editor holds a quote to 5 discounts; a key may send up to 20.

Only a timed row counts down. Money added into discount_cents, or into a row without "timed": true, is a standing discount whatever its reason says. A "book within 24 hours" offer next to other discounts is two rows: { "kind": "amount", "cents": 12264, "reason": "Senior (65+)" } and { "kind": "amount", "cents": 12264, "timed": true, "hours": 24, "unit": "hours", "reason": "Book Today" }. Every row's reason, standing ones included, is held to 60 characters.

Refused by name

For a key, a 400 names the field and nothing is saved: a kind or unit Chalk does not have, a length of 0, a fraction or past 24 months, a new offer with no length, cents that are not whole, 0 or more than $1,000,000, basis points outside 1 to 10000, cents on a percent offer or bp on an amount one, a reason over 60 characters, an until or applied Chalk did not hand out (a "unit": "date" row's own until aside, which must read as a time ahead), a row field Chalk does not use, and discounts[] sent together with the single fields. A converted quote refuses the edit and names the job.

Tiers on one line

"Basic or better stain, your pick": one line of the quote with two or more prices, and the customer picks one on their page. Each tier is an ordinary line with its own name, description, price and measurements. Name the tier in the line's own name ("Deck stain, semi transparent"); there is no separate label.

POST https://app.chalkcrm.com/api/quotes
Authorization: Bearer chk_live_...
{
  "client_id": "cli_...",
  "property_id": "prop_...",
  "title": "Deck staining",
  "line_items": [
    { "name": "Deck stain, semi transparent", "quantity": 400, "unit": "sqft", "unit_price_cents": 175, "choice_group": "deck" },
    { "name": "Deck stain, solid color", "quantity": 400, "unit": "sqft", "unit_price_cents": 225, "choice_group": "deck", "recommended": true },
    { "name": "Railing stain", "quantity": 1, "unit_price_cents": 30000 }
  ]
}

201, total_cents 120000: the recommended tier ($900) plus the railing. The customer's page shows the two deck tiers as one choice, and the total follows their pick. When they approve, the tier they picked is saved as selected: 1 and the other as selected: 0.

The fields

choice_group: short text, the same on every tier of one line, up to 40 characters. It is a key and is never shown to anybody. Lines with the same choice_group must sit next to each other in line_items[]. Leave it out, or send null, for an ordinary line.

Pick one: leave optional off. One tier is always in the total.

Pick one or none: optional: true on the tiers, for an extra the customer may skip ("deck restoration: soft wash or strip"). Nothing is in the total until they pick, the same as an optional extra.

recommended: true on the tier you suggest. It shows a badge, and on a pick-one line it is the tier in the total until the customer picks.

selected: the tier in the total. Send it to record a pick the customer made with you; leave it out and Chalk picks as below.

How Chalk puts it right

Every save tidies the tiers, so the stored lines always follow the rules. Nothing is moved: lines keep their order.

The first tier decides whether the line is pick one or pick one or none, and every tier follows it. Only the first tier marked recommended keeps it.

Of the tiers sent with selected: true, the recommended one wins, else the first. With none, a pick-one line takes the recommended tier, or the first when none is recommended. A pick-one-or-none line takes none.

A choice_group on one line alone makes it an ordinary line. Tiers carry the first tier's section.

Where it counts

Only the tier in the total counts: the quote's subtotal_cents, tax, discounts, deposit percentage and card or bank fee, the materials and crew pay on cost_preview, and the PDF, which prints only that tier.

A job or invoice made from the quote gets the picked tier as an ordinary line, and none of the others. A pick-one-or-none line nobody picked carries nothing.

POST /api/quotes/:id/duplicate and quote templates keep the tiers and any add-ons. A template keeps no pick: a quote made from it starts on the recommended tier.

Refused by name

A 400 names it and nothing is saved: a choice_group that is not text, or the tiers of one line apart from each other. Tiers are for quotes and quote templates: on a job or an invoice line, choice_group is read back as nothing.

Add-ons on a line

"Living room, and if you want, the accent wall too": an optional line that belongs to the line above it. The customer ticks it on their page, under that line. Each add-on is an ordinary line with its own name, description, price, tax and measurements.

POST https://app.chalkcrm.com/api/quotes
Authorization: Bearer chk_live_...
{
  "client_id": "cli_...",
  "property_id": "prop_...",
  "title": "Interior painting",
  "line_items": [
    { "name": "Living room walls", "quantity": 1, "unit_price_cents": 120000 },
    { "name": "Accent wall", "quantity": 1, "unit_price_cents": 25000, "addon": true, "recommended": true },
    { "name": "Remove popcorn ceiling", "quantity": 1, "unit_price_cents": 60000, "addon": true }
  ]
}

201, total_cents 120000: an add-on is not in the total until it is taken. When the customer ticks the accent wall and approves, it is saved as selected: 1 and the total is 145000.

The fields

addon: true on a line that belongs to the line right above it. A line's add-ons sit one after the other directly under it, and under the last tier when that line has tiers (they belong to the whole line).

An add-on is always optional: it counts only once selected. recommended is a badge only. Send selected: true to record that the customer took it.

How Chalk puts it right

Every save tidies the add-ons. Nothing is moved.

An add-on is never a tier: its choice_group is cleared. An add-on with no line above it (the first line) is an ordinary optional extra.

An add-on cannot be taken while its line is not: under an optional line nobody took, or an optional line with tiers and no pick, its selected is 0, on save and when the customer approves.

Where it counts

A taken add-on counts like any line: the total, tax, discounts, deposit percentage, card or bank fee, materials and crew pay.

A job or invoice made from the quote gets each taken add-on as an ordinary line right after its line. An add-on not taken carries nothing.

Duplicate and quote templates keep the add-ons. Before migration it is read back as addon: 0.

Refused by name

A 400 names it and nothing is saved: an addon that is not true or false. Add-ons are for quotes and quote templates: on a job or an invoice line, addon is read back as 0.

Options inside one quote

"Stain only, or the full restoration": one quote with two to four options, and the customer picks one on their page. Or, for options that are separate jobs ("the front deck, the back fence, a house wash"), the customer may take several: options_pick: "many". It stays one quote: one number, one row in every list, one message, one set of terms, one discount and one deposit setting. Each line belongs to exactly one option.

POST https://app.chalkcrm.com/api/quotes
Authorization: Bearer chk_live_...
{
  "client_id": "cli_...",
  "property_id": "prop_...",
  "title": "Deck",
  "options": [ { "key": "a", "label": "Stain only" }, { "key": "b", "label": "Full restoration" } ],
  "recommended_option": "b",
  "line_items": [
    { "name": "Deck stain", "quantity": 1, "unit_price_cents": 210000, "quote_option": "a", "link_key": "stain" },
    { "name": "Sand and repair", "quantity": 1, "unit_price_cents": 150000, "quote_option": "b" },
    { "name": "Deck stain", "quantity": 1, "unit_price_cents": 270000, "quote_option": "b", "link_key": "stain" }
  ]
}

201, total_cents 420000: the quote's own subtotal, total and deposit are the recommended option's until the customer picks. GET lists each option with its own total.

POST https://app.chalkcrm.com/api/quotes/01J.../approve
Authorization: Bearer chk_live_...
{ "chosen_options": ["c", "a"] }

200, on a quote made with "options_pick": "many" and three options: a Front deck ($2,100, taxed), b Back fence ($1,500) and c House wash ($500, not taxed), at 7% tax. GET then says chosen_options ["a", "c"], chosen_option "a", and the quote is both of them: subtotal_cents 260000, tax_cents 14700, total_cents 274700. The job made from it carries the deck and the house wash lines. Sent with no keys before any were taken, the answer is the 409 with "options_pick": "many".

The fields

options: two to four, in order, each { key, label }. key is a short id (letters, digits, - or _, up to 16) that is never shown; label is the name the customer reads, up to 40 characters ("Option A" when left out). One option is no options. "options": [] takes them off.

recommended_option: the key of the option to show first. Left out, it is the first. Sent alone on PATCH it moves the badge.

options_pick: "one" (the default: the customer takes exactly one option) or "many" (they may take any of them, one or several). Left out on PATCH it keeps what is stored, including when the options are sent again. It can change while the quote is open, the same as the options. The office sees it as Customer can pick more than one.

On each line: quote_option, the key of its option. On a quote with options every line sends one; on a quote with none, no line does. link_key: the same text on the copies of one line across options, so the office's editor changes them together. Chalk stores it as sent and never shows it.

Which option counts

The shown option is the chosen one once the customer approved, else the recommended one, else the first. Its lines are the quote's lines for everything that adds up: subtotal_cents, total_cents, deposit_cents, lists, reports and the PDF, which prints the shown option and names the others with their totals.

Inside an option everything works as on a plain quote: tiers, add-ons, optional extras, a fee line. An add-on adds to the line above it in its own option. The discount and the deposit setting apply to each option on its own.

GET /api/quotes/:id returns options (each with key, label, shown, recommended, chosen, lines, subtotal_cents, discount_cents, tax_cents, total_cents and deposit_cents), recommended_option, options_pick ("one" or "many"), chosen_option, chosen_options (every option the customer took, in option order: [] until they take one) and shown_option. All of them are null on a quote with no options. Each option's own figures stay its own: on a pick-many quote, chosen is true on every option taken.

Pick many: the money

Until the customer takes any, the recommended option alone counts, exactly as on a pick-one quote.

Once they took two or more, the quote is all of them, added up as one quote's lines by the same rule as a quote with one option. Each line counts as it does in its option (tiers, add-ons, extras, fee lines). The quote's discounts come off once, on all that work: a dollar discount once, whatever number of options is taken ($100 off with three taken is $100 off in all), a percent of all the work taken, a timed offer while it runs, and never more than the work. Then the tax is worked out once. The options' own total_cents are each option alone, with the discounts on it alone, so the quote's total_cents is not their sum. The job and the invoice made from the quote come to the approved total to the cent.

Deposit: a percent deposit is that percent of the total. A set deposit (deposit_cents) is the figure you typed, asked once, never once per option, and held to the total. While the customer is still choosing it is held to all the options' totals together, since they may take every one.

Card or bank fee lines: each option carries its own, priced on that option alone. Two or more taken are one payment, so their fee lines are set together to the fee on the whole charge: for a card, the processor's 2.9% + 30c grossed up, never more than 3%; for a bank payment, 0.8% up to $5 plus the $1.50 check, grossed up, never more than $6.50. That can be more than their own lines added (each was priced with the whole discount off it, and the quote takes a dollar discount once) or less (one fixed part, not one each). The difference goes on the first option's line, or comes off the later ones first. An option taken with no fee line of its own pays its share through the others'. If none of the options taken has a fee line (each came to nothing on its own, its discount took it all), the quote carries none, and the fee is charged when they pay by card or bank, the way it is on any quote without a fee line. With that payment method's pass-along switched off, or a fee line among them taxed, it only comes down, and once the answer stands (approved, signed and waiting on the deposit, or converted) a fee line only ever comes down. The customer's page shows the figure before they approve.

chosen_option keeps one key, the first option taken, so a reader that knows only one option still sees one that is in.

Approving, and what carries on

Approve, convert, invoice and a PATCH to status: "approved" take option: the key of the one the customer chose. It is written down as chosen_option and the quote adds up as that option. Once one is chosen, option can be left out.

On a pick-many quote send chosen_options instead: a list of every key they took, such as ["a", "c"], in any order (it is kept in option order). One key in the list is just that option, on either kind of quote. Once they took some it can be left out: convert and invoice carry what they took. Once the answer stands (approved, converted, signed and waiting on the deposit, or a job or bill made from it), the same list again is fine and a different one is a 409.

A job or invoice made from the quote carries only the chosen option's lines (on a pick-many quote, every option taken, in option order), as ordinary lines, without quote_option or link_key. A job, invoice or visit never has options.

POST /api/quotes/:id/duplicate keeps the options, how many may be taken, and each line's option and link; the copy starts with none chosen.

POST /api/quotes/:id/options adds one: { label, copy_from }. A quote with no options becomes one with two: its lines are Option A. copy_from (a key; "a" on a quote that had none) fills the new option with a linked copy of that option's lines, measurements, crew pay and costs included; without it the new option starts empty. Only while the quote is a draft, waiting on the customer, or with changes asked.

Refused by name

A 400 names it and nothing is saved: more than four options, a key that is not a short id, two options with one key, a label over 40 characters, a recommended_option that is not one of them, a line that names no option or one that is not there, or a line that names an option on a quote with none. Adding, taking off or changing an option's key on PATCH needs line_items sent with it.

Which one? Approve, convert, invoice or status: "approved" with no option, on a quote where none is chosen yet, is a 409 with choose_option: true, options_pick and options (each key, label, total_cents, recommended). Ask which one, and send it again with option. When options_pick is "many", ask which ones and send them all in chosen_options. An option that is not one of them is a 400.

Pick many, each a 400 with detail.field and nothing saved: options_pick that is neither "one" nor "many" (field options_pick); "many" on a quote with no options (options_pick); changing it once the quote is decided or filed away (options_pick); several keys on a pick-one quote (chosen_options); a key that is not one of the options (chosen_options[1], the place in the list); an empty list or one that is not a list (chosen_options); chosen_options and option together (chosen_options); chosen_options on a new quote, or on PATCH without status: "approved" (chosen_options). A PATCH that marks a pick-many quote approved and rewrites its options in the same save is refused (status): save the options first.

A save that does not know about options: line_items where no line sends quote_option, on a quote that has options and without options in the body, is a 409 with stale: true, and nothing is changed. Saving them would fold every option into one. Read the quote again and send each line with its option.

Before the database has the update, options are a 409 and a plain quote works as always.

The commands

What each call does

Plain paths, same as the app. Open any row for a real request and what Chalk answered. openapi.json has every command a key may call, including ones not listed here, with the permission each needs. You can archive an invoice, or delete an unpaid one with no payments.

Website leads (live now)

Mint it under Settings, Connectors. It files a lead from your own site. It is on every plan, including Core. It is not the $99 developer API, and Core shops keep this one even though they cannot mint developer keys.

POST/api/ingest/lead

Send first_name plus a phone or email, with the key in X-Api-Key. While the business is being restored from a backup (a few minutes), the answer is 202 with "queued": true and no ids: the lead is saved and added when the restore finishes. A business that texts from more than one Quo number can send line (the number's name, like "Paint", the number, or its Quo id) so the customer gets every text from that number.

Example
POST /api/ingest/lead
{
  "first_name": "Rita",
  "last_name": "Stroud",
  "phone": "864-555-0133",
  "message": "Deck, about 300 sq ft"
}

201
{
  "ok": true,
  "request_id": "01M3JVF2MS3GWXY6PH205M86Z0",
  "client_id": "01M3JVF2MRSP8G3R8K8R6MSM7D"
}

Customers

Find or create the person before a quote, a lead or a text. The lookup is the one you want from a chat.

GET/api/clients

Optional ?q= filters the book (name, company, email, phone digits, street). Omit q for the unfiltered list (capped). ?limit= up to 500, ?tag=, ?archived=1.

Example
GET /api/clients?q=harmon

200
[
  {
    "id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
    "first_name": "Dale",
    "last_name": "Harmon",
    "company_name": null,
    "is_company": 0,
    "is_lead": 1,
    "lead_source": null,
    "balance_cents": 0,
    ...
  }
]
GET/api/clients/lookup

Query q (name, phone fragment, address). Examples: ?q=John ?q=Ball ?q=864. Also still accepts name and phone for the in-app duplicate check. Returns { matches: [...] }.

Example
GET /api/clients/lookup?q=Harmon

200
{
  "matches": [
    {
      "id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
      "name": "Dale Harmon",
      "company_name": null,
      ...
    },
    ...
  ]
}
GET/api/clients/:id

One customer, with properties and recent work.

Example
GET /api/clients/01M3JVF1K1XS5ZJKJG6RF2TBXE

200
{
  "client": {
    "id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
    "tenant_id": "ten_flow",
    "first_name": "Dale",
    "last_name": "Harmon",
    "company_name": null,
    "is_company": 0,
    "is_lead": 1,
    ...
  },
  "emails": [
    {
      "id": "01M3JVF1K11859HXQ44TEWA5Q5",
      "tenant_id": "ten_flow",
      "client_id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
      ...
    },
    ...
  ],
  "phones": [
    {
      "id": "01M3JVF1K1Q0CSR7E9F1MQV9N1",
      "tenant_id": "ten_flow",
      "client_id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
      ...
    },
    ...
  ],
  "properties": [
    {
      "id": "01M3JVF1K2NWZFDP2HE54E9D8J",
      "tenant_id": "ten_flow",
      "client_id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
      ...
    },
    ...
  ],
  "archived_properties": [],
  "requests": [],
  "quotes": [],
  ...
}
POST/api/clients

Add a customer: first_name (or company_name), last_name, phone, email, and their first address as property: { street1, city, province, postal_code }. Answers { id, property_id }, ready for a quote. With a key, any other field is a 400 that names it. Optional line: which of the business's Quo numbers texts them (its name, number or Quo id), else the number set on the key, else the main number. A line that is not theirs is never refused: it comes back in warnings.

Example
POST /api/clients#spare
{
  "first_name": "Old",
  "last_name": "Lead"
}

201
{
  "id": "01M3JVF2N07H3CTPDHMCMEJHPG",
  "property_id": null
}
PATCH/api/clients/:id

Update a name, notes, type or terms. automations_paused_until (a day, like 2026-11-05) holds every automated text and email to them until that day, when they start again on their own; "" ends the pause, which needs the send permission like turning a reminder switch back on.

Example
PATCH /api/clients/01M3JVF1K1XS5ZJKJG6RF2TBXE
{
  "company_name": "Harmon Rentals"
}

200
{
  "ok": true
}
POST/api/clients/:id/phones

Add a phone number: number, optional label.

Example
POST /api/clients/01M3JVF1K1XS5ZJKJG6RF2TBXE/phones
{
  "number": "864-555-0120",
  "label": "Work"
}

201
{
  "id": "01M3JVF1N0GMJPB3HQ52MT475W"
}
POST/api/clients/:id/phones/:phoneId/texts

Texts off for a number: on false. Every row of the shop's phone book with that number goes off, and nothing is texted to it until it is back on. Turning texts back on (on true, with customer_asked true) is the customer's consent, so only a person signed in can do it, never a key.

Example
POST /api/clients/01M3JVF1K1XS5ZJKJG6RF2TBXE/phones/01M3JVF1N0GMJPB3HQ52MT475W/texts
{
  "on": false
}

200
{
  "ok": true,
  "texts_on": false
}
POST/api/clients/:id/phones/:phoneId/wrong

Mark a number wrong (wrong true) or right again (false). The number stays on file, marked for the next person. A call logged with the wrong_number outcome marks it too.

Example
POST /api/clients/01M3JVF1K1XS5ZJKJG6RF2TBXE/phones/01M3JVF1N0GMJPB3HQ52MT475W/wrong
{
  "wrong": true
}

200
{
  "ok": true,
  "wrong": true
}
DELETE/api/clients/:id/phones/:phoneId

Take a number off.

Example
DELETE /api/clients/01M3JVF1K1XS5ZJKJG6RF2TBXE/phones/01M3JVF1N0GMJPB3HQ52MT475W

200
{
  "ok": true
}
POST/api/clients/:id/emails

Add an email address: address.

Example
POST /api/clients/01M3JVF1K1XS5ZJKJG6RF2TBXE/emails
{
  "address": "office@harmonrentals.example"
}

201
{
  "id": "01M3JVF1N27AFJFA6A0YVC6957"
}
DELETE/api/clients/:id/emails/:emailId

Take an address off.

Example
DELETE /api/clients/01M3JVF1K1XS5ZJKJG6RF2TBXE/emails/01M3JVF1N27AFJFA6A0YVC6957

200
{
  "ok": true
}
POST/api/clients/:id/portal-link

Hand them their portal without opening the app. Needs send: the link outlives the key.

Example
POST /api/clients/01M3JVF1K1XS5ZJKJG6RF2TBXE/portal-link

200
{
  "portal_url": "https://app.chalkcrm.com/hub/01M3JVF1N5DQWVXTGYEF6VS5FK"
}
POST/api/clients/:id/archive

Put a customer away. Their history stays.

Example
POST /api/clients/01M3JVF2N07H3CTPDHMCMEJHPG/archive

200
{
  "ok": true
}
PUT/api/clients/:id/sms-line

Which of the business's Quo numbers texts this customer, for a business with more than one: line is the number's name, number or Quo id. Every text to them goes from it until it is changed again.

Example
PUT /api/clients/01M3JVF2N07H3CTPDHMCMEJHPG/sms-line
{ "line": "Paint" }

200
{
  "ok": true,
  "sms_line": "PN2a8Kx01",
  "changed": true
}
POST/api/clients/:id/unarchive

Put them back.

Example
POST /api/clients/01M3JVF2N07H3CTPDHMCMEJHPG/unarchive

200
{
  "ok": true
}

Properties

The job address. Quotes and visits hang off it, not off the person.

GET/api/properties

Addresses on file for the shop.

Example
GET /api/properties

200
[
  {
    "id": "01M3JVF1K2NWZFDP2HE54E9D8J",
    "tenant_id": "ten_flow",
    "client_id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
    "name": null,
    "street1": "14 Pelham Rd",
    "street2": null,
    "city": "Greer",
    "province": "SC",
    ...
  },
  ...
]
GET/api/properties/suggest

Address suggestions as you type: ?q=.

Example
GET /api/properties/suggest?q=14%20Pel

200
[
  {
    "label": "14 Pel 99444-14, Duhok, Duhok 42001",
    "street1": "14 Pel 99444-14",
    "city": "Duhok",
    "province": "Duhok",
    "postal_code": "42001",
    "lat": null,
    "lng": null
  },
  ...
]
POST/api/properties

Add a property to a customer: client_id, street1, city, province, postal_code.

Example
POST /api/properties#spare2
{
  "client_id": "01M3JVF2N07H3CTPDHMCMEJHPG",
  "street1": "3 Old Rd",
  "city": "Greer",
  "province": "SC",
  "postal_code": "29650"
}

201
{
  "id": "01M3JVF2N94FESK489YH4S86H2"
}
PATCH/api/properties/:id

Fix an address, gate note or geo.

Example
PATCH /api/properties/01M3JVF27NYHM2G15CENR5J1SS
{
  "gate_code": "4411"
}

200
{
  "ok": true
}
POST/api/properties/:id/archive

Put an address away.

Example
POST /api/properties/01M3JVF2N94FESK489YH4S86H2/archive

200
{
  "ok": true
}
POST/api/properties/:id/unarchive

Put it back.

Example
POST /api/properties/01M3JVF2N94FESK489YH4S86H2/unarchive

200
{
  "ok": true
}
DELETE/api/properties/:id

Delete an address nothing hangs off. One with work on it archives instead.

Example
DELETE /api/properties/01M3JVF2N94FESK489YH4S86H2

200
{
  "ok": true
}

Leads

The funnel from first enquiry to a quote. Move a card, or turn a yes into an estimate. An estimate visit is a visit with kind: "assessment" (Schedule).

GET/api/requests

Leads on the board. ?status=, ?source=, ?from=/?to= (YYYY-MM-DD, the shop's own days in its time zone; to is the first day left out), ?archived=1.

Example
GET /api/requests

200
[
  {
    "id": "01M3JVF27ZWWRNNSY20Y3G8DZX",
    "tenant_id": "ten_flow",
    "client_id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
    "property_id": "01M3JVF27NYHM2G15CENR5J1SS",
    "title": "Fence staining estimate",
    "details": "About 200 ft of wood privacy fence, both sides.",
    "source": "website",
    "status": "new",
    ...
  }
]
GET/api/requests/pipeline

The funnel columns, with cards in each.

Example
GET /api/requests/pipeline

200
{
  "stages": [
    {
      "id": "new_lead",
      "label": "New lead",
      "color": "#2b8ba3",
      "kind": "open",
      "cards": ...
    },
    ...
  ],
  "stats": {
    "needs_action": 0,
    "quotes_out_cents": 0,
    "quotes_out_count": 0,
    "won_this_month_cents": 0,
    "new_this_week": 1
  },
  "next_up": [
    {
      "id": "01M3JVF27ZWWRNNSY20Y3G8DZX",
      "tenant_id": "ten_flow",
      "client_id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
      "property_id": "01M3JVF27NYHM2G15CENR5J1SS",
      "title": "Fence staining estimate",
      ...
    },
    ...
  ]
}
GET/api/requests/:id

One lead, with the thread around it.

Example
GET /api/requests/01M3JVF27ZWWRNNSY20Y3G8DZX

200
{
  "tags": [],
  "request": {
    "id": "01M3JVF27ZWWRNNSY20Y3G8DZX",
    "tenant_id": "ten_flow",
    "client_id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
    "property_id": "01M3JVF27NYHM2G15CENR5J1SS",
    "title": "Fence staining estimate",
    "details": "About 200 ft of wood privacy fence, both sides.",
    ...
  },
  "client": {
    "id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
    "tenant_id": "ten_flow",
    "first_name": "Dale",
    "last_name": "Harmon",
    "company_name": "Harmon Rentals",
    "is_company": 0,
    ...
  },
  "property": {
    "id": "01M3JVF27NYHM2G15CENR5J1SS",
    "tenant_id": "ten_flow",
    "client_id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
    "name": null,
    "street1": "22 Suber Rd",
    "street2": null,
    ...
  },
  "fallback_property": null,
  "quotes": [],
  ...
}
POST/api/requests

File a new enquiry: client_id, optional property_id, title, source, details. From a Facebook lead form (Make, Zapier), also send what Meta hands over: meta_lead_id (Meta's lead id, 15 to 17 digits, as a string), and optionally meta_form_id, meta_ad_id (digits, as strings) and meta_lead_created_at (ISO 8601 or unix seconds). A malformed one never refuses the lead: it is saved without that field, and the answer carries a warnings list saying which and why. The lead ingest (POST /api/ingest/lead) takes the same four fields. They are what lets Meta Conversions tell Facebook how the lead got on; a lead with no Meta lead id is never sent. Optional line, as on POST /api/clients: it is set on the customer only when they have no number yet.

Example
POST /api/requests#3
{
  "client_id": "01M3JVF2N07H3CTPDHMCMEJHPG",
  "title": "Porch, maybe"
}

201
{
  "id": "01M3JVF2NH3ZW4REBDWZG0H2X2"
}

POST /api/requests
{
  "client_id": "01M3JVF2N07H3CTPDHMCMEJHPG",
  "title": "Deck stain",
  "source": "Facebook Lead Ad",
  "meta_lead_id": "1234567890123456",
  "meta_form_id": "987654321098765",
  "meta_ad_id": "120210000000000000",
  "meta_lead_created_at": "2026-10-04T14:05:00Z"
}

201
{
  "id": "01M3JVF2NJ8Q4MWK2CZT6R0B7D"
}
PATCH/api/requests/:id

Move it, rename it, change the stage. Also takes the four meta_ fields, so a Meta lead id can be added after the lead was filed.

Example
PATCH /api/requests/01M3JVF27ZWWRNNSY20Y3G8DZX
{
  "title": "Fence staining, both sides"
}

200
{
  "ok": true
}
POST/api/requests/:id/convert

Turn a yes into a quote.

Example
POST /api/requests/01M3JVF2N67WZGHK7TRR9NKR9C/convert

201
{
  "quote_id": "01M3JVF2N7SVS0KRM3JT64QTRK",
  "number": 3
}
POST/api/requests/:id/tie

Put one of the customer's quotes or jobs that is on no lead onto this lead. Send quote_id or job_id. A quote brings its jobs, a job brings its quote. Refused for another customer's record, one already on another lead, or anything archived. The card moves forward to match (Won for a job, an approval or a deposit paid in full), with no webhook.

Example
POST /api/requests/01M3JVF2N67WZGHK7TRR9NKR9C/tie
{
  "quote_id": "01M3JVF2N7SVS0KRM3JT64QTRK"
}

200
{
  "ok": true,
  "already": false,
  "quote_ids": ["01M3JVF2N7SVS0KRM3JT64QTRK"],
  "job_ids": [],
  "moved": true,
  "stage": { "key": "quoted", "label": "Quoted" },
  "words": "Tied quote #3 to this lead, which moved to Quoted."
}
POST/api/requests/:id/archive

Take it off the board.

Example
POST /api/requests/01M3JVF2NH3ZW4REBDWZG0H2X2/archive

200
{
  "ok": true
}
POST/api/requests/:id/unarchive

Put it back on the board.

Example
POST /api/requests/01M3JVF2NH3ZW4REBDWZG0H2X2/unarchive

200
{
  "ok": true
}
DELETE/api/requests/:id

Delete a lead nothing hangs off.

Example
DELETE /api/requests/01M3JVF2NH3ZW4REBDWZG0H2X2

200
{
  "ok": true
}
GET/api/requests/marketing

Where leads come from and how far they get: the funnel and each source.

Example
GET /api/requests/marketing

200
{
  "funnel": {
    "leads": 3,
    "contacted": 2,
    "quoted": 2,
    "won": 1,
    "lost": 0
  },
  "sources": [
    {
      "source": "website",
      "leads": 1,
      "won": 1,
      ...
    },
    ...
  ],
  "weekly": [
    {
      "weeks_ago": 7,
      "leads": 0
    },
    ...
  ],
  "speed": {
    "avg_days_to_quote": 1.7248094081878662e-06,
    "avg_days_to_win": 1.851934939622879e-06
  }
}

Quotes

The whole estimate loop: draft from the price book, send the link, watch them sign, turn it into a job. A measured line is quantity on a measurement, priced per unit. Crew pay can come from a price-book measurement, or be put straight on the line (see Crew pay on a line), and so can what the line costs you (see What a line costs). A quote can carry a timed offer that counts down on the customer's page (see A timed offer on a quote). A line can offer tiers, each with its own price, for the customer to pick one (see Tiers on one line). A line can carry optional add-ons the customer ticks under it (see Add-ons on a line). A quote can carry two to four options the customer picks one of, and stays one quote (see Options inside one quote). Shop must have measurements on for measured lines.

GET/api/quotes

Estimates in the shop, newest first. ?status=, ?client_id=, ?from=/?to= (a YYYY-MM-DD is the shop's own day in its time zone, to the first day left out; a full timestamp is used as is), ?limit= (up to 300), ?before= for the next page.

Example
GET /api/quotes?limit=20

200
[
  {
    "id": "01M3JVF2AVEKN7S8Q00X6G7E05",
    "tenant_id": "ten_flow",
    "client_id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
    "property_id": "01M3JVF27NYHM2G15CENR5J1SS",
    "request_id": "01M3JVF27ZWWRNNSY20Y3G8DZX",
    "number": 1,
    "title": "Fence staining - 200 ft",
    ...
  }
]
GET/api/quotes/:id

One quote. line_items[] each carry their own measures[] and crew pay nested under them, so you can send them straight back on PATCH. Each line also carries unit_cost_cents, cost_breakdown[] (its named cost items), line_cost_cents (what it adds to materials) and materials_from (cost_breakdown, unit_cost, or price_book when the price book's material rules buy for it). line_item_measures is the same measurements as one flat list. cost_preview is the shop's cost card (crew pay, materials, overhead): materials_cents is price_book_materials_cents plus line_materials_cents. quote.timed_discount is the timed offer (active, off_cents, until, remaining_ms, countdown, portal_total_cents), and discounts[] every discount, each with active and off_cents. A quote with options also returns options (each with its own totals and deposit), recommended_option, options_pick ("one", or "many" when the customer may take several), chosen_option (one key, the first taken), chosen_options (every key taken, in option order; [] until a pick) and shown_option, and each line its quote_option and link_key; all null on a quote with none (see Options inside one quote). opens is every time the customer opened it, by kind of device: { count, phone, tablet, computer, capped, last_at, last_device, last_app, recent[] }, where recent is the newest 50 as { at, device, app }, device is phone, tablet or computer, and app names an in-app browser (facebook, messenger, instagram, tiktok, linkedin, google) or is null. Only opens after it was sent, never the office looking (Preview, See what they see, or any browser signed in to the shop), and a reload on the same kind of device within 30 minutes counts once. At most 200 are kept (capped: true). No address or browser details are stored. null before opens were tracked. Pay and cost are left out for a key whose person has Job prices off.

Example
GET /api/quotes/01J...

200
{
  "quote": { "id": "01J...", "number": 1, "status": "draft", "total_cents": 70000, ... },
  "line_items": [
    { "id": "01J...", "name": "Fence staining", "quantity": 1, "unit_price_cents": 70000, "total_cents": 70000,
      "measures": [ { "id": "01J...", "product_measure_id": null, "label": "Fence", "unit": "ln ft", "quantity": 200,
                     "unit_price_cents": 350, "unit_cost_cents": 0, "pay_per_unit_cents": 100, "split_mode": "split", "pay_set": 1 } ],
      "crew_pay_cents": null, "pay_per_unit_cents": null, "split_mode": null }
  ],
  "line_item_measures": [ ... ],
  "cost_preview": { "revenue_cents": 70000, "measurement_pay_cents": 20000, ... },
  ...
}
GET/api/quotes/:id/materials

What the job will take: the price book's materials for measured lines (source: "price_book", rounded to packs), then each other line's own cost items (source: "line"; the same item on several lines is one row, and lines names them; a line with only unit_cost_cents is one row named after it). Only lines that count (an extra once taken). total_cost_cents is the cost card's materials_cents. The prices are for the owner and admins; any other key gets the list without money.

Example
GET /api/quotes/01J.../materials

200
{
  "materials": [
    { "name": "EXPERT Stain & Seal", "unit_label": "5-gal pail", "used": 3, "buy": 3, "packs": 0, "pack_size": 0,
      "cost_cents": 35700, "source": "line", "unit_cost_cents": 11900, "lines": [ "Fence staining" ] },
    { "name": "Brushes and rollers", "unit_label": "kit", "used": 1, "buy": 1, "cost_cents": 1800, "source": "line", ... },
    { "name": "Gate", "unit_label": "each", "used": 2, "buy": 2, "cost_cents": 2400, "source": "line", "unit_cost_cents": 1200, ... }
  ],
  "total_cost_cents": 39900,
  "price_book_cost_cents": 0,
  "line_cost_cents": 39900
}
GET/api/quotes/:id/pdf

The PDF the customer sees. No crew pay or cost on it. A quote with options prints one: the chosen one, else the recommended one, else the first, with its own lines, totals and deposit, and names the others with their totals.

Example
GET /api/quotes/01M3JVF2AVEKN7S8Q00X6G7E05/pdf

200
(PDF, 2620 bytes)
GET/api/payroll/quotes/:id/cost

The shop's cost card for a quote: crew pay, materials, overhead, what is left. Needs a key whose person sees pay (owner, admin, office).

Example
GET /api/payroll/quotes/01M3JVF2AVEKN7S8Q00X6G7E05/cost

200
{
  "revenue_cents": 73625,
  "materials_cents": 0,
  "linked_expenses_cents": 0,
  "measurement_pay_cents": 23000,
  "salesperson_cents": 0,
  "revenue_split_cents": 0,
  "overhead_cents": 0,
  "fixed_job_cost_cents": 0,
  "cost_cents": 23000,
  "profit_before_profit_splits_cents": 50625
}
POST/api/quotes

Draft with line_items[]. Each line may include product_id and measures[] (product_measure_id, label, unit, quantity, optional unit_price_cents). Crew pay copies from the price book, or goes straight on the line: measures[].pay_per_unit_cents, split_mode, unit_cost_cents, or on a plain line crew_pay_cents or pay_per_unit_cents (owner or admin key). What the line costs you: unit_cost_cents, and/or cost_breakdown[] of named items (name, quantity, unit, unit_cost_cents; see What a line costs). Discounts as on PATCH, including a timed offer: timed_discount_kind ("amount" or "percent"), timed_discount_cents or timed_discount_bp, timed_discount_hours with timed_discount_unit ("hours", "days", "weeks", "months"; up to 24 months) and timed_discount_reason (see A timed offer on a quote). A line may be one tier of a line the customer picks from: choice_group, with recommended on the default tier (see Tiers on one line). Or an add-on of the line above: addon: true (see Add-ons on a line). Options the customer picks one of: options (two to four { key, label }) and recommended_option, with each line's quote_option and link_key; options_pick: "many" lets them take several (see Options inside one quote). chosen_options is refused here: a new quote is a draft, approved once it is made. Starts as a draft. Without request_id it stays on no lead as a draft; when it is first sent it joins the customer's lead, only when exactly one open lead fits (same property, came in before the quote).

Example
POST /api/quotes
{
  "client_id": "cli_...",
  "property_id": "prop_...",
  "title": "Fence staining - 200 ft",
  "line_items": [
    {
      "name": "Fence staining",
      "description": "Clean, brighten and stain both sides",
      "measures": [
        { "label": "Fence", "unit": "ln ft", "quantity": 200,
          "unit_price_cents": 350, "pay_per_unit_cents": 100 }
      ]
    }
  ]
}

201
{ "id": "01J...", "number": 1, "subtotal_cents": 70000, "discount_cents": 0, "tax_cents": 0, "total_cents": 70000, "updated_at": "..." }
PATCH/api/quotes/:id

Same nested lines, including measures[]. Send back what GET gave you: read-only keys (id, total_cents, sort_order) ride along. A line or measurement sent without its pay keeps the pay it had, and a line sent without unit_cost_cents or cost_breakdown keeps its cost (cost_breakdown: [] clears the list), while it is the same line: sent with its id from GET, it is that line while it is the same price-book item (product_id) with the same name or one sharing a word. A line picked again from the price book, or retyped as other work, is not taken for that line by its id: it is matched the way a line sent without an id is (by its name and price-book item, or the same place with the same unit, price and quantity), and starts clean when nothing matches. Its measures[] are its own: send them, or a line known by its id gets back the measurements it had. Change extras, deposit or terms. Tiers and add-ons as on POST (choice_group, addon; see Tiers on one line and Add-ons on a line); each save tidies them. Options as on POST (options, recommended_option, options_pick, each line's quote_option and link_key); options_pick left out keeps what is stored, and it is fixed once the quote is decided; line_items replaces every line in every option, and lines where none says its option, on a quote with options, are a 409 with stale: true and nothing changed (see Options inside one quote). option (or chosen_options, a list, on a pick-many quote) goes with status: "approved": the ones the customer chose. Without that status either is a 400. One discount: discount_cents and discount_reason. A timed offer: the timed_discount_* fields; timed_discount_kind: null takes it off, and a new kind, length or unit starts its clock again. Several: discounts[], each with its own reason, and "timed": true with hours and unit for a timed one, or "unit": "date" with an until for one that ends on a set day. They stack: each percent is of the work before any discount. Not both in one call. A converted quote is sealed; the 400 names the job to edit instead. Any other field is a 400 that names it. To be sure you are not writing over somebody else's change, send base_updated_at: exactly the updated_at you read (from GET, or from your last save's answer). If the quote has changed since, or the stamp is not one this quote had, the answer is a 409 and nothing is written; read it again and resend.

Example
PATCH /api/quotes/01J...
{
  "title": "Fence staining - 200 ft, both sides",
  "line_items": [ ...the line_items from GET, changed... ],
  "discounts": [ { "kind": "percent", "bp": 500, "reason": "Neighbor" } ]
}

200
{ "ok": true, "subtotal_cents": 77500, "discount_cents": 3875, "tax_cents": 0, "total_cents": 73625, "updated_at": "..." }
PUT/api/quotes/:id/lines/:lineId/crew-pay

Crew pay on one line, without sending every line back. pay_per_unit_cents (per unit of the line or its measurement) or crew_pay_cents (flat, plain lines), optional split_mode, and measure_id on a line measured two ways. 0 takes it off. Owner or admin key. Line ids change on every full save: read them from GET first.

Example
PUT /api/quotes/01M3JVF2AVEKN7S8Q00X6G7E05/lines/01M3JVF2BHSS8QWFSJQFYE63DX/crew-pay
{
  "crew_pay_cents": 3000
}

200
{
  "ok": true,
  "line_item_id": "01M3JVF2BHSS8QWFSJQFYE63DX",
  "name": "Gate",
  "unit": "each",
  "quantity": 1,
  "pay_per_unit_cents": null,
  "crew_pay_cents": 3000,
  "split_mode": "split",
  "crew_pay_total_cents": 3000,
  "summary": "Crew pay on Gate: $30.00 flat",
  "measure_id": null
}
PUT/api/quotes/:id/lines/:lineId/cost

What one line costs you, without sending every line back: cost_breakdown (the named items; [] clears it) and/or unit_cost_cents. Both sent must agree. Answers the line and the new cost_preview. The owner or an admin. A line the price book buys for, or a converted quote, is a 400 that says why.

Example
PUT /api/quotes/01J.../lines/01J.../cost
{
  "cost_breakdown": [ { "name": "Post caps", "quantity": 2, "unit": "each", "unit_cost_cents": 1200 } ]
}

200
{
  "ok": true,
  "line_item_id": "01J...",
  "name": "Gate",
  "quantity": 2,
  "unit": "each",
  "unit_cost_cents": 1200,
  "cost_breakdown": [ { "id": "01J...", "name": "Post caps", "quantity": 2, "unit": "each", "unit_cost_cents": 1200, "total_cost_cents": 2400 } ],
  "line_cost_cents": 2400,
  "materials_from": "cost_breakdown",
  "summary": "Materials on Gate: Post caps, 2 x each at $12.00 = $24.00",
  "cost_preview": { "materials_cents": 39900, "cost_cents": 90900, "profit_before_profit_splits_cents": 119100, ... }
}
POST/api/quotes/:id/send

Body { email: true, sms: true } to send both. Empty body uses the shop default (email) and 400s if the client has no email. { email: false, sms: true } is SMS-only. Office also accepts { channel, to, message }, where channel is "sms", "email" or "both". With "both", each channel takes its own optional sms_to / email_to (else the one on file) and its own optional sms_message / email_message (else the shop's text or email wording), with the same customer link, and the answer's sent lists each channel with status sent, queued or failed (a text that had to go by email instead is failed). sms_to must be a phone number and email_to an email address; both go with "both" only. With "both", a single to, or a message without message_channel, is answered 400. Uses tpl_quote_sms for the body and tpl_quote_email_subject for the email subject. May also carry the discount fields, checked as on PATCH. A timed offer's clock starts now. Needs send. A text to a number marked wrong (a call logged as "Phone number is incorrect", or marked on the client page) is answered 409 and nothing is sent or changed, unless you send confirm_wrong_number: true with wrong_number_seen set to the 409's wrong_number.seen; the 409 carries wrong_number (the number, when it was marked, by whom, and seen) and confirm_with. The yes covers the marks it names and no more: a number marked again later, or another number, is asked again, so an integration that always sends the yes never texts a newly marked number by itself. Email is never held. Send a new Idempotency-Key with the yes (the body changed). With { email: true, sms: true } the whole send waits, so it never goes half sent; send sms: false to send the email alone. The answer carries saved_email only when the send saved an address as the customer's email: an email typed for a customer with none on file, never the shop's or a team member's address, and never one that had failed or been blocked by the time the send answered. Only a person sending from the app saves one; a send made with an API key never saves an address, so its answer has no saved_email.

Example
POST /api/quotes/01M3JVF2AVEKN7S8Q00X6G7E05/send
{
  "email": true,
  "sms": false
}

200
{
  "ok": true,
  "hub_url": "https://app.chalkcrm.com/hub/01M3JVF2CAC3VHWJMBFFXDGNNS",
  "app_url": "https://app.chalkcrm.com/quotes/01M3JVF2AVEKN7S8Q00X6G7E05",
  "channel": "email",
  "to": "dale@example.com"
}
POST/api/quotes/:id/link

Mint the public link without sending it. Returns { hub_url, app_url }. hub_url is the customer portal. app_url is the office page https://app.chalkcrm.com/quotes/:id. Needs send: the link outlives the key.

Example
POST /api/quotes/01M3JVF2AVEKN7S8Q00X6G7E05/link

200
{
  "hub_url": "https://app.chalkcrm.com/hub/01M3JVF2CAC3VHWJMBFFXDGNNS",
  "app_url": "https://app.chalkcrm.com/quotes/01M3JVF2AVEKN7S8Q00X6G7E05"
}
DELETE/api/quotes/:id/link

Take the public link back: the customer's copy stops opening.

Example
DELETE /api/quotes/01M3JVF2CQ9FYR26B9EDAT0549/link

200
{
  "ok": true,
  "revoked": 1
}
POST/api/quotes/:id/invoice

Bill an approved quote straight away, with no job. Only for shops on the Simple workflow; others convert first. Owner or admin key. On a quote with options the invoice carries only the chosen option's lines (on a pick-many quote, every option taken, billed to the cent of the approved total); option, or chosen_options on a pick-many quote, chooses when none is chosen yet, and with neither the answer is the same 409 as approve.

Example
POST /api/quotes/01M3JVF2VE3WQM73HQ0JJY5PYF/invoice

201
{
  "invoice_id": "01M3JVF2VNKDD0N2Q0926JRSRY",
  "reused": false
}
POST/api/quotes/:id/mark-sent

Mark it sent when you handed it over some other way. Starts the follow-up clock, and a timed offer's clock.

Example
POST /api/quotes/01M3JVF2CQ9FYR26B9EDAT0549/mark-sent

200
{
  "ok": true,
  "hub_url": "https://app.chalkcrm.com/hub/01M3JVF2NNPV6MJH6FXS0PTDA4"
}
POST/api/quotes/:id/approve

Mark it signed from the office. On a quote with options send option, the key of the one the customer chose, or on a pick-many quote chosen_options, every key they took (["a", "c"]); with none chosen yet and none sent, the answer is a 409 with choose_option: true, options_pick and options. Several keys on a pick-one quote, a key that is not an option, an empty list, or both fields at once is a 400 naming the field. The quote then adds up as every option taken, the bill worked out once over all of them (see Options inside one quote).

Example
POST /api/quotes/01M3JVF2VE3WQM73HQ0JJY5PYF/approve
{
  "chosen_options": ["a", "c"]
}

200
{
  "ok": true
}
POST/api/quotes/:id/convert

Turn an approved quote into a job. The job keeps the lines, the measurements, the crew pay, and each line's cost and cost items it was sold with. crew_pay_cents is what the crew is owed, waiting as "Crew" until somebody is on a visit. The customer's lead goes to Won; a quote with no lead first joins the customer's one fitting open lead (same rule as creating a quote), and with none or several it is left alone. On a quote with options the job carries only the chosen option's lines (on a pick-many quote, every option taken, in option order); option, or chosen_options on a pick-many quote, chooses when none is chosen yet, and with neither the answer is the same 409 as approve.

Example
POST /api/quotes/01M3JVF2AVEKN7S8Q00X6G7E05/convert

201
{
  "job_id": "01M3JVF2D4HZ9B61Q6VK4SG6SY",
  "crew_pay_cents": 23000,
  "expense_cents": 0
}
POST/api/quotes/:id/duplicate

Copy last year's deck job as a starting point. Crew pay and cost items set on the lines come too, and so do the options (and options_pick), each line in its own; the copy starts with none chosen.

Example
POST /api/quotes/01M3JVF2AVEKN7S8Q00X6G7E05/duplicate

201
{
  "id": "01M3JVF2CQ9FYR26B9EDAT0549",
  "number": 2
}
POST/api/quotes/:id/options

Add an option inside the quote: { label, copy_from }, both optional. A quote with no options becomes one with two, its lines Option A. copy_from (an option's key, "a" on a quote that had none) fills the new one with a linked copy of that option's lines; left out, it starts empty. Up to four, while the quote is a draft, waiting on the customer, or with changes asked; options_pick stays as it was. Answers the new key and label, copied_lines, and every option with its totals (see Options inside one quote).

Example
POST /api/quotes/01M3JVF2AVEKN7S8Q00X6G7E05/options
{
  "label": "Full restoration",
  "copy_from": "a"
}

201
{
  "key": "b",
  "label": "Full restoration",
  "copied_lines": 2,
  "options": [
    { "key": "a", "label": "Option A", "shown": true, "recommended": true, "chosen": false, "lines": 2, "subtotal_cents": 120000, "discount_cents": 0, "tax_cents": 0, "total_cents": 120000, "deposit_cents": 0 },
    { "key": "b", "label": "Full restoration", "shown": false, "recommended": false, "chosen": false, "lines": 2, "subtotal_cents": 120000, "discount_cents": 0, "tax_cents": 0, "total_cents": 120000, "deposit_cents": 0 }
  ]
}
POST/api/quotes/:id/archive

Take it off the live list.

Example
POST /api/quotes/01M3JVF2CQ9FYR26B9EDAT0549/archive

200
{
  "ok": true
}
POST/api/quotes/:id/unarchive

Put it back.

Example
POST /api/quotes/01M3JVF2CQ9FYR26B9EDAT0549/unarchive

200
{
  "ok": true
}
DELETE/api/quotes/:id

Delete a quote nothing hangs off. A quote with a job or money on it archives instead.

Example
DELETE /api/quotes/01M3JVF2NQADYTE27QN5Z64QYF

200
{
  "ok": true
}

Jobs

Won work. Finish it, then bill it from the same record.

GET/api/jobs

Jobs on the books, newest first. ?status=, ?client_id=, ?archived=1, ?limit= (up to 300) and ?before= for the next page.

Example
GET /api/jobs?limit=20

200
[
  {
    "id": "01M3JVF2D4HZ9B61Q6VK4SG6SY",
    "tenant_id": "ten_flow",
    "client_id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
    "property_id": "01M3JVF27NYHM2G15CENR5J1SS",
    "quote_id": "01M3JVF2AVEKN7S8Q00X6G7E05",
    "request_id": "01M3JVF27ZWWRNNSY20Y3G8DZX",
    "number": 1,
    ...
  }
]
GET/api/jobs/:id

One job, with visits, invoices, expenses, time, payouts and costing (the profit card: revenue, labor, technician pay, materials, fees, overhead, profit). costing.estimated_materials_cents is "Estimated materials (from quote)": the lines' own costs, counted while no materials receipt is logged. Once one is, materials_receipts_cents are the materials and materials_vs_estimate_cents says how they compare (above 0 is over). Never both. Lines nest their measurements, crew pay and cost items, as on quotes. A key whose person has Job prices off gets the crew's view: the work, no money.

Example
GET /api/jobs/01J...

200
{
  "job": { "id": "01J...", "number": 1, "status": "scheduled", "total_cents": 70000, ... },
  "line_items": [ { "name": "Fence staining", "measures": [ { "quantity": 200, "pay_per_unit_cents": 100, ... } ], ... } ],
  "visits": [ ... ],
  "payouts": [ { "payee_name": "Pete Barnes", "amount_cents": 20000, "pay_kind": "measurement", "status": "pending", ... } ],
  "costing": { "revenue_cents": 70000, "payout_cents": 20000, "pay_technician_cents": 20000, "profit_cents": 50000, ... },
  ...
}
POST/api/jobs

Open a job without a quote, if you need to. Same line_items[] as quotes, crew pay included. starts_on with assignees books its visits in the same call. Send request_id to put it on a lead (the lead goes to Won); with quote_id it takes the quote's lead. A job with neither is never put on a lead by guesswork.

Example
POST /api/jobs#doomed
{
  "client_id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
  "property_id": "01M3JVF27NYHM2G15CENR5J1SS",
  "title": "Made by mistake"
}

201
{
  "id": "01M3JVF2RTAXSFAJZE6Q4REJZD",
  "number": 3,
  "visit_ids": [],
  "hours": null
}
PATCH/api/jobs/:id

Change title, instructions, status, dates, line_items[] (same lines as quotes) or discount_cents. Charges can grow after billing but never drop below what is already invoiced. Lines sent back without their crew pay keep the pay the job was sold with; only an owner or admin key changes it. Lines sent back without their cost keep it too. A job keeps one discount amount: discount_reason goes in the job history. The crew is set on each visit. Any other field is a 400 that names it.

Example
PATCH /api/jobs/01M3JVF2D4HZ9B61Q6VK4SG6SY
{
  "instructions": "Gate code 4411. Dog in back yard."
}

200
{
  "ok": true
}
PUT/api/jobs/:id/lines/:lineId/crew-pay

Crew pay on one line of a sold job. Same body as the quote one. What the crew is owed is worked out again right away: paid and held money stays as it is, and anything more is owed as its own row. Owner or admin key.

Example
PUT /api/jobs/01M3JVF2D4HZ9B61Q6VK4SG6SY/lines/f9925d5f09c7632f25670d57a709da9a/crew-pay
{
  "pay_per_unit_cents": 110,
  "split_mode": "split"
}

200
{
  "ok": true,
  "line_item_id": "f9925d5f09c7632f25670d57a709da9a",
  "name": "Fence staining",
  "unit": "ln ft",
  "quantity": 200,
  "pay_per_unit_cents": 110,
  "crew_pay_cents": null,
  "split_mode": "split",
  "crew_pay_total_cents": 22000,
  "summary": "Crew pay on Fence staining: $1.10/ln ft x 200 = $220.00",
  "measure_id": "d35d13ebd17b8099255784115ea36b94"
}
PUT/api/jobs/:id/lines/:lineId/cost

What one line of a job costs you. Same body as the quote one. The profit card and any unpaid profit share follow right away. The owner or an admin.

Example
PUT /api/jobs/01J.../lines/6bf8.../cost
{
  "unit_cost_cents": 38000,
  "cost_breakdown": [
    { "name": "EXPERT Stain & Seal", "quantity": 3, "unit": "5-gal pail", "unit_cost_cents": 12000 },
    { "name": "Brushes and rollers", "quantity": 1, "unit": "kit", "unit_cost_cents": 2000 }
  ]
}

200
{
  "ok": true,
  "name": "Fence staining",
  "unit_cost_cents": 38000,
  "cost_breakdown": [ ... ],
  "line_cost_cents": 38000,
  "materials_from": "cost_breakdown",
  "summary": "Materials on Fence staining: EXPERT Stain & Seal, 3 x 5-gal pail at $120.00; Brushes and rollers, 1 x kit at $20.00 = $380.00",
  ...
}
GET/api/jobs/:id/materials

What to buy for the job: the same list as the quote's, from the job's own lines as sold. The prices are for the owner and admins; the rest of the office gets the list without money, and the field crew gets a 403.

Example
GET /api/jobs/01J.../materials

200
{
  "materials": [ { "name": "EXPERT Stain & Seal", "unit_label": "5-gal pail", "buy": 3, "cost_cents": 35700, "source": "line", ... }, ... ],
  "total_cost_cents": 39900,
  "price_book_cost_cents": 0,
  "line_cost_cents": 39900
}
POST/api/jobs/:id/expenses

What was really bought for the job: items (up to 20), each name, quantity, unit, unit_cost_cents and optional category ("materials" when left out), plus incurred_on, note, reimbursable. One expense row per item. Materials rows replace the quote's estimate on the profit. An item may name a common expense (preset_id) and a stock version (inventory_variant_id); for a role with Inventory on, it takes that stock out, and with no unit the common expense's own unit is used. For a role that can't see job profit, a line that takes stock is priced from the common expense or the stock, whatever cost was sent, and its money is left out of the answer (priced_from_stock: true, no total_cents). With Inventory off, stock is left alone and the answer says so (stock_left, stock_note). Anyone who may log an expense; the materials summary in the answer is for the owner and admins.

Example
POST /api/jobs/01J.../expenses
{
  "items": [
    { "name": "EXPERT Stain & Seal", "quantity": 3, "unit": "5-gal pail", "unit_cost_cents": 18900 },
    { "name": "Gas", "quantity": 1, "unit_cost_cents": 4000, "category": "fuel" }
  ],
  "incurred_on": "2026-09-29"
}

201
{
  "ok": true,
  "expenses": [
    { "id": "01J...", "description": "EXPERT Stain & Seal, 3 x 5-gal pail at $189.00", "amount_cents": 56700, "category": "materials", ... },
    { "id": "01J...", "description": "Gas", "amount_cents": 4000, "category": "fuel", ... }
  ],
  "total_cents": 60700,
  "materials": { "quote_estimate_cents": 39900, "receipts_cents": 56700, "vs_estimate_cents": 16800, "estimated_materials_cents": 0 }
}
POST/api/jobs/:id/complete

Mark the work done.

Example
POST /api/jobs/01M3JVF2D4HZ9B61Q6VK4SG6SY/complete

200
{
  "ok": true,
  "revisit_at": null
}
POST/api/jobs/:id/reopen

Reopen a finished job.

Example
POST /api/jobs/01M3JVF2D4HZ9B61Q6VK4SG6SY/reopen

200
{
  "ok": true,
  "job": {
    "id": "01M3JVF2D4HZ9B61Q6VK4SG6SY",
    "tenant_id": "ten_flow",
    "client_id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
    "property_id": "01M3JVF27NYHM2G15CENR5J1SS",
    "quote_id": "01M3JVF2AVEKN7S8Q00X6G7E05",
    "request_id": "01M3JVF27ZWWRNNSY20Y3G8DZX",
    "number": 1,
    "title": "Fence staining - 200 ft, both sides",
    "instructions": "Gate code 4411. Dog in back yard.",
    ...
  }
}
POST/api/jobs/:id/invoice

Turn the finished job into an invoice. Owner or admin key.

Example
POST /api/jobs/01M3JVF2D4HZ9B61Q6VK4SG6SY/invoice

201
{
  "invoice_id": "01M3JVF2GN2TGWK1TZH91F8DZY"
}
POST/api/jobs/:id/archive

Take it off the live list.

Example
POST /api/jobs/01M3JVF2NW8SGJN2WFQF0WJ6R2/archive

200
{
  "ok": true
}
POST/api/jobs/:id/unarchive

Put it back.

Example
POST /api/jobs/01M3JVF2NW8SGJN2WFQF0WJ6R2/unarchive

200
{
  "ok": true
}
POST/api/jobs/preview-recurrence

See the next visits before you lock a series: recurrence_rule, starts_on.

Example
POST /api/jobs/preview-recurrence
{
  "recurrence_rule": "FREQ=MONTHLY;COUNT=3",
  "starts_on": "2026-10-03"
}

200
{
  "label": "Monthly, 3 times",
  "dates": [
    "2026-10-03",
    ...
  ],
  "truncated": false,
  "unsupported": []
}
POST/api/jobs/:id/cancel-remaining

Cancel the visits still to come on a job.

Example
POST /api/jobs/01M3JVF2NW8SGJN2WFQF0WJ6R2/cancel-remaining

200
{
  "cancelled": 0,
  "ids": []
}
DELETE/api/jobs/:id

Delete a job made by mistake, with nothing billed or paid on it. Owner or admin key.

Example
DELETE /api/jobs/01M3JVF2RTAXSFAJZE6Q4REJZD

200
{
  "ok": true
}

Schedule

Book, move and confirm visits. A visit's assignees is its crew, and who is on it decides who shares the job's crew pay (people set to "By the job").

GET/api/schedule

The calendar for a range: ?from= and ?to= (ISO). Left out, it is the shop's today and the six days after.

Example
GET /api/schedule?from=2026-09-28T00:00:00.000Z&to=2026-10-05T00:00:00.000Z

200
{
  "visits": [
    {
      "id": "775ad5006416134b1a0c674ff7fa2706",
      "tenant_id": "ten_flow",
      "job_id": "01M3JVF2D4HZ9B61Q6VK4SG6SY",
      ...
    },
    ...
  ],
  "unscheduled": [],
  "unscheduled_total": 0,
  "blackouts": [],
  "users": [
    {
      "id": "usr_admin",
      "name": "Jess Rowe",
      "color": "#111",
      ...
    },
    ...
  ],
  "range": {
    "from": "2026-09-28T00:00:00.000Z",
    "to": "2026-10-05T00:00:00.000Z"
  },
  ...
}
GET/api/schedule/my-day

What the key's person is running today.

Example
GET /api/schedule/my-day

200
{
  "date": "2026-09-27",
  "visits": [],
  "running_timer": null,
  "last_lat": null,
  "last_lng": null,
  "last_geo_at": null
}
GET/api/schedule/free

Who is free on a day and half-day window.

Example
GET /api/schedule/free

200
{
  "day": "2026-09-27",
  "window": "afternoon",
  "people": [
    {
      "id": "usr_admin",
      "name": "Jess Rowe"
    },
    ...
  ]
}
GET/api/schedule/blackouts

Days the shop is closed. Do not book over them.

Example
GET /api/schedule/blackouts

200
[]
POST/api/schedule/blackouts

Close the shop for a stretch: starts_at, ends_at, reason.

Example
POST /api/schedule/blackouts
{
  "starts_at": "2026-10-18T04:00:00.000Z",
  "ends_at": "2026-10-19T03:00:00.000Z",
  "reason": "Shop closed"
}

201
{
  "id": "01M3JVF2FJ6ZA0F950F3MG25GK"
}
POST/api/schedule/find-time

Ask for the next open slot that fits: duration_minutes, optional assignees.

Example
POST /api/schedule/find-time
{
  "duration_minutes": 480,
  "assignees": [
    "usr_pete"
  ]
}

200
{
  "slots": [
    {
      "starts_at": "2026-09-28T10:00:00.000Z",
      "ends_at": "2026-09-28T18:00:00.000Z"
    },
    ...
  ],
  "duration_minutes": 480
}
POST/api/schedule/check

See if a time collides before you book it.

Example
POST /api/schedule/check
{
  "starts_at": "2026-09-30T13:00:00.000Z",
  "ends_at": "2026-09-30T21:00:00.000Z",
  "assignees": [
    "usr_pete"
  ]
}

200
{
  "conflicts": [],
  "ok": true,
  "capacity": [],
  "hours": null
}
POST/api/schedule/visits

Put a visit on the board: client_id, property_id, optional job_id or request_id, starts_at, ends_at, assignees, kind (assessment for an estimate visit). A clash answers 409 with the conflicts; send force: true to book anyway.

Example
POST /api/schedule/visits
{
  "client_id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
  "property_id": "01M3JVF27NYHM2G15CENR5J1SS",
  "job_id": "01M3JVF2D4HZ9B61Q6VK4SG6SY",
  "title": "Second coat",
  "starts_at": "2026-10-01T13:00:00.000Z",
  "ends_at": "2026-10-01T17:00:00.000Z",
  "assignees": [
    "usr_pete"
  ],
  "force": true
}

201
{
  "id": "01M3JVF2F24D97CZWC96JNQSBA",
  "capacity": [],
  "hours": null
}
PATCH/api/schedule/visits/:id

Move it, reassign it (assignees), change the window. The crew's pay follows the crew.

Example
PATCH /api/schedule/visits/775ad5006416134b1a0c674ff7fa2706
{
  "starts_at": "2026-09-30T13:00:00.000Z",
  "ends_at": "2026-09-30T21:00:00.000Z",
  "assignees": [
    "usr_pete"
  ],
  "force": true
}

200
{
  "ok": true,
  "capacity": [],
  "hours": null
}
POST/api/schedule/visits/:id/confirm

Tell the customer they are on the board. Needs send. A text to a number marked wrong (a call logged as "Phone number is incorrect", or marked on the client page) is answered 409 and nothing is sent, unless you send confirm_wrong_number: true with wrong_number_seen set to the 409's wrong_number.seen; the 409 carries wrong_number (the number, when it was marked, by whom, and seen) and confirm_with. The yes covers the marks it names and no more: a number marked again later, or another number, is asked again, so an integration that always sends the yes never texts a newly marked number by itself. Email is never held. Send a new Idempotency-Key with the yes (the body changed).

Example
POST /api/schedule/visits/775ad5006416134b1a0c674ff7fa2706/confirm
{
  "channel": "sms"
}

200
{
  "ok": true,
  "channel": "sms",
  "to": "+18645550199",
  "body": "Hi Dale, you are booked in with Upstate Painting Co on Wednesday, September 30 at 9:00 AM for..."
}
POST/api/schedule/visits/:id/on-my-way

Text that the crew is rolling. Needs send.

Example
POST /api/schedule/visits/775ad5006416134b1a0c674ff7fa2706/on-my-way
{
  "minutes": 20
}

200
{
  "ok": true,
  "already_sent": false,
  "minutes": 20,
  "sent_at": "2026-09-28T01:53:26.225Z"
}
POST/api/schedule/visits/:id/complete

The stop is done.

Example
POST /api/schedule/visits/01M3JVF2F24D97CZWC96JNQSBA/complete

200
{
  "ok": true
}
POST/api/schedule/visits/:id/uncomplete

Undo a stop marked done by mistake.

Example
POST /api/schedule/visits/01M3JVF2F24D97CZWC96JNQSBA/uncomplete

200
{
  "ok": true
}
POST/api/schedule/series

Book a repeating visit: job_id, starts_on, recurrence_rule.

Example
POST /api/schedule/series
{
  "job_id": "01M3JVF2NW8SGJN2WFQF0WJ6R2",
  "starts_on": "2026-10-04",
  "recurrence_rule": "FREQ=WEEKLY;COUNT=3",
  "assignees": [
    "usr_pete"
  ],
  "force": true
}

201
{
  "visit_ids": [
    "01M3JVF2P9NGF6RZ44GX5YMJMV",
    ...
  ],
  "count": 3,
  "label": "Weekly, 3 times",
  "pattern": "Weekly, 3 times",
  "truncated": false,
  "hours": null
}
POST/api/schedule/optimize

Reorder the day's stops: date, optional user_id.

Example
POST /api/schedule/optimize
{
  "date": "2026-09-30",
  "user_id": "usr_pete"
}

200
{
  "ordered": [
    "775ad5006416134b1a0c674ff7fa2706",
    ...
  ],
  "without_coordinates": 1,
  "note": "Stops without coordinates were placed last"
}
GET/api/schedule/weather

The forecast for the shop's area, for the days on the board.

Example
GET /api/schedule/weather

200
{
  "place": "",
  "days": []
}
POST/api/schedule/visits/:id/shift-future

Move this visit and the rest of its series by delta_ms (an hour is 3600000).

Example
POST /api/schedule/visits/01M3JVF2P9NGF6RZ44GX5YMJMV/shift-future
{
  "delta_ms": 3600000,
  "force": true
}

200
{
  "updated": 3,
  "notified": false
}
POST/api/schedule/visits/:id/cancel-future

Cancel this visit and the rest of its series.

Example
POST /api/schedule/visits/01M3JVF2P9VVCR45F7F6N17ZSR/cancel-future

200
{
  "cancelled": 2,
  "ids": [
    "01M3JVF2P9VVCR45F7F6N17ZSR",
    ...
  ]
}
POST/api/schedule/visits/bulk

Unschedule or cancel several at once: action (unschedule or cancel) with visit_ids, or a day (and assignee_id, outdoor).

Example
POST /api/schedule/visits/bulk
{
  "action": "unschedule",
  "visit_ids": [
    "01M3JVF2P9NGF6RZ44GX5YMJMV"
  ]
}

200
{
  "ok": true,
  "action": "unschedule",
  "did": [
    "01M3JVF2P9NGF6RZ44GX5YMJMV",
    ...
  ],
  "skipped": []
}
DELETE/api/schedule/visits/:id

Take a visit off for good.

Example
DELETE /api/schedule/visits/01M3JVF2P9NGF6RZ44GX5YMJMV

200
{
  "ok": true
}
POST/api/schedule/blackouts/:id/remove

Open a closed day again.

Example
POST /api/schedule/blackouts/01M3JVF2FJ6ZA0F950F3MG25GK/remove

200
{
  "ok": true
}
GET/api/timers/running

Everyone on the clock right now, across the shop and whatever week their clock started in, oldest first: the punch id, the person, kind (work, drive or break), started_at and the job. No rates. Only when the person the key acts as is the owner or has Spending on Full, the people who may clock others out; anyone else gets a 403.

Example
GET /api/timers/running

200
{
  "running": [
    {
      "id": "01M3JVF2G9NP39GEZNQ3MG54A6",
      "user_id": "usr_dee",
      "name": "Dee Whitfield",
      "color": "#2f7d5b",
      "kind": "work",
      "started_at": "2026-10-29T11:02:00.000Z",
      "job_id": "01M3JVF2CQ9FYR26B9EDAT0549",
      "visit_id": null,
      "job_number": 1042,
      "number_label": null,
      "job_title": "Smith exterior"
    }
  ],
  "now": "2026-10-29T20:12:00.000Z"
}
POST/api/timers/:id/stop

Clock a running punch out now. Your own, or anybody's for the owner or Spending on Full. Send "expect_running": true to get a 409 when it had already ended (somebody else clocked them out first) instead of a quiet already_stopped. A clock that has run for more than a day is a 400: it needs the time they really left, set on Pay in the app. A punch in a locked pay week is a 400. The answer carries ended_at, which Undo sends back. When the owner or somebody with Spending on Full clocks somebody else's punch out, its history says who, and Undo can take it back. Their own clock-out writes that line only with "undoable": true.

Example
POST /api/timers/01M3JVF2G9NP39GEZNQ3MG54A6/stop
{
  "expect_running": true
}

200
{
  "ok": true,
  "seconds": 33000,
  "ended_at": "2026-10-29T20:12:00.000Z"
}
POST/api/timers/:id/undo-stop

Undo a clock-out within a minute of it: the punch runs again from the same start with no end, and its hours and pay are worked out again. Send ended_at, the end the clock-out answered with. The owner or Spending on Full, or a person who set when their own punch ended. A clock-out can be undone when it was made by the owner or somebody with Spending on Full, or was a person setting when their own punch ended; a crew member's own plain clock-out leaves nothing to undo (409). Also a 409 once anything else has happened to the punch (an edit, a different end, the person pressing clock out themselves), when the clock-out changed more than the end, once they are on the clock again or have a newer punch, once their hour or day pay was marked paid, or after the minute. A 400 when its pay week is locked. The clock-out and the undo both stay in the punch's history.

Example
POST /api/timers/01M3JVF2G9NP39GEZNQ3MG54A6/undo-stop
{
  "ended_at": "2026-10-29T20:12:00.000Z"
}

200
{
  "ok": true,
  "id": "01M3JVF2G9NP39GEZNQ3MG54A6",
  "running": true,
  "user_id": "usr_dee",
  "started_at": "2026-10-29T11:02:00.000Z",
  "kind": "work",
  "job_id": "01M3JVF2CQ9FYR26B9EDAT0549"
}

Checklists and forms

The walkthrough on a visit: gate latched, photos taken, customer signed. Templates are the lists; a submission is one filled in.

GET/api/forms/templates

The shop's checklists.

Example
GET /api/forms/templates

200
[]
POST/api/forms/templates

Add one: name, fields[] (label, kind).

Example
POST /api/forms/templates
{
  "name": "Fence walkthrough",
  "fields": [
    {
      "label": "Gate latched",
      "kind": "check"
    }
  ]
}

201
{
  "id": "01M3JVF2FRCAK14ZWGN9785K0W"
}
PATCH/api/forms/templates/:id

Rename one or change its fields.

Example
PATCH /api/forms/templates/01M3JVF2FRCAK14ZWGN9785K0W
{
  "name": "Fence walkthrough, final"
}

200
{
  "ok": true
}
GET/api/forms/visits/:visitId/checklists

The checklists on one visit.

Example
GET /api/forms/visits/775ad5006416134b1a0c674ff7fa2706/checklists

200
[
  {
    "id": "01M3JVF2FSSKTWZRMD7FM4WAT1",
    "template_id": "01M3JVF2FRCAK14ZWGN9785K0W",
    "name": "Fence walkthrough",
    "fields": [
      {
        "label": "Gate latched",
        "kind": "check"
      },
      ...
    ],
    "active": 1,
    "default_for": null
  }
]
POST/api/forms/visits/:visitId/checklists

Put a checklist on a visit: template_id. The office, or somebody on the visit.

Example
POST /api/forms/visits/775ad5006416134b1a0c674ff7fa2706/checklists
{
  "template_id": "01M3JVF2FRCAK14ZWGN9785K0W"
}

201
{
  "ok": true
}
DELETE/api/forms/visits/:visitId/checklists/:id

Take a checklist off a visit. The office only.

Example
DELETE /api/forms/visits/775ad5006416134b1a0c674ff7fa2706/checklists/01M3JVF2FSSKTWZRMD7FM4WAT1

200
{
  "ok": true
}
GET/api/forms/submissions

Filled-in checklists, newest first. ?visit_id=.

Example
GET /api/forms/submissions?visit_id=775ad5006416134b1a0c674ff7fa2706

200
[
  {
    "id": "01M3JVF2FV5J3MGNMS12SJPJ67",
    "tenant_id": "ten_flow",
    "template_id": "01M3JVF2FRCAK14ZWGN9785K0W",
    "visit_id": "775ad5006416134b1a0c674ff7fa2706",
    "job_id": null,
    "answers": {
      "Gate latched": true
    },
    "completed_at": "2026-09-28T01:53:26.011Z",
    "completed_by": "usr_owner",
    ...
  }
]
POST/api/forms/submissions

Fill one in: template_id, visit_id or job_id, answers, completed.

Example
POST /api/forms/submissions
{
  "template_id": "01M3JVF2FRCAK14ZWGN9785K0W",
  "visit_id": "775ad5006416134b1a0c674ff7fa2706",
  "answers": {
    "Gate latched": true
  },
  "completed": true
}

201
{
  "id": "01M3JVF2FV5J3MGNMS12SJPJ67"
}

Invoices and money

Bill, chase and see what landed. Writing down a check is in. You can archive an invoice, or delete an unpaid one with no payments. Paid invoices archive. They do not delete. Charging a saved card, refunds and write-offs need write on Payments and money.

GET/api/invoices

Invoices, newest first. ?status= (unpaid is everything still owed, including a draft that has taken a payment: its status stays draft, it was never sent, so never chase it), ?archived=1, ?limit= and ?before=.

Example
GET /api/invoices?limit=20

200
[
  {
    "id": "01M3JVF2GN2TGWK1TZH91F8DZY",
    "tenant_id": "ten_flow",
    "client_id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
    "property_id": "01M3JVF27NYHM2G15CENR5J1SS",
    "job_id": "01M3JVF2D4HZ9B61Q6VK4SG6SY",
    "number": 1,
    "subject": "Fence staining - 200 ft, both sides",
    ...
  }
]
GET/api/invoices/aging

Who is late, for chase copy. not_sent is what is left on drafts that have taken a payment: owed, never sent, so never late and never chased. It is in total_cents, and those drafts are in invoices with status draft.

Example
GET /api/invoices/aging

200
{
  "buckets": {
    "current": 0,
    "d1_30": 0,
    "d31_60": 0,
    "d61_90": 0,
    "d90_plus": 0,
    "not_sent": 0
  },
  "total_cents": 0,
  "invoices": []
}
GET/api/invoices/:id

One invoice, with payments. Lines nest their measurements as on quotes. An invoice never carries crew pay of its own: the crew is paid from the job. opens is every time the customer opened it, as on a quote, by kind of device: { count, phone, tablet, computer, capped, last_at, last_device, last_app, recent[] }, where recent is the newest 50 as { at, device, app }, device is phone, tablet or computer, and app names an in-app browser (facebook, messenger, instagram, tiktok, linkedin, google) or is null. Only opens after it was sent, never the office looking (Preview, See what they see, or any browser signed in to the shop), and a reload on the same kind of device within 30 minutes counts once. At most 200 are kept (capped: true). No address or browser details are stored. null before opens were tracked.

Example
GET /api/invoices/01M3JVF2GN2TGWK1TZH91F8DZY

200
{
  "invoice": {
    "id": "01M3JVF2GN2TGWK1TZH91F8DZY",
    "tenant_id": "ten_flow",
    "client_id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
    "property_id": "01M3JVF27NYHM2G15CENR5J1SS",
    "job_id": "01M3JVF2D4HZ9B61Q6VK4SG6SY",
    "number": 1,
    "subject": "Fence staining - 200 ft, both sides",
    ...
  },
  "line_items": [
    {
      "id": "5d3c608e201069bd3ccb322ecb88c589",
      "tenant_id": "ten_flow",
      "parent_type": "invoice",
      ...
    },
    ...
  ],
  "line_item_measures": [
    {
      "id": "964c50b4680d215a53aaadb13c08b45d",
      "tenant_id": "ten_flow",
      "line_item_id": "5d3c608e201069bd3ccb322ecb88c589",
      ...
    },
    ...
  ],
  "payments": [],
  "notes": [],
  "property": {
    "id": "01M3JVF27NYHM2G15CENR5J1SS",
    "tenant_id": "ten_flow",
    "client_id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
    "name": null,
    "street1": "22 Suber Rd",
    "street2": null,
    "city": "Greer",
    ...
  },
  "attachments": [],
  ...
}
GET/api/invoices/:id/pdf

The bill as a PDF.

Example
GET /api/invoices/01M3JVF2GN2TGWK1TZH91F8DZY/pdf

200
(PDF, 2989 bytes)
GET/api/invoices/:id/receipt.pdf

The receipt after it is paid.

Example
GET /api/invoices/01M3JVF2GN2TGWK1TZH91F8DZY/receipt.pdf

200
(PDF, 3691 bytes)
POST/api/invoices

Write an invoice by hand: client_id, property_id, line_items[].

Example
POST /api/invoices#plan
{
  "client_id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
  "property_id": "01M3JVF27NYHM2G15CENR5J1SS",
  "line_items": [
    {
      "name": "Deck",
      "quantity": 1,
      "unit_price_cents": 300000
    }
  ]
}

201
{
  "id": "01M3JVF2TDTY7ACMRAJM7TSJMN",
  "number": 3,
  "subtotal_cents": 300000,
  "discount_cents": 0,
  "tax_cents": 0,
  "total_cents": 300000
}
PATCH/api/invoices/:id

Change lines or due date while it is unpaid.

Example
PATCH /api/invoices/01M3JVF2PR6PVX213HCQFE4E16
{
  "due_on": "2026-10-16"
}

200
{
  "ok": true,
  "subtotal_cents": 15000,
  "discount_cents": 0,
  "tax_cents": 0,
  "total_cents": 15000
}
POST/api/invoices/:id/send

Send the pay link: channel "sms", "email" (the default) or "both", optional to and message. With "both", each channel takes its own optional sms_to / email_to and sms_message / email_message, with the same pay link, and the answer's sent lists each channel with status sent, queued or failed (a text that had to go by email instead is failed). sms_to must be a phone number and email_to an email address; both go with "both" only. With "both", a single to, or a message without message_channel, is answered 400. Needs send. A text to a number marked wrong (a call logged as "Phone number is incorrect", or marked on the client page) is answered 409 and nothing is sent, unless you send confirm_wrong_number: true with wrong_number_seen set to the 409's wrong_number.seen; the 409 carries wrong_number (the number, when it was marked, by whom, and seen) and confirm_with. The yes covers the marks it names and no more: a number marked again later, or another number, is asked again, so an integration that always sends the yes never texts a newly marked number by itself. Email is never held. Send a new Idempotency-Key with the yes (the body changed). The answer carries saved_email only when the send saved an address as the customer's email: an email typed for a customer with none on file, never the shop's or a team member's address, and never one that had failed or been blocked by the time the send answered. Only a person sending from the app saves one; a send made with an API key never saves an address, so its answer has no saved_email.

Example
POST /api/invoices/01M3JVF2GN2TGWK1TZH91F8DZY/send
{
  "email": true
}

200
{
  "ok": true,
  "hub_url": "https://app.chalkcrm.com/hub/01M3JVF2H3MMB1RCD27CQM75AR",
  "channel": "email",
  "to": "dale@example.com"
}
POST/api/invoices/remind

Nudge the slow ones: ids. Needs send. Every reminder is worked out first: if any would be texted to a number marked wrong, the answer is 409, no reminder goes, and its wrong_number.invoices names them; send confirm_wrong_number: true with wrong_number_seen set to its wrong_number.seen to send them all anyway, or leave those ids out. Email is never held.

Example
POST /api/invoices/remind
{
  "ids": [
    "01M3JVF2GN2TGWK1TZH91F8DZY"
  ]
}

200
{
  "queued": 1,
  "skipped": 0
}
POST/api/invoices/:id/link

Mint the pay link without sending it. Needs send: the link outlives the key.

Example
POST /api/invoices/01M3JVF2GN2TGWK1TZH91F8DZY/link

200
{
  "hub_url": "https://app.chalkcrm.com/hub/01M3JVF2H3MMB1RCD27CQM75AR"
}
POST/api/invoices/:id/archive

Take it off the live list. Paid invoices archive. They do not delete.

Example
POST /api/invoices/01M3JVF2PR6PVX213HCQFE4E16/archive

200
{
  "ok": true
}
POST/api/invoices/:id/unarchive

Put it back.

Example
POST /api/invoices/01M3JVF2PR6PVX213HCQFE4E16/unarchive

200
{
  "ok": true
}
DELETE/api/invoices/:id

Delete an unpaid invoice with no payments. If money landed, archive it instead.

Example
DELETE /api/invoices/01M3JVF2PR6PVX213HCQFE4E16

200
{
  "ok": true
}
GET/api/installments/:invoiceId

The payment plan on an invoice, if it has one.

Example
GET /api/installments/01M3JVF2GN2TGWK1TZH91F8DZY

200
[]
PUT/api/installments/:invoiceId

Set a payment plan: installments[] of label, amount_cents, due_on. Owner or admin key.

Example
PUT /api/installments/01M3JVF2TDTY7ACMRAJM7TSJMN
{
  "installments": [
    {
      "label": "Deposit",
      "amount_cents": 100000,
      "due_on": "2026-09-29"
    },
    {
      "label": "On completion",
      "amount_cents": 200000,
      "due_on": "2026-10-28"
    }
  ]
}

200
{
  "ok": true,
  "count": 2
}
POST/api/invoices/:id/send-receipt

Send the receipt for a paid invoice: channel. Needs send. A text to a number marked wrong (a call logged as "Phone number is incorrect", or marked on the client page) is answered 409 and nothing is sent, unless you send confirm_wrong_number: true with wrong_number_seen set to the 409's wrong_number.seen; the 409 carries wrong_number (the number, when it was marked, by whom, and seen) and confirm_with. The yes covers the marks it names and no more: a number marked again later, or another number, is asked again, so an integration that always sends the yes never texts a newly marked number by itself. Email is never held. Send a new Idempotency-Key with the yes (the body changed). An invoice paid in full whose receipt already went, or the same receipt to the same address a moment ago, is also answered 409 and nothing is sent: error says which, with the day the receipt went.

Example
POST /api/invoices/01M3JVF2GN2TGWK1TZH91F8DZY/send-receipt
{
  "channel": "email"
}

200
{
  "ok": true,
  "receipt_url": "https://app.chalkcrm.com/hub/01M3JVF2H3MMB1RCD27CQM75AR/receipt",
  "channel": "email",
  "to": "dale@example.com"
}
GET/api/payments

Money that has come in, newest first. ?limit= and ?before= (a received_at).

Example
GET /api/payments?limit=20

200
[
  {
    "id": "01M3JVF2HK94KKFQW5GBG02A0T",
    "tenant_id": "ten_flow",
    "client_id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
    "invoice_id": "01M3JVF2GN2TGWK1TZH91F8DZY",
    "quote_id": null,
    "amount_cents": 25000,
    "tip_cents": 0,
    "fee_cents": 0,
    ...
  }
]
GET/api/payments/in-transit

Money on its way to the bank, after fees. With Stripe connected it is Stripe's own balance and payouts (source: "stripe"); otherwise an estimate from recent payments (source: "estimate"). Bank payments the bank has not cleared yet are under clearing, never in the total (Stripe's own stripe.balance_cents does hold them). fallback_reason says why an estimate was used; next_payout, stripe and dates can be null. on_its_way_cents and its older name in_transit_net_cents are after fees. in_transit_cents is the same money before fees, as it always was: on the estimate what the customers paid, and with Stripe, Stripe's figure plus the fee Stripe took on each payment still pending in it (a payout already started counts as it pays).

Example
GET /api/payments/in-transit

200
{
  "source": "stripe",
  "estimated": false,
  "on_its_way_cents": 322982,
  "in_transit_cents": 332744,
  "in_transit_net_cents": 322982,
  "next_payout": { "amount_cents": 322982, "arrival_date": "2026-10-27", "from": "stripe_balance" },
  "stripe": { "balance_cents": 504572, "available_cents": 0, "pending_cents": 504572, "payouts": [] },
  "clearing": { "count": 1, "cents": 182090, "net_cents": 181590, "in_stripe_balance_cents": 181590, "expected_date": "2026-10-27", "payments": [] },
  "payments": []
}
POST/api/payments

Write down money that came in by hand: invoice_id (or quote_id for a deposit), amount_cents, method (cash, check or other), optional received_at (a real date, 2026-10-02, or a full ISO time; anything else is refused), note, tip_cents. A key never records a card or sets processor fields. send_receipt: true needs send; that receipt is never texted to a number marked wrong (it goes by email when they have one, or not at all). Without send, no receipt or review request goes, whatever the date. While a bank payment from the customer is still clearing on it, the answer is 409 unless you send confirm_pending: true, so the bill is not paid twice by mistake. For a check, send its number as check_number (it goes into the note as "Check #1041"). The same check number for the same amount already on the same job is answered 409 and nothing is recorded, unless you send confirm_duplicate_check: true (one check split across two bills of one job is the real case), so a retry never writes the same check twice by itself. That 409's duplicate_check.seen is how many copies are on the job, and its words name it; send it back as duplicate_check_seen with the yes and the yes covers those copies only, so if there are more by then you are asked again instead. A yes sent without duplicate_check_seen covers no copy on the job: it records nothing there, so an integration that sends the yes on every call never writes the same check twice on a retry. The same number on file elsewhere is unaffected (its count is 0). Send a new Idempotency-Key with the yes (the body changed), so a retry of it is never recorded twice either. The same number already on file for this customer for another amount or another job is recorded, and the answer carries a warning that says where; send confirm_duplicate_check: true to say you know.

Example
POST /api/payments#rest
{
  "invoice_id": "01M3JVF2GN2TGWK1TZH91F8DZY",
  "amount_cents": 48625,
  "method": "cash"
}

201
{
  "id": "01M3JVF2Q06CENQX5XT5XBYNW5",
  "fee_cents": 0,
  "net_cents": 48625
}
GET/api/payments/cards/:clientId

See that a card is on file. Charging it is a person in the loop.

Example
GET /api/payments/cards/01M3JVF1K1XS5ZJKJG6RF2TBXE

200
{
  "available": false,
  "cards": []
}

Pay and the books

What the crew is owed and why, what the shop spent, and the numbers. Reading pay needs read on Payments and money and a key whose person has the money switch (owner, admin, office reads). Changing how people are paid, marking pay paid and overrides need write on Payments and money, on top of the person's own switches. Crew pay is the narrow way in: read lists pay, and write adds a split owed on a job, or changes or takes back one still owed that was added by hand, without ever marking pay paid.

GET/api/payroll

Pay > Owed: each person and what they are owed now (owed[]: pending, held, payable), plus pay setup totals. owed_now_cents is the figure Who is owed shows: what Mark all paid would pay, with pay on hold (held_cents) left out. total_cents is everything open, on hold included. owed[] comes most owed now first, and owed_now_total_cents adds up owed_now_cents.

Example
GET /api/payroll

200
{
  "setup": {
    "overhead_bp": 0,
    "fixed_job_cost_cents": 0,
    "pay_timing": "week_end",
    "early_pay_enabled": "0",
    "wages_since": "2026-09-27T04:00:00.000Z",
    "commission_scope_ready": true
  },
  "no_job_time": [],
  "people": [
    {
      "id": "usr_admin",
      "name": "Jess Rowe",
      "color": "#111",
      ...
    },
    ...
  ],
  "owed": [
    {
      "payee_user_id": "usr_pete",
      "payee_name": "Pete Barnes",
      "payee_role": "crew",
      "total_cents": 25000,
      "owed_now_cents": 25000,
      "held_cents": 0,
      ...
    },
    ...
  ],
  "recent_paid": [],
  "pending_total_cents": 25000,
  "owed_now_total_cents": 25000,
  "stats": {
    "paid_30d_cents": 0,
    "paid_prev_30d_cents": 0,
    "paid_30d_delta_cents": 0,
    "paid_30d_delta_pct": null,
    "held_cents": 0,
    "due_this_week_cents": 25000
  }
}
GET/api/payroll/people/:id

One person's pay: their setup and every owed or paid row, with the job each came from.

Example
GET /api/payroll/people/usr_pete

200
{
  "person": {
    "id": "usr_pete",
    "name": "Pete Barnes",
    "color": "#224",
    "role": "field",
    "active": 1,
    "pay_type": "per_project",
    ...
  },
  "payouts": [
    {
      "id": "01M3JVF2EYA5XCAJ9QAR3C6SY8",
      "tenant_id": "ten_flow",
      "job_id": "01M3JVF2D4HZ9B61Q6VK4SG6SY",
      ...
    },
    ...
  ]
}
GET/api/payouts

Every pay row: ?status= (pending, paid, held), ?payee_user_id=, ?job_id= (every pay row on one job, and the owed totals for just that job). Each row carries source_key and pay_kind. A row added by hand has source_key null. A row from Chalk's own pay rules has one, and pay_kind says which: measurement (crew pay from the quote's lines), revenue, salesperson, profit, hour, day. Chalk posts crew pay by itself: when a quote's lines carry crew pay, each tech paid per project who is on the job's visits gets a row with source_key measurement: and their user id, and the pay waits as Crew (measurement:crew) until somebody is on a visit. It is raised to the shop's crew pay minimum per job (Pay setup), for each tech; a tech already paid on the job is not topped up to a minimum set since. It shows as in progress (in_progress 1) until the job is finished, or until what the tech's pay timing waits on; the same goes for a flat or percent split added by hand for a tech paid per project (not on a recurring or archived job, which never finishes). A split added by hand for the work (role subcontractor, crew or technician, more than $0, not archived; several add up) for a tech paid per project replaces Chalk's row for them when it is at least half of what Chalk works out for them on that job, whichever came first: Chalk posts none, or takes off its own row if it is still open (owed, not on hold, not paid, its amount not set by hand), with a line in History. Under half (gas money, say), both stay. The half is judged for a tech when their own split for the work is added, changed, moved, removed or restored; after that a crew change, a new price or a teammate's split keeps what is there, except that Chalk's open row is taken off whenever the split covers all of it. Chalk's row that is already paid, on hold or set by hand is never touched, so the split is extra and the answer warns; released from hold, marked unpaid, restored or given back its worked-out amount, it is taken off again if a split covers it (that answer says so with removed and a warning), and when it stays next to a split of at least half of it the answer warns that it is owed on top. When the split is removed, archived, moved to somebody else or cut under half, the tech gets Chalk's row back. A split with another role is never crew pay: other and referral are extra and owed at once, and salesperson follows sales pay. A bulk archive or delete of such rows is refused past 20 jobs at a time. Before a script adds pay by hand, read GET /api/payouts?job_id= so the same pay is not added twice. owed[] groups what is open by person, most owed now first: owed_now_cents is what Mark all paid would pay them, with pay on hold (held_cents) left out; total_cents is everything open, on hold included. owed_now_total_cents adds up owed_now_cents.

Example
GET /api/payouts?status=pending

200
{
  "payouts": [
    {
      "id": "01M3JVF2EYA5XCAJ9QAR3C6SY8",
      "tenant_id": "ten_flow",
      "job_id": "01M3JVF2D4HZ9B61Q6VK4SG6SY",
      "payee_user_id": "usr_pete",
      ...
    },
    ...
  ],
  "owed": [
    {
      "payee_user_id": "usr_pete",
      "payee_name": "Pete Barnes",
      "payee_role": "crew",
      "total_cents": 25000,
      "owed_now_cents": 25000,
      "held_cents": 0,
      ...
    },
    ...
  ],
  "pending_total_cents": 25000,
  "owed_now_total_cents": 25000
}
POST/api/payouts

Add pay owed to somebody on a job, the way Add split on the job does. job_id, basis (flat with amount_cents, percent of the job or profit share with rate_bp), and either payee_user_id (a teammate) or payee_name (somebody with no login). Optional payee_role (default subcontractor) and note. It is always added as owed, never as paid. Needs write on Crew pay, or on Payments and money. Without Payments and money, a flat row for the Crew with the role crew is refused: Chalk keeps that for crew pay worked out from measurements, so name the person or use another role. Nobody but the owner adds pay for themselves, and a key acting as a role never adds pay for the person who made it. Read GET /api/payouts?job_id= first. A split for the work for a tech paid per project (role subcontractor, crew or technician) that is at least half of their crew pay from the quote's lines on that job replaces Chalk's row for them: the answer carries counts_as_crew_pay, replaced_crew_pay_cents when it took Chalk's open row off, and a warning in words. When Chalk's row stays (it is already paid, on hold or its amount was set by hand, or the split is under half of it), the split is still added, on top, and the answer carries a warning and auto_crew_pay (id, amount_cents, source_key).

Example
POST /api/payouts
{
  "job_id": "01M3JVF2D4HZ9B61Q6VK4SG6SY",
  "basis": "flat",
  "amount_cents": 45000,
  "payee_user_id": "usr_pete",
  "payee_role": "subcontractor",
  "note": "Fence, two coats"
}

201
{
  "id": "01M3JVF2EYA5XCAJ9QAR3C6SY8",
  "amount_cents": 45000
}
POST/api/jobs/:id/payouts

The same as POST /api/payouts, with the job in the address. Same body without job_id (a job_id naming another job is refused), same checks, same answer. Needs write on Crew pay, or on Payments and money.

Example
POST /api/jobs/01M3JVF2D4HZ9B61Q6VK4SG6SY/payouts
{
  "basis": "flat",
  "amount_cents": 18000,
  "payee_user_id": "usr_juan",
  "note": "Gate, extra coat"
}

201
{
  "id": "01M3JVF2FQ0B7W9T2Z5C8KX4ND",
  "amount_cents": 18000,
  "warning": "Chalk already has $180.00 of crew pay for Juan Ortiz on this job from the quote's lines, and $180.00 of it is already paid, so it stays and this adds more on top. Remove one if it is the same pay.",
  "auto_crew_pay": {
    "id": "01M3JVF2E3J8M6P1V4R7T0WQ5S",
    "amount_cents": 18000,
    "source_key": "measurement:usr_juan"
  }
}
GET/api/payouts/:id

One pay row, with the same fields as a row of the list, archived ones too (archived_at set). A person who sees only their own pay gets 404 for anybody else's. Needs read on Crew pay, or on Payments and money.

Example
GET /api/payouts/01M3JVF2EYA5XCAJ9QAR3C6SY8

200
{
  "id": "01M3JVF2EYA5XCAJ9QAR3C6SY8",
  "job_id": "01M3JVF2D4HZ9B61Q6VK4SG6SY",
  "payee_user_id": "usr_pete",
  "payee_name": "Pete Barnes",
  "payee_role": "subcontractor",
  "basis": "flat",
  "rate_bp": null,
  "amount_cents": 45000,
  "note": "Fence, two coats",
  "status": "pending",
  "source_key": null,
  "pay_kind": null,
  "overridden": 0,
  "archived_at": null,
  "job_number": 29,
  "job_title": "Fence and deck",
  "client_name": "Dana Whitfield",
  "payable_now": 1,
  "in_progress": 0,
  "in_progress_why": null
}
PATCH/api/payouts/:id

Change a split that is still owed: amount_cents, note, the payee (payee_user_id or payee_name), payee_role, or basis with rate_bp. The amount is worked out again the way adding a split works it out: a percent or profit split takes a new rate_bp, and to set dollars on one send basis flat with amount_cents. It never marks pay paid or unpaid, holds it, archives it or moves it to another job: status, paid, paid_at, paid_method, archived_at, job_id and other fields are refused. A paid row stays put (409, or 403 for a Crew pay key) and an archived one is restored first. amount_cents and rate_bp are whole numbers. Pay from Chalk's own rules takes only amount_cents, as a hand-set amount beside what Chalk worked out, and needs Payments and money. With Crew pay only a split that is still owed, was added by hand and has no amount set by a person in Chalk. Answers the row as GET /api/payouts/:id does (with the same warning, auto_crew_pay, counts_as_crew_pay or replaced_crew_pay_cents as adding a split, when they apply), and History names the key. Moving a split for the work to somebody else gives the first tech Chalk's crew pay back and replaces the new one's.

Example
PATCH /api/payouts/01M3JVF2EYA5XCAJ9QAR3C6SY8
{
  "amount_cents": 48000,
  "note": "Fence, two coats and the gate"
}

200
{
  "id": "01M3JVF2EYA5XCAJ9QAR3C6SY8",
  "job_id": "01M3JVF2D4HZ9B61Q6VK4SG6SY",
  "payee_user_id": "usr_pete",
  "payee_name": "Pete Barnes",
  "basis": "flat",
  "amount_cents": 48000,
  "note": "Fence, two coats and the gate",
  "status": "pending",
  "source_key": null
}
DELETE/api/payouts/:id

Remove a split. With Crew pay only a split that is still owed, was added by hand and has no amount set by a person in Chalk. A paid or held row, one from Chalk's own pay rules, or the Crew's pay from measurements is refused.

POST/api/payouts/:id/archive

Archive a split so it is no longer owed. Answers { "ok": true, "changed": 1 }, or changed: 0 when nothing moved. Crew pay has the same limits as removing one.

POST/api/payouts/:id/unarchive

Put an archived split back. Crew pay has the same limits as removing one.

GET/api/expenses

Spend, newest first: ?job_id=, ?category=, ?from=/?to=, ?limit=.

Example
GET /api/expenses?limit=20

200
{
  "expenses": [
    {
      "id": "01M3JVF2G9NP39GEZNQ3MG54A6",
      "tenant_id": "ten_flow",
      "job_id": "01M3JVF2D4HZ9B61Q6VK4SG6SY",
      "user_id": "usr_owner",
      ...
    },
    ...
  ],
  "total_cents": 18000,
  "count": 1,
  "more": false
}
GET/api/expenses/summary

This month and last, by category.

Example
GET /api/expenses/summary

200
{
  "this_month": {
    "v": 18000,
    "n": 1
  },
  "last_month": {
    "v": 0,
    "n": 0
  },
  "this_month_by_category": [
    {
      "category": "materials",
      "v": 18000,
      "n": 1
    },
    ...
  ],
  "this_month_materials_cents": 18000,
  "by_category_90d": [],
  "reimbursable": [],
  "reimbursable_total_cents": 0
}
POST/api/expenses

Log a spend, the way the receipt camera does: amount_cents, description, category, incurred_on, optional job_id. Anyone on the crew may log one. To log items by name, quantity and unit cost on a job, use POST /api/jobs/:id/expenses.

Example
POST /api/expenses#2
{
  "amount_cents": 2500,
  "category": "fuel",
  "description": "Gas",
  "incurred_on": "2026-09-28"
}

201
{
  "id": "01M3JVF2T5CN6HCNPZ91ZCZV9T",
  "amount_cents": 2500,
  "description": "Gas"
}
PATCH/api/expenses/:id

Fix one. The office, or the person who logged it.

Example
PATCH /api/expenses/01M3JVF2G9NP39GEZNQ3MG54A6
{
  "amount_cents": 17500
}

200
{
  "ok": true,
  "amount_cents": 17500,
  "description": "Stain, 5 gal"
}
DELETE/api/expenses/:id

Take one off. Owner or admin key. It can be put back.

Example
DELETE /api/expenses/01M3JVF2T5CN6HCNPZ91ZCZV9T

200
{
  "ok": true
}
POST/api/expenses/:id/restore

Put it back. Owner or admin key.

Example
POST /api/expenses/01M3JVF2T5CN6HCNPZ91ZCZV9T/restore

200
{
  "ok": true
}
GET/api/books/month

The month's books: collected, fees, spend, pay: ?month=YYYY-MM. Needs Reports.

Example
GET /api/books/month?month=2026-09

200
{
  "timezone": "America/New_York",
  "month": "2026-09",
  "collected_cents": 25000,
  "surcharge_cents": 0,
  "fee_cents": 0,
  "klarna_fee_cents": 0,
  "labor_cents": 0,
  "expense_cents": 18000,
  "expense_n": 1,
  "payouts_cents": 25000,
  ...
}
GET/api/dashboard/timesheets

The week's time: every punch and each person's hours: ?week=YYYY-MM-DD.

Example
GET /api/dashboard/timesheets

200
{
  "week": "2026-09-27",
  "on_ledger": true,
  "wages_since": "2026-09-27T04:00:00.000Z",
  "locked": false,
  "entries": [],
  "team": [
    {
      "id": "usr_admin",
      "name": "Jess Rowe",
      "color": "#111",
      "role": "admin",
      ...
    },
    ...
  ]
}
GET/api/timeclock/weeks/:week

Whether a pay week is locked.

Example
GET /api/timeclock/weeks/2026-09-28

200
{
  "locked": false,
  "locked_at": null,
  "locked_by_name": null
}

Messages

The business number, as an inbox. Replies land here. Sends still respect STOP and whether text or email is actually wired. A reply sent here goes at once, like one typed in the app, so quiet hours do not hold it.

GET/api/messages

Threads in the inbox.

Example
GET /api/messages

200
{
  "threads": [],
  "bot_working": [],
  "bot_working_addresses": [],
  "held_overnight": 0,
  "unread_total": 0,
  "ready": true,
  ...
}
GET/api/messages/thread

The back and forth with one number or address: ?address= (+18645550199 or an email).

Example
GET /api/messages/thread?address=%2B18645550199

200
{
  "address": "+18645550199",
  "bot_working": false,
  "messages": []
}
GET/api/messages/unread

What has not been opened yet.

Example
GET /api/messages/unread

200
{
  "n": 0,
  "ready": true,
  "state": "in_app"
}
GET/api/messages/recipients

Who you can text from here.

Example
GET /api/messages/recipients?q=harmon

200
{
  "matches": [
    {
      "id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
      "name": "Dale Harmon",
      "phone": "+18645550199"
    },
    ...
  ],
  "suggested": false
}
GET/api/messages/usage

The texting meter: used, included, the bank. Buying packs stays in the app.

Example
GET /api/messages/usage

200
{
  "mode": "stop",
  "included": 1500,
  "included_used": 0,
  "used": 0,
  "bank": 0,
  "payg_used": 0,
  "payg_month": null,
  "rate_cents_per_unit": 2,
  "pack_min": 250,
  ...
}
POST/api/messages/send

Reply from the business number: address (their number or email), body, optional client_id. Needs send. It goes out at once, like a reply typed in the app: quiet hours do not hold it, so check the time before an automation calls it. A number that texted STOP is still refused.

Example
POST /api/messages/send
{
  "client_id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
  "address": "+18645550199",
  "body": "We can do Tuesday at 9."
}

201
{
  "id": "01M3JVF2QJZYHTJN5E8EDEGS5B",
  "simulated": true,
  "media": []
}
POST/api/messages/read

Mark a thread read: address. Needs send.

Example
POST /api/messages/read
{
  "address": "+18645550199"
}

200
{
  "ok": true
}
GET/api/connectors/channels

Whether text, email or neither can actually send.

Example
GET /api/connectors/channels

200
{
  "sms": {
    "state": "in_app",
    "can_send": true
  },
  "email": {
    "ready": true
  }
}

Notes and photos

Gate codes, dog names, call before you come. Before and after shots live on the job. line_items[].description on a quote is the printed line, not an office note. Office notes are GET /api/notes/for-client/:id and POST /api/notes with a message. They are different on purpose.

GET/api/notes/for-client/:id

Notes on a customer.

Example
GET /api/notes/for-client/01M3JVF1K1XS5ZJKJG6RF2TBXE

200
[
  {
    "id": "01M3JVF2K0ESQJZ6CTCVH0S0ZW",
    "tenant_id": "ten_flow",
    "entity_type": "client",
    "entity_id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
    "body": "Prefers texts after 5pm.",
    "pinned": 0,
    "created_by": "usr_owner",
    "created_at": "2026-09-28T01:53:26.112Z",
    "client_id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
    ...
  }
]
GET/api/notes/:entityType/:entityId

Notes on a job, quote, invoice or lead.

Example
GET /api/notes/job/01M3JVF2D4HZ9B61Q6VK4SG6SY

200
[]
POST/api/notes

Write a note on a customer, job or quote. Put the message in body (or message). Quote line descriptions stay on the quote.

Example
POST /api/notes#2
{
  "entity_type": "job",
  "entity_id": "01M3JVF2D4HZ9B61Q6VK4SG6SY",
  "body": "Wrong job"
}

201
{
  "id": "01M3JVF2S62VXCVVS4WW6ENHSB"
}
DELETE/api/notes/:id

Take a note off.

Example
DELETE /api/notes/01M3JVF2S62VXCVVS4WW6ENHSB

200
{
  "ok": true
}
PATCH/api/notes/:id

Fix a note.

Example
PATCH /api/notes/01M3JVF2K0ESQJZ6CTCVH0S0ZW
{
  "body": "Prefers texts after 5pm. Dog is friendly."
}

200
{
  "ok": true
}
PUT/api/files

Query entity_type, entity_id, optional filename. Body is raw bytes, Content-Type: image/jpeg (not JSON). JSON {entity_type, entity_id} is wrong. There is no GET /api/files index (404). List is GET /api/files/list/:type/:id. Fetch one is GET /api/files/:id. Needs files.

Example
PUT /api/files?entity_type=job&entity_id=01M3JVF2D4HZ9B61Q6VK4SG6SY&filename=after.jpg
(raw image bytes)

201
{
  "id": "01M3JVF2K69VABZ8KCJFRR6XD9",
  "key": "ten_flow/job/01M3JVF2D4HZ9B61Q6VK4SG6SY/01M3JVF2K69VABZ8KCJFRR6XD9-after.jpg",
  "size_bytes": 14
}
GET/api/files/gallery

The shop gallery, searchable. Needs files.

Example
GET /api/files/gallery

200
{
  "images": [
    {
      "id": "01M3JVF2K69VABZ8KCJFRR6XD9",
      "entity_type": "job",
      "entity_id": "01M3JVF2D4HZ9B61Q6VK4SG6SY",
      "filename": "after.jpg",
      "content_type": "image/jpeg",
      ...
    },
    ...
  ],
  "has_more": false,
  "offset": 0
}
GET/api/files/list/:type/:id

Photos on one job or quote.

Example
GET /api/files/list/job/01M3JVF2D4HZ9B61Q6VK4SG6SY

200
[
  {
    "id": "01M3JVF2K69VABZ8KCJFRR6XD9",
    "tenant_id": "ten_flow",
    "entity_type": "job",
    "entity_id": "01M3JVF2D4HZ9B61Q6VK4SG6SY",
    "r2_key": "ten_flow/job/01M3JVF2D4HZ9B61Q6VK4SG6SY/01M3JVF2K69VABZ8KCJFRR6XD9-after.jpg",
    "filename": "after.jpg",
    ...
  }
]
GET/api/files/:id

Fetch one file.

Example
GET /api/files/01M3JVF2K69VABZ8KCJFRR6XD9

200
(image/jpeg, 14 bytes)
DELETE/api/files/:id

Take a photo off. Needs files.

Example
DELETE /api/files/01M3JVF2K69VABZ8KCJFRR6XD9

200
{
  "ok": true
}

Search and the board

Find Thompson's fence job from a sentence. See what is open today. Check who a key acts as.

GET/api/users/me

Who this key acts as: the person, their role and switches, whether they may set crew pay, and the key's scopes and call cap. Check it once instead of learning your limits one 403 at a time.

Example
GET /api/users/me

200
{
  "user": {
    "id": "usr_owner",
    "name": "Sam Carter",
    "role": "owner",
    "email": "sam@upstatepainting.example"
  },
  "shop": {
    "id": "ten_flow",
    "name": "Upstate Painting Co",
    "timezone": "America/New_York"
  },
  "perms": {
    "sales": true,
    "schedule": "all",
    "schedule_write": true,
    "job_prices": true,
    "invoices": "full",
    "money": "full",
    "reports": true,
    "chalkbot": true,
    "messaging": true
  },
  "may_set_crew_pay": true,
  "api_key": {
    "id": "key_tour",
    "name": "Estimator",
    "prefix": "chk_live_key_tou",
    "scopes": [
      "read",
      ...
    ],
    "created_at": "2026-09-28T01:53:24.834Z",
    "last_used_at": "2026-09-28T01:53:25.066Z",
    "calls_per_minute": 240,
    "access": {
      "areas": {
        "clients": "write",
        "sales": "write",
        "schedule": "read",
        ...
      },
      "send": false
    },
    "acts_as": "owner",
    "expires_at": null
  }
}
GET/api/search

Search customers, quotes, jobs and invoices: ?q=.

Example
GET /api/search?q=harmon

200
{
  "q": "harmon",
  "kind": null,
  "status": null,
  "hits": [
    {
      "kind": "client",
      "id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
      "title": "Harmon Rentals",
      "subtitle": "+18645550199 · 14 Pelham Rd, Greer",
      "status": null,
      ...
    },
    ...
  ]
}
GET/api/dashboard/search

The same hunt the header bar uses.

Example
GET /api/dashboard/search?q=harmon

200
{
  "results": [
    {
      "id": "01M3JVF1K1XS5ZJKJG6RF2TBXE",
      "title": "Dale Harmon",
      "subtitle": "Harmon Rentals",
      "type": "client",
      "path": "/clients/01M3JVF1K1XS5ZJKJG6RF2TBXE"
    },
    ...
  ]
}
GET/api/dashboard

What is open: leads, quotes waiting, jobs, money owed.

Example
GET /api/dashboard

200
{
  "deltas": {
    "revenue_pct": null,
    "close_rate_pts": null,
    "won_value_pct": null
  },
  "on_clock": [],
  "revenue_this_month_cents": 25000,
  "goals": [],
  "quotes_90d": {
    "count": 2,
    "value_cents": 147250
  },
  "won_90d": {
    "count": 1,
    "value_cents": 73625
  },
  "lost_90d": 0,
  ...
}
GET/api/dashboard/reports

The numbers, read only: money by month, who sells, lead sources, and job_profit[] (each finished job's revenue, costs, crew pay and profit). Needs Reports.

Example
GET /api/dashboard/reports

200
{
  "monthly": [
    {
      "month": "2026-09",
      "collected_cents": 25000,
      "payments": 1
    },
    ...
  ],
  "by_salesperson": [
    {
      "name": "Sam Carter",
      "quoted_count": 2,
      "quoted_cents": 147250,
      "won_count": 1,
      ...
    },
    ...
  ],
  "by_source": [
    {
      "source": "website",
      "leads": 1,
      "won_jobs": 1,
      "won": 1,
      ...
    },
    ...
  ],
  "job_profit": [
    {
      "id": "01M3JVF2D4HZ9B61Q6VK4SG6SY",
      "number": 1,
      "title": "Fence staining - 200 ft, both sides",
      "total_cents": 73625,
      ...
    },
    ...
  ],
  "by_job_type": [
    {
      "name": "Not categorised",
      "jobs": 1,
      "total_cents": 73625
    },
    ...
  ],
  "expense_mix": [
    {
      "name": "materials",
      "total_cents": 18000,
      "n": 1
    },
    ...
  ],
  "quote_outcomes": [
    {
      "name": "Won",
      "n": 1,
      "total_cents": 73625
    },
    ...
  ],
  "repeat_vs_new": [
    {
      "month": "2026-09",
      "repeat_jobs": 0,
      "new_jobs": 1
    },
    ...
  ]
}
GET/api/reports/dashboard

The Reports page for one period: what the finished jobs made (sold, direct costs, gross profit, overhead, profit shares, net profit), cash in and out, overhead, targets, pay per person, expenses, sales and what is owed. ?period=this_month (or last_month, this_quarter, last_7, last_30, last_90, this_year, last_year, custom with from and to as YYYY-MM-DD), &compare=1 for the period before. Money in cents. Needs Reports.

Example
GET /api/reports/dashboard?period=last_month

200
{
  "period": { "key": "last_month", "fromDay": "2026-09-01", "toDay": "2026-10-01", "label": "September 2026" },
  "summary": {
    "jobs": 8,
    "sold_cents": 1953100,
    "sold_net_cents": 1953100,
    "gross_cents": 1104200,
    "net_cents": 812600,
    "net_margin_bp": 4161
  },
  "cash": { "collected_cents": 1820000, "tax_cents": 0, "leftover_cents": 640300 }
}
GET/api/dashboard/goals

The Chalkboard's goals (money collected or work sold, jobs finished, new leads, close rate) over one period, each against its target scaled to that period: ?period=last_90 (or last_7, last_30, this_month, this_quarter, this_year). Left out, the period the person picked on the Chalkboard. Only the targets that are set. Money in cents, rates in basis points. Needs Reports. The key's role needs Customers and quotes, or See shop goals for a role without it (the owner and admins always read them). Money goals also need Revenue on the Chalkboard.

GET/api/dashboard/referrals

Who sent work, and what those people earned.

Example
GET /api/dashboard/referrals

200
{
  "signups": 0,
  "payouts_owed_cents": 0,
  "payouts_paid_cents": 0,
  "won_revenue_cents": 0,
  "signups_by_month": [
    {
      "month": "2025-10",
      "signups": 0
    },
    ...
  ],
  "earnings_by_month": [
    {
      "month": "2025-10",
      "paid_cents": 0,
      "pending_cents": 0
    },
    ...
  ],
  "referrers": [],
  "empty": true
}
GET/api/users

Who can be assigned. Creating users stays in the app.

Example
GET /api/users

200
[
  {
    "id": "usr_admin",
    "initials": "u2",
    "email": "jess@upstatepainting.example",
    "name": "Jess Rowe",
    "phone": null,
    "role": "admin",
    "color": "#111",
    "active": 1,
    ...
  },
  ...
]
GET/api/team

The team with roles and pay types. Owner or admin key. Invites stay in the app. With write on Team a key can change people below admin, never an owner, an admin or the person who made it.

Example
GET /api/team

200
{
  "people": [
    {
      "id": "usr_owner",
      "initials": "u1",
      "email": "sam@upstatepainting.example",
      ...
    },
    ...
  ],
  "policy": {
    "password": "optional",
    "pin": "off"
  }
}
GET/api/notifications

What the office bell is holding.

Example
GET /api/notifications

200
{
  "notifications": [
    {
      "id": "01M3JVF2GJPCD7BZHDQJ06SQEM",
      "tenant_id": "ten_flow",
      "user_id": null,
      "kind": "job_ready_to_invoice",
      "title": "Dale Harmon is ready to invoice",
      ...
    },
    ...
  ],
  "unread": 3
}
GET/api/notifications/prefs

Which bells this person wants: leads, approvals, ChalkBot, and the rest of the catalog.

Example
GET /api/notifications/prefs

200
{
  "types": {
    "lead_created": true,
    "quote_approved": true,
    "quote_changes_requested": true,
    "job_needs_schedule": true,
    "job_ready_to_invoice": true,
    "payment_received": true,
    "money_to_sort": true,
    "text_from_new_number": true,
    "texts_switched_off": true,
    ...
  },
  "catalog": [
    {
      "key": "lead_created",
      "group": "Work",
      "label": "New leads",
      "hint": "Someone asked for a quote or booked an estimate."
    },
    ...
  ],
  "role_defaults": {
    "job_ready_to_invoice": {
      "office": true,
      "crew": false
    }
  },
  "can_edit_role_defaults": true,
  "push": {
    "configured": false,
    "secret_names": [
      "VAPID_PUBLIC_KEY",
      ...
    ]
  }
}
PUT/api/notifications/prefs

Turn those types on or off: { "types": { "quote_approved": false } }.

Example
PUT /api/notifications/prefs
{
  "types": {
    "quote_approved": false
  }
}

200
{
  "types": {
    "lead_created": true,
    "quote_approved": false,
    "quote_changes_requested": true,
    "job_needs_schedule": true,
    "job_ready_to_invoice": true,
    "payment_received": true,
    "money_to_sort": true,
    "text_from_new_number": true,
    "texts_switched_off": true,
    ...
  },
  "catalog": [
    {
      "key": "lead_created",
      "group": "Work",
      "label": "New leads",
      "hint": "Someone asked for a quote or booked an estimate."
    },
    ...
  ],
  "role_defaults": {
    "job_ready_to_invoice": {
      "office": true,
      "crew": false
    }
  }
}

Automations

The cards on Settings, Automations: follow-ups, reminders, review asks. Owner or admin key.

GET/api/automations

Every card, with its trigger, timing and words.

Example
GET /api/automations

200
{
  "workflows": [
    {
      "id": "01M3JVF2MBZC78JDMRQJ4YBJJR",
      "tenant_id": "ten_flow",
      "builtin_key": "auto_archive_quotes",
      ...
    },
    ...
  ],
  "groups": [
    {
      "id": "quotes",
      "label": "Quotes"
    },
    ...
  ],
  "templates": [
    {
      "id": "custom",
      "title": "Custom",
      "blurb": "Blank When, If, and Then. You pick the trigger and write the steps.",
      ...
    },
    ...
  ],
  "placeholders": {
    "quote_sent": [
      "first_name",
      ...
    ],
    "invoice_due": [
      "first_name",
      ...
    ],
    "invoice_paid": [
      "first_name",
      ...
    ],
    "installment_due": [
      "first_name",
      ...
    ],
    "lead_created": [
      "first_name",
      ...
    ],
    "visit_upcoming": [
      "first_name",
      ...
    ],
    ...
  },
  "channels": {
    "sms": {
      "connected": false,
      "can_send": false,
      "provider": null
    },
    "email": {
      "ready": false
    }
  }
}
GET/api/automations/:id

One card.

Example
GET /api/automations/01M3JVF2R3S7CJ1SH5JG1G2BTS

200
{
  "id": "01M3JVF2R3S7CJ1SH5JG1G2BTS",
  "tenant_id": "ten_flow",
  "builtin_key": "lead_received",
  "group_key": "leads",
  "title": "New lead auto-text",
  "enabled": true,
  "definition": {
    "trigger": {
      "type": "lead_created",
      "delayDays": 0,
      "delayHours": 0
    },
    "conditions": [],
    "actions": [
      {
        "id": "a1",
        "type": "notify_client",
        "channel": "auto",
        "body": "Hi {first_name}, we got your request at {company}. We'll be in touch shortly to talk it...",
        "subject": "We got your request at {company}",
        ...
      },
      ...
    ],
    "branches": []
  },
  "created_at": "2026-09-28T01:53:26.275Z",
  "updated_at": "2026-09-28T01:53:26.275Z",
  ...
}
POST/api/automations/from-template

Add a card from one of the built-in templates: template_id (for example new_lead_text).

Example
POST /api/automations/from-template
{
  "template_id": "new_lead_text"
}

201
{
  "workflow": {
    "id": "01M3JVF2R3S7CJ1SH5JG1G2BTS",
    "tenant_id": "ten_flow",
    "builtin_key": "lead_received",
    "group_key": "leads",
    "title": "New lead auto-text",
    "enabled": true,
    "definition": {
      "trigger": ...,
      "conditions": ...,
      "actions": ...,
      "branches": ...
    },
    "created_at": "2026-09-28T01:53:26.275Z",
    "updated_at": "2026-09-28T01:53:26.275Z",
    ...
  },
  "created": true
}
POST/api/automations

Add a card of your own: title, group_key, definition (trigger, conditions, actions).

Example
POST /api/automations
{
  "title": "Thank-you text",
  "group_key": "jobs",
  "definition": {
    "trigger": {
      "type": "job_completed",
      "delayDays": 1
    },
    "conditions": [],
    "actions": [],
    "branches": []
  }
}

201
{
  "id": "01M3JVF2V660AS4Y8RBXD3KA4G",
  "tenant_id": "ten_flow",
  "builtin_key": null,
  "group_key": "jobs",
  "title": "Thank-you text",
  "enabled": true,
  ...
}
DELETE/api/automations/:id

Take a card off.

Example
DELETE /api/automations/01M3JVF2V660AS4Y8RBXD3KA4G

200
{
  "ok": true
}
GET/api/automations/pause

Whether all automations are paused, since when, by whom, and how many messages the pause has held so far.

Example
GET /api/automations/pause

200
{
  "paused": true,
  "paused_at": "2026-10-14T15:00:00.000Z",
  "paused_by": "Jordan Lee",
  "held": 3
}
PUT/api/automations/pause

Pause all automations: { "paused": true }. While paused, nothing automatic goes to a customer (cards, ChalkBot routines and Just do it sends, the invoice a finished visit would send); what comes due is marked not sent and is not sent later. Sends a person presses still go, and so do answers to the customer's own action: a payment receipt, a booking confirmation, the HELP reply. A key can pause but not resume: { "paused": false } answers 403, and an owner or admin resumes from the app.

Example
PUT /api/automations/pause
{
  "paused": true
}

200
{
  "paused": true,
  "paused_at": "2026-10-14T15:00:00.000Z",
  "paused_by": "Jordan Lee",
  "held": 0
}
PATCH/api/automations/:id

Switch a card on or off (enabled), rename it (title), or change its steps (definition).

Example
PATCH /api/automations/01M3JVF2R3S7CJ1SH5JG1G2BTS
{
  "enabled": false
}

200
{
  "id": "01M3JVF2R3S7CJ1SH5JG1G2BTS",
  "tenant_id": "ten_flow",
  "builtin_key": "lead_received",
  "group_key": "leads",
  "title": "New lead auto-text",
  "enabled": false,
  "definition": {
    "trigger": {
      "type": "lead_created",
      "delayDays": 0,
      "delayHours": 0
    },
    "conditions": [],
    "actions": [
      {
        "id": "a1",
        "type": "notify_client",
        "channel": "auto",
        "body": "Hi {first_name}, we got your request at {company}. We'll be in touch shortly to talk it...",
        "subject": "We got your request at {company}",
        ...
      },
      ...
    ],
    "branches": []
  },
  "created_at": "2026-09-28T01:53:26.275Z",
  "updated_at": "2026-09-28T01:53:26.278Z",
  ...
}
PUT/api/automations/:id/wording

Change what a built-in card says. The fields are the card's own wording settings (the tpl_... keys it names), so the Settings screen and the card never disagree.

Example
PUT /api/automations/01M3JVF2MBJCK29EMH2A3GYV3B/wording
{
  "tpl_visit_reminder_sms": "Hi {first_name}, the crew will be at {address} tomorrow between 8 and 9."
}

200
{
  "id": "01M3JVF2MBJCK29EMH2A3GYV3B",
  "tenant_id": "ten_flow",
  "builtin_key": "visit_reminder",
  "group_key": "visits",
  "title": "Remind the day before a visit",
  "enabled": true,
  "definition": {
    "trigger": {
      "type": "visit_upcoming",
      "delayDays": 1,
      "delayHours": 0,
      "hour": 12
    },
    "conditions": [
      {
        "id": "c1",
        "type": "client_opt_in",
        "op": "is",
        "value": "reminders"
      },
      ...
    ],
    "actions": [
      {
        "id": "a1",
        "type": "notify_client",
        "channel": "auto",
        "body": "Hi {first_name}, the crew will be at {address} tomorrow between 8 and 9.",
        "subject": "Reminder: {company} is coming {date}",
        ...
      },
      ...
    ],
    "branches": []
  },
  "created_at": "2026-09-28T01:53:26.155Z",
  "updated_at": "2026-09-28T01:53:26.281Z",
  ...
}

ChalkBot

The meter and the minutes. Asking the assistant, approving its cards and buying credits stay in the app. ChalkBot can set crew pay on a line for an owner or admin (Ask first or Just do it), through the same endpoint as a key.

GET/api/assistant/usage

Credits used this week, the included 250, and any extra bank.

Example
GET /api/assistant/usage

200
{
  "mode": "stop",
  "included": 250,
  "included_used": 0,
  "used": 0,
  "bank": 0,
  "payg_used": 0,
  "rate_cents_per_credit": 1,
  "pack_min": 500,
  "pack_max": 20000,
  ...
}
GET/api/assistant/time-saved

Minutes ChalkBot saved this month, and all time.

Example
GET /api/assistant/time-saved

200
{
  "month": 0,
  "all": 0
}
GET/api/assistant/pending

Cards waiting for somebody's OK.

Example
GET /api/assistant/pending

200
{
  "items": []
}

Price book and settings

An assistant that quotes without the price book will invent prices. Read the catalog, including measurements, costs you and crew pay. Write hours, templates, numbering and follow-ups. Tax, card and bank fee settings, financing and pay need write on Payments and money, and sign-in rules need write on Team. Message wording, quiet hours and the review link also need Can message customers, and switching an automatic message on or off needs write on Automations and Can message customers. The website estimator's key and where the owner digest goes never change with a key.

GET/api/products

The price book.

Example
GET /api/products

200
[
  {
    "id": "01M3JVF2952CTWCVJEE4MYBNHW",
    "tenant_id": "ten_flow",
    "name": "Fence staining",
    "description": null,
    "category": "service",
    "unit": "ln ft",
    "unit_price_cents": 350,
    ...
  }
]
GET/api/products/:id

One item with measurements, costs, crew pay, tiers. 404 if missing. measures[].id is the product_measure_id a quote line points at.

Example
GET /api/products/01M3JVF2952CTWCVJEE4MYBNHW

200
{
  "id": "01M3JVF2952CTWCVJEE4MYBNHW",
  "tenant_id": "ten_flow",
  "name": "Fence staining",
  "description": null,
  "category": "service",
  "unit": "ln ft",
  "unit_price_cents": 350,
  ...
}
POST/api/products

Add a line the shop actually sells. May include nested measures (measure_type_id, unit_price_cents charge, unit_cost_cents costs you, pay_per_unit_cents crew pay, split_mode, materials[]) and crew_minimum_cents. Crew pay needs a key made by the owner or an admin; from anyone else it is a 403.

Example
POST /api/products
{
  "name": "Fence staining",
  "unit": "ln ft",
  "unit_price_cents": 350,
  "crew_minimum_cents": 15000,
  "measures": [
    {
      "measure_type_id": "01M3JVF292GEWN4HWR0GREQQ28",
      "unit_price_cents": 350,
      "unit_cost_cents": 40,
      "pay_per_unit_cents": 100,
      "split_mode": "split"
    }
  ]
}

201
{
  "id": "01M3JVF2952CTWCVJEE4MYBNHW"
}
PATCH/api/products/:id

Change a price or a name. Same nested measures if present. Omit measures to leave them. Changing crew pay (pay_per_unit_cents, split_mode, crew_minimum_cents, or dropping a paid measurement) needs a key made by the owner or an admin. Other keys may send the pay unchanged or leave it out, and it stays as it is.

Example
PATCH /api/products/01M3JVF2952CTWCVJEE4MYBNHW
{
  "description": "Clean, brighten and stain both sides"
}

200
{
  "ok": true
}
POST/api/products/bulk

Duplicate or delete. Delete retires (active=0). Duplicate copies name, price, cost, unit, description, measures and tiers, name suffixed " (copy)".

Example
POST /api/products/bulk
{
  "ids": [
    "01M3JVF2952CTWCVJEE4MYBNHW"
  ],
  "action": "duplicate"
}

200
{
  "done": 1,
  "skipped": []
}
GET/api/product-tiers?product_id=

Good / better / best prices for one item.

Example
GET /api/product-tiers?product_id=01M3JVF2952CTWCVJEE4MYBNHW

200
[]
PUT/api/product-tiers/:productId

Replace those tiers. Owner or admin key.

Example
PUT /api/product-tiers/01M3JVF2952CTWCVJEE4MYBNHW
{
  "tiers": [
    {
      "name": "Good",
      "unit_price_cents": 325
    },
    {
      "name": "Better",
      "unit_price_cents": 350
    },
    {
      "name": "Best",
      "unit_price_cents": 395
    }
  ]
}

200
{
  "ok": true,
  "count": 3
}
GET/api/quote-templates

Reuse "deck refresh" instead of rebuilding lines.

Example
GET /api/quote-templates

200
[]
POST/api/quote-templates

Save a set of lines to start quotes from: name, title, line_items[].

Example
POST /api/quote-templates
{
  "name": "Fence refresh",
  "title": "Fence staining",
  "line_items": [
    {
      "name": "Fence staining",
      "quantity": 1,
      "unit_price_cents": 70000
    }
  ]
}

201
{
  "id": "01M3JVF2SF7TX56SKWWT9GWK1T"
}
PATCH/api/quote-templates/:id

Change one.

Example
PATCH /api/quote-templates/01M3JVF2SF7TX56SKWWT9GWK1T
{
  "name": "Fence refresh, both sides"
}

200
{
  "ok": true
}
DELETE/api/quote-templates/:id

Take one off.

Example
DELETE /api/quote-templates/01M3JVF2SF7TX56SKWWT9GWK1T

200
{
  "ok": true
}
GET/api/job-types

The kinds of work this shop does.

Example
GET /api/job-types

200
[]
POST/api/job-types

Add a kind of work: name. Owner or admin key.

Example
POST /api/job-types
{
  "name": "Fence staining"
}

201
{
  "id": "01M3JVF2SJ1VK2T3K334GBET31"
}
PATCH/api/job-types/:id

Change one. Owner or admin key.

Example
PATCH /api/job-types/01M3JVF2SJ1VK2T3K334GBET31
{
  "name": "Fence staining and sealing"
}

200
{
  "ok": true
}
GET/api/client-types

Residential, commercial, and the rest of the labels.

Example
GET /api/client-types

200
[]
POST/api/client-types

Add a label: name, optional payment_terms_days, deposit and terms. Owner or admin key.

Example
POST /api/client-types
{
  "name": "Property manager",
  "payment_terms_days": 30
}

201
{
  "id": "01M3JVF2SN7PJXX8F6PYJP7QJ2"
}
PATCH/api/client-types/:id

Change one. Owner or admin key.

Example
PATCH /api/client-types/01M3JVF2SN7PJXX8F6PYJP7QJ2
{
  "payment_terms_days": 15
}

200
{
  "ok": true
}
GET/api/expense-presets

Saved spends: five gallons of stain, a dump run.

Example
GET /api/expense-presets

200
[]
POST/api/expense-presets

Save one: name, unit_amount_cents, category. Owner or admin key.

Example
POST /api/expense-presets
{
  "name": "Stain, 5 gal",
  "unit_amount_cents": 18000,
  "category": "materials"
}

201
{
  "id": "01M3JVF2SQNJAX8PHKTHE4MQGD"
}
PATCH/api/expense-presets/:id

Change one. Owner or admin key.

Example
PATCH /api/expense-presets/01M3JVF2SQNJAX8PHKTHE4MQGD
{
  "unit_amount_cents": 18500
}

200
{
  "ok": true
}
GET/api/term-sets

The contract texts a quote can carry.

Example
GET /api/term-sets

200
[]
POST/api/term-sets

Add one: name, body. Owner or admin key.

Example
POST /api/term-sets
{
  "name": "Commercial",
  "body": "Net 30. Work guaranteed for two years."
}

201
{
  "id": "01M3JVF2ST847A61MQ99X1D97D"
}
PATCH/api/term-sets/:id

Change one. Owner or admin key.

Example
PATCH /api/term-sets/01M3JVF2ST847A61MQ99X1D97D
{
  "body": "Net 30. Work guaranteed for three years."
}

200
{
  "ok": true
}
GET/api/tags

Tags on customers and work.

Example
GET /api/tags

200
[]
POST/api/tags

Add a tag: label, optional color.

Example
POST /api/tags
{
  "label": "Repeat customer",
  "color": "#2b8ba3"
}

201
{
  "id": "01M3JVF2S9NDVPTM0VYY7EFM7K"
}
POST/api/tags/assign

Put a tag on something: tag_id, entity_type, entity_id.

Example
POST /api/tags/assign
{
  "tag_id": "01M3JVF2S9NDVPTM0VYY7EFM7K",
  "entity_type": "client",
  "entity_id": "01M3JVF1K1XS5ZJKJG6RF2TBXE"
}

200
{
  "ok": true
}
GET/api/custom-fields

The shop's own fields on customers and work.

Example
GET /api/custom-fields

200
[]
POST/api/custom-fields

Add a field: entity_type, label, kind. Owner or admin key.

Example
POST /api/custom-fields
{
  "entity_type": "client",
  "label": "Gate code",
  "kind": "text"
}

201
{
  "id": "01M3JVF2SCNVQYFX8K9Z74D7RD"
}
GET/api/custom-fields/values/:entityType/:entityId

One record's answers, by field id.

Example
GET /api/custom-fields/values/client/01M3JVF1K1XS5ZJKJG6RF2TBXE

200
{
  "01M3JVF2SCNVQYFX8K9Z74D7RD": "4411"
}
PUT/api/custom-fields/values/:entityType/:entityId

Save answers: { "field id": "value" }. Fields the shop never made are ignored.

Example
PUT /api/custom-fields/values/client/01M3JVF1K1XS5ZJKJG6RF2TBXE
{
  "01M3JVF2SCNVQYFX8K9Z74D7RD": "4411"
}

200
{
  "ok": true
}
GET/api/pipeline-stages

Funnel columns. Do not make these up.

Example
GET /api/pipeline-stages

200
{
  "stages": [
    {
      "id": "01M3JVF27ZNCZTSYV78D9JCXCW",
      "key": "new_lead",
      "label": "New lead",
      ...
    },
    ...
  ],
  "events": [
    {
      "id": "lead_created",
      "label": "A new lead arrives"
    },
    ...
  ]
}
POST/api/pipeline-stages

Add a column: label. Owner or admin key.

Example
POST /api/pipeline-stages
{
  "label": "Site walked"
}

201
{
  "id": "01M3JVF2T2YKDHKQZV5A6WYGG5",
  "key": "site_walked"
}
PATCH/api/pipeline-stages/:id

Rename or recolor one. Owner or admin key.

Example
PATCH /api/pipeline-stages/01M3JVF2T2YKDHKQZV5A6WYGG5
{
  "label": "Site visited"
}

200
{
  "ok": true
}
GET/api/admin/prefs

Hours, quiet hours, templates, deposits, follow-ups.

Example
GET /api/admin/prefs

200
{
  "prefs": {
    "business_phone": "",
    "business_email": "",
    "business_address": "",
    "business_address_public": "0",
    "review_link": "",
    "day_start_hour": 6,
    "default_visit_hours": 8,
    "default_visit_start": "08:00",
    ...
  },
  "defaults": {
    "business_phone": "",
    "business_email": "",
    "business_address": "",
    "business_address_public": "0",
    "review_link": "",
    "day_start_hour": 6,
    "default_visit_hours": 8,
    "default_visit_start": "08:00",
    ...
  }
}
GET/api/admin/settings

The saved settings, secrets left out.

Example
GET /api/admin/settings

200
{ "measures_enabled": "1", "doc_show_measures": "1", "quote_expiry_days": "21", ... }
PUT/api/admin/settings

Change hours, templates, numbering, follow-ups, measures_enabled. Allowlisted keys only; anything else comes back in ignored. Turning late fees on (late_fee_mode to percent or flat) also adds the fee to invoices that are already past due, not just new ones; the app asks first, a key does not.

Example
PUT /api/admin/settings
{ "measures_enabled": "1", "quote_expiry_days": "21", "card_fee_percent_bp": "300" }

200
{ "ok": true, "ignored": [ "card_fee_percent_bp" ] }

Measurements

How a price-book item is measured: linear feet, square feet, gates. Owner or admin key to change them.

GET/api/measures/types

Names of things you count (sq ft, ln ft).

Example
GET /api/measures/types

200
[
  {
    "id": "01M3JVF292GEWN4HWR0GREQQ28",
    "tenant_id": "ten_flow",
    "name": "Linear feet",
    "unit": "ln ft",
    "sort_order": 0,
    "active": 1,
    "created_at": "2026-09-28T01:53:25.794Z"
  },
  ...
]
POST/api/measures/types

Add a unit you count: name, unit.

Example
POST /api/measures/types
{
  "name": "Linear feet",
  "unit": "ln ft"
}

201
{
  "id": "01M3JVF292GEWN4HWR0GREQQ28"
}
PATCH/api/measures/types/:id

Rename one. Owner or admin key.

Example
PATCH /api/measures/types/01M3JVF292GEWN4HWR0GREQQ28
{
  "name": "Linear feet of fence"
}

200
{
  "ok": true
}
GET/api/measures/products

Every measured item's rates.

Example
GET /api/measures/products

200
[
  {
    "id": "01M3JVF295J4AXJECSQWP36B7K",
    "tenant_id": "ten_flow",
    "product_id": "01M3JVF2952CTWCVJEE4MYBNHW",
    "measure_type_id": "01M3JVF292GEWN4HWR0GREQQ28",
    "unit_price_cents": 350,
    "unit_cost_cents": 40,
    "pay_per_unit_cents": 100,
    "sort_order": 0,
    "created_at": "2026-09-28T01:53:25.797Z",
    "active": 1,
    ...
  }
]
GET/api/measures/products/:productId

Rates, materials and crew floor for one item.

Example
GET /api/measures/products/01M3JVF2952CTWCVJEE4MYBNHW

200
{
  "crew_minimum_cents": 15000,
  "measures": [
    {
      "id": "01M3JVF295J4AXJECSQWP36B7K",
      "tenant_id": "ten_flow",
      "product_id": "01M3JVF2952CTWCVJEE4MYBNHW",
      ...
    },
    ...
  ]
}
PUT/api/measures/products/:productId

Replace rates, materials, crew floor. Owner or admin keys only.

Example
PUT /api/measures/products/01M3JVF2952CTWCVJEE4MYBNHW
{
  "crew_minimum_cents": 15000,
  "measures": [
    {
      "measure_type_id": "01M3JVF292GEWN4HWR0GREQQ28",
      "unit_price_cents": 350,
      "unit_cost_cents": 40,
      "pay_per_unit_cents": 100,
      "split_mode": "split"
    }
  ]
}

200
{
  "ok": true,
  "count": 1
}

Inventory

Stock with its versions (colors, sheens, sizes), where it sits, every change to it, and tools and equipment. Read only for keys for now: changing stock happens in Chalk. Costs come back only when the person the key acts as can see job prices. Quantities can have decimals (2.5 gallons); money is in cents.

GET/api/inventory/summary

Counts at a glance: items, versions, running low, tools out and overdue. ready is false until Inventory is set up.

Example
GET /api/inventory/summary

200
{
  "ready": true,
  "items": 24,
  "versions": 41,
  "low": 3,
  "value_cents": 286400,
  "tools": 9,
  "tools_out": 2,
  "tools_overdue": 1,
  "tools_repair": 0,
  "locations_on": false,
  "settings": { "cost_mode": "planned", "on_complete": "ask", "low_alerts": true, "overdue_alerts": true, "tool_due_days": 1 }
}
GET/api/inventory/items

The stock list. Optional ?q= (name, SKU, supplier, version), group=, low=1, archived=1, limit= (up to 200). total is the whole count; pass next_cursor back as cursor= for the next page.

Example
GET /api/inventory/items?q=stain&low=1

200
{
  "items": [
    {
      "id": "01M3JVF2952CTWCVJEE4MYBNHW",
      "name": "Semi-transparent deck stain",
      "group": "Stains and sealers",
      "unit": "gallon",
      "pack_size": 1,
      "cost_cents": 4050,
      "price_cents": null,
      "low_at": 4,
      "reorder_qty": 10,
      "sku": null,
      "supplier": "Paint store",
      "attributes": ["Color"],
      "on_hand": 9,
      "low": true,
      "value_cents": 36450,
      "variants": [
        { "id": "01M3JVF295J4AXJECSQWP36B7K", "item_id": "01M3JVF2952CTWCVJEE4MYBNHW", "label": "Cedar", "values": { "Color": "Cedar" }, "is_default": false, "sku": null, "cost_cents": null, "low_at": null, "on_hand": 3, "low": true, "archived": false }
      ],
      "starter_key": "stain_semi_transparent",
      "archived": false,
      "updated_at": "2026-10-17T14:02:11.000Z"
    }
  ],
  "groups": ["Coatings", "Stains and sealers", "Sundries"],
  "total": 1,
  "next_cursor": null
}
GET/api/inventory/items/:id

One item with its versions, its newest 50 changes and what points at it (price-book materials and common expenses).

GET/api/inventory/moves

Every stock change, newest first. Optional item_id=, variant_id=, job_id=, kind= (received, used, returned, adjusted, counted, moved, starting, carried_over), cursor=.

GET/api/inventory/shopping-list

Everything running low, grouped by supplier, with a suggested amount to buy.

GET/api/inventory/locations

The places stock can sit, and whether more than one is switched on.

GET/api/inventory/assets

Tools and equipment. Optional status= (available, out, overdue, repair, retired, archived), q=, mine=1. /api/inventory/assets/:id adds who had it and when.

GET/api/inventory/export.csv

Every item and version as a spreadsheet, one row per version.

GET/api/inventory/starters

The starter lists for each trade, and which keys the shop already added. /api/inventory/price-book-candidates lists the price-book materials and what each is linked to.

When something happens, we tell you

These fire today from Settings, Connectors: a Zapier URL or your own webhook. They are not waiting on developer keys. The names are the ones the funnel actually sends.

lead_created

A new lead arrives, including one from the website form or ingest.

assessment_booked

An estimate visit is booked.

quote_created

A quote is started.

quote_sent

The quote is sent.

quote_viewed

The customer opens the quote.

changes_requested

The customer asks for changes.

job_created

The work is booked in.

Never open to a key

A key can run the shop, but a few doors only open for a person who is signed in, whatever the key holds. A key that asks gets a 403 that says: "This part of Chalk is only available when signed in, not with an API key."

Signing in and people

Signing in, sessions and trusted devices. Making a login, invites, password reset links, calendar feed links and push sign-ups, since each would outlive the key. Seeing the app as somebody else. Changing an owner, an admin, or the person who made the key.

The account itself

Paying Chalk (plans, ChalkBot credits, text packs), closing the account, imports, backups and restoring one, the whole-account export, and setting up a new account.

Keys, wiring and ChalkBot

Making, changing or revoking API keys. Connecting Stripe, QuickBooks, the text number and email (a key can only read whether texting and email are ready). Asking ChalkBot, approving for it, its leash and its wallet; reading what it did is open.

A person's call

The client timeline, turning a customer's texts back on, resuming paused automations (a key can pause them), sending an automation test, and deleting a photo off every record at once. The estimator's own key and where the owner digest goes never change with a key.

FAQ

Can I call this today?

Yes, if you are on the AI plan ($99 a month) and an owner or admin made a key in Settings, Connectors, Custom API (or Settings, ChalkBot). Core ($49) shops use the browser. The website estimator ingest key is a different thing, and it stays on every plan.

Is this a second API for the AI?

No. The assistant and your own software hit the same commands. Same shop, same rules. The difference is the key, not a private back door.

What about Core plan shops?

Core ($49) already has the whole toolkit in the browser. It cannot mint or use developer keys. ChalkBot and those keys sit on the AI plan ($99). Website lead forms keep working on Core. There is no Core one-off developer key.

Is there an OpenAPI spec?

Yes: openapi.json, OpenAPI 3.1. It lists every command a key may call and the permission each needs, built from the same list the server checks.

Will a send actually text someone?

Yes, if the shop has a number or email wired. Sends Chalk queues, like a quote, an invoice or a reminder, wait for the shop's texting hours. A reply through /api/messages/send goes at once, like one typed in the app, so quiet hours do not hold it. If neither channel is ready, the call tells you that instead of failing silently.

The board is already live.

Make a key in Settings → Connectors → Custom API if you are on the AI plan. If you are building against this, say hello.