The Job Close Build Standard

1. What this standard covers

A trade or field service business whose techs finish jobs on site and whose invoices are raised from the job card: plumbing, electrical, air conditioning, fire, security, appliance repair. The standard starts when the tech says the work is done and ends when the job is marked complete in the job system, with a card that has the work done, the parts as price book lines, the labour, the photos and, where the business wants it, the customer’s sign-off.

It sits on the cash path between the Dispatch Board, which put the right tech at the house, and Invoice Out, which bills the completed job. It carries Cash Seam’s job id and adds none of its own. The field service roadmap explains why this handover was built first.

Out of scope. Raising, approving or sending the invoice, which is Invoice Out’s behind its own release. Ordering the parts before the job, which is Material Order’s. Pricing a variation and getting it signed, which stays with a person. Timesheets: labour on the card is what the customer is charged, not what the tech is paid, and Timesheet Check holds the second.

What cannot meet it. A job system with no write API. Tradify is the common one: a business on Tradify can run checks 1 to 6 on a sheet, and a person types the confirmed card in.

2. The close, in the shape your developer needs

Two records. What arrived from site, kept as it came; and the card it became, with where it was written and what came back.

close_request
  job_external_id   string        # read from the job system, never minted
  tech_id           string        # the assigned tech, read from the job
  captured_at       datetime
  inputs
    voice_note_uri?   string
    transcript?       string      # verbatim, stored before extraction
    notes?            string
    photos            [uri]
    parts_used        [{ spoken: string, qty: number }]

close_result
  work_done         string        # drafted from the transcript; the tech confirms
  lines
    - kind            part | labour | callout
      catalogue_code? string      # resolved from the price book only
      qty             number
      unit_price?     number      # read_pricebook at close time, never typed
      source          pricebook | parked
  parked            [{ spoken, reason: not_in_book | ambiguous | variation }]
  photos_attached   [external_id]
  signoff?          { name, at }
  confirmed         { by: tech_id, at, draft_id }
  written           { system: servicem8 | simpro | aroflo | fergus | native,
                      intent_id,    # close:<tenant>:<job>:<capture>
                      external_ids: [string] }
  status            closed | closed_with_parked | not_written

A line with no catalogue code, a confirmation from anyone but the assigned tech, and a completion with no external ids are the three defects this schema exists to make visible.

3. The checks, in order

The order is the order a close runs, and each step guards the next. The job is read before anything is kept, so a wrong job number never reaches the price book. What was said is kept before it is priced, so the card can always be set beside the words. The price book is read again at the write, not at the draft, because a draft can sit for an hour while someone fixes a price. And completion is last, because it is the only signal Invoice Out acts on: a job marked complete with no card behind it is an invoice for nothing.

1. The job exists and this tech is on it. A close starts from the job id the job system issued, read back from the job system before anything else. No job, no close: a close is never the thing that creates a job. A capture from a tech who is not assigned to that job goes to the office, not onto the card.
2. What the tech said is stored before anything is taken from it. The transcript, the notes, the photos and the parts as spoken are kept word for word as evidence first. The draft is worked out from the stored copy, so what the tech said can always be set beside what was written.
3. Every part is a price book line or it is parked. Each part the tech names resolves to exactly one catalogue line in the business's own price book, at the price the book holds when the card is written. A part that matches nothing is parked as not_in_book; one that matches more than one line is parked as ambiguous. No price is ever estimated, averaged or remembered.
4. A variation is never priced at close. On a quoted job, a part or line the quote did not cover is parked as a variation and goes to the person who prices variations. It is not put on the card at any price, even one the book holds. Invoice Out bills it only once the customer has signed for it.
5. The tech confirms the draft before it is written. The draft goes to the tech in one message: the work done, the lines, and what was parked. Only a yes from the assigned tech's own number, naming that draft, lets it be written. A yes from the office, or a draft the model marked confirmed itself, is not the tech's confirmation.
6. A draft nobody confirms goes to the tech's supervisor. If the tech has not confirmed within the written window, two hours by default, the draft is raised as not_confirmed to the tech's supervisor, once. It is not written and the job is not marked complete while it waits.
7. One write, with the job system's ids back. The card, its lines and its photos are written once, with the intent id close:<tenant>:<job>:<capture>. A retry carries the same intent id and lands once. A write that returns no ids is treated as not written and raised as write_failed to the office manager.
8. The job is marked complete only after the write returns ids. Completion is the last step and the only trigger Invoice Out accepts, so it happens only once the write has come back with the job system's ids. A parked item does not hold completion: it travels to Invoice Out, which parks the invoice.
9. Every parked item goes to the exceptions queue with an owner. Each part not in the book, ambiguous match and variation is raised once to the Exception Desk queue with the job id, the tech's words exactly and a named owner: the office manager for a part, the variation pricer for a variation. Nothing parked is left only in a message.
10. The close is on the record, by job. For each job: what the tech sent, what was taken from it, who confirmed it and when, and what the write returned, ids or the reason it failed. The history of one close can be read in one place.
11. It survives the builder. Someone other than the builder can explain what it does, and it runs on an account the business owns.
12. The pass test passes. On a real job in the business's own ServiceM8 or Simpro: a thirty-second voice note naming one part in the price book and one that is not, and two photos. Within five minutes the card shows the work done, the known part at the book price, both photos and the job complete; the unknown part is on the exceptions list, not the card. Sent again, nothing duplicates.

4. One close, from the roof space to complete

Mia’s job again, J100, a do-and-charge call-out with no quote, run to this standard.

1. 2:00pm. Sent from site. Mia records thirty seconds: “Replaced the leaking tempering valve under the house and two 15 mil elbows. Also swapped the Rheem element, three point six kilowatt. About an hour and a half all up.” Two photos, job J100.
2. 2:00pm. Checked and kept. J100 is in the job system and Mia is on it. The note, the transcript and both photos are stored as they came.
3. 2:01pm. Priced, and one thing parked. “Tempering valve” is one line in the book, TMV15. “15 mil elbow” is CU15-ELB, two of them. An hour and a half is the labour line. “Rheem element 3.6kW” is not in the book, so it is parked as not_in_book. Nothing is guessed.
4. 2:01pm. One message to Mia. The work done, the three lines, and “parked for the office: Rheem element 3.6kW”. She replies YES with the draft number.
5. 2:03pm. Written, on the second try. The first write times out in the roof space. It is treated as not written and raised. The retry goes under the same id, close:harbour:J100:C1, and the job system answers with the ids of the card it already holds. One card, three lines, two photos.
6. 2:03pm. Complete, and the element to the office. The job is marked complete. The element goes to the exceptions queue with Mia’s words and the office manager’s name. Invoice Out sees the completed job and parks the invoice until the element is priced.

5. What gets parked, and whose it is

A part is parked rather than priced when the book does not hold it, when the tech’s words match two lines (“flexi hose” when the book has a 300mm and a 450mm), or when the job was quoted and the part is not on the quote. The last one is a variation even if the book has a price for it, because what the customer agreed to pay for is the quote, and anything beyond it needs their signature first. Each parked item goes to one exceptions queue with the job id, the tech’s words and an owner. The Exception Desk standard, next on the roadmap, is the queue every standard will share.

A parked item never holds up completion. The job is complete when the work is; the parked part travels to Invoice Out, which parks the invoice until a person prices it. That keeps the two questions apart: was the job done, and what do we charge for it.

6. Writing it once

This is the step not to hand-roll. Drafting the work-done text is the easy part: a coding agent does it in an afternoon. The hard part is an authenticated write of the card, its lines and its photos into a job system you do not own, priced only from the business’s own book, that holds across retries from a phone on a bad signal.

• ✓One id, every try: close:<tenant>:<job>:<capture>, made from things that do not change between tries. Never a timestamp or a random number: those make a new card on every retry.
• ✓No ids, not written: a write that times out may have landed. It is treated as not written, raised as write_failed, and tried again under the same id. The job system's answer to the retry is the truth.
• ✓Complete last: the status change is a separate, final step, made only after ids come back. A failed write never leaves a completed job behind it.
• ✓Lines need a code: a line with no catalogue code is refused before it is sent. The job system's invoicing, and Invoice Out, both price by code.

7. What stays with a person

• ✓Confirming the draft: the tech on the job, from their own phone.
• ✓Pricing every part parked as not in the book or matching two lines.
• ✓Pricing every variation, and getting the customer to sign for it.
• ✓Chasing a tech who has not confirmed, as their supervisor.
• ✓Fixing a write that failed, and keeping the price book's aliases in step with what the techs say.
• ✓Sending the invoice, through Invoice Out's release.

8. Run it your way

The same checks and the same pass test hold whichever way you run it, and the job id is the job system’s in every one. Mix them if you like: a sheet for the drafts and Office Voice for the write, once it ships. What matters is that one surface owns each step for your business, so two of them never write the same card (run a standard anywhere sets out the rules).

9. With a Grok Bot or Claude, without it guessing a price

Think of the bot as the apprentice in the passenger seat who fills in the job sheet while you drive: they write down what you said, look each part up in the price list, read it back, and only file it when you nod. The bot never prices from memory, never decides a part is close enough, and never saves a card you did not confirm. Your logins stay yours: the bot holds a key you can delete.

What each piece of access is for.

• Read the book, on an Office Voice key. Lets the bot read the job by its number (read_job) and your price list in Xero (read_pricebook). It comes with Connect at $19a month per business. That is enough for checks 1 to 6: the job, the price, the parking and the tech’s yes.
• The write, when close_job ships. Office Voice’s close_job will write the card, lines and photos into ServiceM8 or Simpro once per intent id and mark the job complete. It is being built and is not live. Until it is, the bot hands the confirmed card to the office to type in.
• Not ServiceM8’s own connector, for the write. It can add a note and change a job’s status, but its published list of actions has no job materials or attachments and nothing carries an intent id, so a retry could double the note and the job could be marked complete with no lines behind it. That fails checks 7 and 8.

1. Under Keys (office-voice.com/app/keys), create a key with Read the book only, and add it to the bot as the Grok Bot and Xero guide sets out. The same key works in Claude.
2. Tell the bot, in its standing instructions: read the job first and stop if the sender is not its tech; keep the tech’s words as they came; price only from read_pricebook, one match or park it; park anything not on the quote; send the draft back and wait for the tech’s yes.
3. Have the bot put every parked item on one list with the job number, the tech’s words and who owns it.
4. Run the checklist in section 12 against a real job.

Why not let the bot price it? Grok Bot and Claude will both happily tell you what a tempering valve costs. That number is the model’s, not yours, and it will be wrong in the way that costs you money: plausible. The book is the only price.

Facts that can change, and when we checked them

11. What your developer builds, and the step that needs care

The step not to hand-roll is the write: one authenticated, idempotent write of the card, lines and photos into a job system you do not own, priced only from the business's own book. Office Voice's close_job will hold it and is not live yet. Everything before it is yours, and it is the free part.

provider:
  stub:       local.mock_job_close
  production: none                       # scoped build, not a product

stub                                 # local.mock_job_close
  - a job store with assigned techs, a price book,
    captures, replies, and a job system that keeps
    one card per intent id
  - proves checks 1 to 10 in shape

production                           # coming: Office Voice close_job
  - read_job, read_pricebook         # live today
  - close_job(job_external_id, work_done, lines[],
              photos[], intent_id)   # CLOSE-1, not live
  - close by SMS or MMS from site    # CLOSE-2, not live

stays local                          # yours, and the standard
  - the draft and the tech's confirmation
  - the parking rules and the owners
  - the record of every close, by job

Anyone selling you an AI that fills in job cards should be able to answer one question: what happens to the second card when the first save times out?

12. A checklist to hold any build or supplier to

Hold a DIY build or a vendor to this. If a box is empty, it is not in production.

• ✓1. The job exists and this tech is on it. A close starts from the job id the job system issued, read back from the job system before anything else. No job, no close: a close is never the thing that creates a job. A capture from a tech who is not assigned to that job goes to the office, not onto the card.
• ✓2. What the tech said is stored before anything is taken from it. The transcript, the notes, the photos and the parts as spoken are kept word for word as evidence first. The draft is worked out from the stored copy, so what the tech said can always be set beside what was written.
• ✓3. Every part is a price book line or it is parked. Each part the tech names resolves to exactly one catalogue line in the business's own price book, at the price the book holds when the card is written. A part that matches nothing is parked as not_in_book; one that matches more than one line is parked as ambiguous. No price is ever estimated, averaged or remembered.
• ✓4. A variation is never priced at close. On a quoted job, a part or line the quote did not cover is parked as a variation and goes to the person who prices variations. It is not put on the card at any price, even one the book holds. Invoice Out bills it only once the customer has signed for it.
• ✓5. The tech confirms the draft before it is written. The draft goes to the tech in one message: the work done, the lines, and what was parked. Only a yes from the assigned tech's own number, naming that draft, lets it be written. A yes from the office, or a draft the model marked confirmed itself, is not the tech's confirmation.
• ✓6. A draft nobody confirms goes to the tech's supervisor. If the tech has not confirmed within the written window, two hours by default, the draft is raised as not_confirmed to the tech's supervisor, once. It is not written and the job is not marked complete while it waits.
• ✓7. One write, with the job system's ids back. The card, its lines and its photos are written once, with the intent id close:<tenant>:<job>:<capture>. A retry carries the same intent id and lands once. A write that returns no ids is treated as not written and raised as write_failed to the office manager.
• ✓8. The job is marked complete only after the write returns ids. Completion is the last step and the only trigger Invoice Out accepts, so it happens only once the write has come back with the job system's ids. A parked item does not hold completion: it travels to Invoice Out, which parks the invoice.
• ✓9. Every parked item goes to the exceptions queue with an owner. Each part not in the book, ambiguous match and variation is raised once to the Exception Desk queue with the job id, the tech's words exactly and a named owner: the office manager for a part, the variation pricer for a variation. Nothing parked is left only in a message.
• ✓10. The close is on the record, by job. For each job: what the tech sent, what was taken from it, who confirmed it and when, and what the write returned, ids or the reason it failed. The history of one close can be read in one place.
• ✓11. It survives the builder. Someone other than the builder can explain what it does, and it runs on an account the business owns.
• ✓12. The pass test passes. On a real job in the business's own ServiceM8 or Simpro: a thirty-second voice note naming one part in the price book and one that is not, and two photos. Within five minutes the card shows the work done, the known part at the book price, both photos and the job complete; the unknown part is on the exceptions list, not the card. Sent again, nothing duplicates.