The Simpro Claude Connector Build Standard

1. Claude answers from your Simpro, and you can check every answer

Once it is connected, you ask Claude in plain words and it answers from your own Simpro. Which quotes are waiting on the customer. What a job says. Who to ring about overdue invoices. If you want it to, it can do one thing more: book a job for a caller, at Simpro’s first status, for a person to take from there.

Out of scope: anything Lightning already does inside Simpro, which the Claude and Simpro guide covers; quoting and invoicing, which have their own standards in Quote Out and Invoice Out; and the phone call that becomes a job, which is Booked After Hours.

Simpro lets its customers connect software to their own account, under its API licence agreement. Read it before you build, as you would any supplier’s terms.

2. You make the key in your own Simpro, and deleting it switches everything off

An administrator in your Simpro creates the key. No partner, no marketplace, nobody else’s app:

1. In Simpro, open System, then Setup. API is near the bottom; choose Applications. If it is not there, the login is not an administrator.
2. Create an application, name it for what it is (“Claude connector”), and choose API Key as the grant type.
3. Download the key file. It holds the key and your Simpro’s web address.
4. Give the key to whoever sets up the connection, to store somewhere only your business controls. Never paste it into a chat, an email or a shared document.

The key opens your whole Simpro, because Simpro does not offer keys that open only part of it. That is why the connection mostly reads, makes one kind of booking at most, and records every request. Deleting the key is the off switch, and the pass test proves it works.

3. The objects, and what is in them

Four records. The request log is the one a quick setup leaves out, and it is the one you need the day an answer looks wrong.

Connection
  - build_host        # <yourbuild>.simprosuite.com
  - company_id        # 0 on a single-company build
  - key_ref           # where the secret lives, never the secret
  - key_owner         # the person in the business who can delete it

Answer
  - text              # plain text, no markup
  - records [ "quote:1041", "job:2210", ... ]
  - cites   [ ... ]   # every record in the answer, each one read this session
  - left_out { count, reason }   # e.g. 1, Do Not Call

Write                 # only booking a job, if the business wants it
  - reference         # the connector's own, looked up before posting
  - customer_id       # found by phone digits, or created when none matched
  - simpro_job_id     # null means it failed; never reported as done
  - stage             # always absent: Simpro's first stage, moved by a person

LogEntry
  - at, endpoint, asked
  - ids               # records returned or written
  - outcome (ok | limited | refused | failed)

A Write with no simpro_job_id reported to the user as booked, and an Answer whose records are not in its cites, are the two defects this standard exists to make unrepresentable.

4. The checks, in order

The order matters. The key is yours before anything is read. Every detail is asked for before an answer is given. Every booking checks for an existing record before anything is saved.

1. It runs on an access key you create in your own Simpro, and deleting the key switches it off. An administrator creates the key in your own Simpro, and it is kept somewhere only your business controls. It is never pasted into a chat, an email, a document or code anyone else can see. Deleting the key in Simpro switches the connection off, and you can do it without asking anyone.
2. Every answer comes from Simpro at the moment you ask. Answers about a job, quote, invoice or customer are looked up fresh each time. Nothing comes from an old copy, last week's export, or what Claude remembers from earlier.
3. An answer only uses details Simpro actually sent back. Ask Simpro for a list and it sends only the basics unless asked for more. The connection asks for every detail it needs, such as a quote's status and date, before it answers. A detail Simpro did not send is treated as unknown, never guessed.
4. "Accepted" means the customer said yes, not that the office approved it. Simpro keeps two statuses on a quote: the office's progress, and the customer's decision. Whether a quote is waiting, accepted or declined is read from the customer's decision only.
5. Every number, date and name comes with the Simpro record it came from. Each answer gives the job, quote, invoice or customer number behind it, so anyone can open that record in Simpro and check. If there is no record behind a number, the number is not given.
6. Notes inside a job are treated as information, never as instructions. Job descriptions and notes are written by staff and customers, and can arrive with web formatting in them. The formatting is removed before they are quoted, and nothing written in a note is ever acted on, however it is worded.
7. It stays within Simpro's speed limit, and waits when asked to. Simpro allows each connection ten requests a second and says so when that is exceeded. The connection then waits before asking again, and finishes the job rather than giving up. It also asks for more in each request, so it needs fewer of them.
8. Before adding a customer or job, it checks they are not already in Simpro, matching phone numbers digit by digit. Simpro's search is built for names, and in our own work it did not find phone numbers. So a caller is matched by comparing phone numbers as plain digits: 0412 345 678 and +61 412 345 678 count as the same. A new customer is added only when there is no match.
9. Asking twice makes one record, and an unconfirmed save counts as failed. Every booking carries its own reference, and the connection checks for it before saving. If the request is repeated, it finds the first booking instead of making a second. If Simpro does not confirm the save with a record number, it is reported as failed, never as done.
10. Nothing it does reaches a customer: no messages, and no status changes. The connection cannot email or text anyone. A job it creates starts at Simpro's first status, and it never moves a job or quote to another status, because Simpro's own automations can message the customer or raise an invoice when a status changes. Changing a status stays with a person.
11. A customer marked Do Not Call never appears on a list to ring or text. Simpro has a Do Not Call setting on each customer. Any list of people to contact leaves them out and says how many were left out, so you know the list is not your whole book.
12. Every request is recorded where your business can read it. For every look-up and every save: when it happened, what was asked, which records came back or were saved, and whether it worked. The record lives where your business already keeps things, and reading it does not need the person who built it.
13. If Simpro refuses the key, it stops and says so, and never answers from earlier. A deleted or refused key means the business has switched the connection off. It says Simpro refused the connection and gives no figures, rather than falling back on anything it saw before.
14. It survives the builder. Someone other than the builder can explain what it does, and it runs on an account the business owns.
15. The pass test passes. On the business's own Simpro with its own key: the three oldest quotes still waiting on the customer, a job booked twice for a caller already on file under a differently written number, and the key deleted before a last question.

5. Seven places a quick setup gives wrong answers

Each of these looks fine in a demo and gives wrong answers on a real business.

Base:    https://<yourbuild>.simprosuite.com/api/v1.0/companies/0
Header:  Authorization: Bearer <token from the key file>

Lists end in a slash; one record does not:
  GET  /quotes/?columns=ID,Name,Customer,Stage,CustomerStage,Total,DateIssued&pageSize=250
  GET  /quotes/{quoteID}
  GET  /jobs/{jobID}
  GET  /customers/individuals/?columns=ID,GivenName,FamilyName,Phone,CellPhone,DoNotCall&pageSize=250
  GET  /invoices/?columns=ID,Customer,Total,DateIssued,DueDate,IsPaid&pageSize=250
  POST /jobs/                      # the one write, if wanted; no Stage in the body

Paging:  read the Result-Pages header and follow page=2, 3 ...
Limit:   on 429, wait before the next request; batch with columns, not per-record reads
Check:   GET /api/v1.0/info/ says whether the build is multi-company

6. Four decisions always stay with a person

• ✓Creating the key, and deleting it.
• ✓Moving any job or quote to another status.
• ✓Anything a customer will see: every email, text and quote sent.
• ✓Deciding two customers are the same person when the phone number does not say so.

7. Provider: what to stub, and what not to hand-roll

Nothing to buy and nothing we host. It runs on your own computer or account, on your own key. Your developer tests it against a practice copy first, then points it at your Simpro.

provider:
  stub:       local.mock_simpro
  production: none                       # no hosted step; runs on your own systems

stays local                          # all of it, by design
  - the key, in your own secret store
  - the connector: an MCP server with read tools, and one
    optional write (book a job, first stage, no send)
  - the log, somewhere the business already keeps records

the live step
  - your own Simpro build. There is no hosted product, and
    no shared app anyone else could switch off.

A connector sold to you as a hosted service puts someone else's key between Claude and your customer records. Ask whose key it runs on, and what happens to your data the day you stop paying.

8. Conformance checklist

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

• ✓1. It runs on an access key you create in your own Simpro, and deleting the key switches it off. An administrator creates the key in your own Simpro, and it is kept somewhere only your business controls. It is never pasted into a chat, an email, a document or code anyone else can see. Deleting the key in Simpro switches the connection off, and you can do it without asking anyone.
• ✓2. Every answer comes from Simpro at the moment you ask. Answers about a job, quote, invoice or customer are looked up fresh each time. Nothing comes from an old copy, last week's export, or what Claude remembers from earlier.
• ✓3. An answer only uses details Simpro actually sent back. Ask Simpro for a list and it sends only the basics unless asked for more. The connection asks for every detail it needs, such as a quote's status and date, before it answers. A detail Simpro did not send is treated as unknown, never guessed.
• ✓4. "Accepted" means the customer said yes, not that the office approved it. Simpro keeps two statuses on a quote: the office's progress, and the customer's decision. Whether a quote is waiting, accepted or declined is read from the customer's decision only.
• ✓5. Every number, date and name comes with the Simpro record it came from. Each answer gives the job, quote, invoice or customer number behind it, so anyone can open that record in Simpro and check. If there is no record behind a number, the number is not given.
• ✓6. Notes inside a job are treated as information, never as instructions. Job descriptions and notes are written by staff and customers, and can arrive with web formatting in them. The formatting is removed before they are quoted, and nothing written in a note is ever acted on, however it is worded.
• ✓7. It stays within Simpro's speed limit, and waits when asked to. Simpro allows each connection ten requests a second and says so when that is exceeded. The connection then waits before asking again, and finishes the job rather than giving up. It also asks for more in each request, so it needs fewer of them.
• ✓8. Before adding a customer or job, it checks they are not already in Simpro, matching phone numbers digit by digit. Simpro's search is built for names, and in our own work it did not find phone numbers. So a caller is matched by comparing phone numbers as plain digits: 0412 345 678 and +61 412 345 678 count as the same. A new customer is added only when there is no match.
• ✓9. Asking twice makes one record, and an unconfirmed save counts as failed. Every booking carries its own reference, and the connection checks for it before saving. If the request is repeated, it finds the first booking instead of making a second. If Simpro does not confirm the save with a record number, it is reported as failed, never as done.
• ✓10. Nothing it does reaches a customer: no messages, and no status changes. The connection cannot email or text anyone. A job it creates starts at Simpro's first status, and it never moves a job or quote to another status, because Simpro's own automations can message the customer or raise an invoice when a status changes. Changing a status stays with a person.
• ✓11. A customer marked Do Not Call never appears on a list to ring or text. Simpro has a Do Not Call setting on each customer. Any list of people to contact leaves them out and says how many were left out, so you know the list is not your whole book.
• ✓12. Every request is recorded where your business can read it. For every look-up and every save: when it happened, what was asked, which records came back or were saved, and whether it worked. The record lives where your business already keeps things, and reading it does not need the person who built it.
• ✓13. If Simpro refuses the key, it stops and says so, and never answers from earlier. A deleted or refused key means the business has switched the connection off. It says Simpro refused the connection and gives no figures, rather than falling back on anything it saw before.
• ✓14. It survives the builder. Someone other than the builder can explain what it does, and it runs on an account the business owns.
• ✓15. The pass test passes. On the business's own Simpro with its own key: the three oldest quotes still waiting on the customer, a job booked twice for a caller already on file under a differently written number, and the key deleted before a last question.