Simpro API: a worked example with n8n

n8n’s Schedule Trigger runs a workflow “at fixed intervals and times”.⁷ Simpro also offers webhooks, so a workflow can be told when a record changes instead of asking. Each webhook message carries an X-Response-Signature header, an SHA1 HMAC of the body made with a secret you choose, so you can check it came from Simpro.³

For a morning check, a schedule is simpler. You know when it runs, and a missed run is easy to spot.

Getting a Simpro API key. API access is tied to your own Simpro build. Follow the current steps in Simpro’s Developer Center (see the sources), then keep the key in an n8n credential, not in the workflow itself.⁶

Every Simpro route starts with a company. For a single-company build the company ID is 0, so routes begin /api/v1.0/companies/0. A multi-company build has more than one, and you choose which in each request.¹ Check this first, because the same workflow pointed at the wrong company returns valid data that is simply not yours.

Only what changed. Most Simpro handlers accept an If-Modified-Since header. Each response carries a Date header you can store and send next time.¹ The first call is:

GET /api/v1.0/companies/0/customerInvoices/ with If-Modified-Since set to the last run’s Date.⁴

Every page, not the first. A Simpro listing returns 30 results unless you ask for more, up to 250 with pageSize. The response headers Result-Total and Result-Pages tell you how many records and pages there are, and page picks the page.¹ In n8n’s HTTP Request node, turn on Pagination and set the mode to “Update a Parameter in Each Request”. Set page to {{ $pageCount + 1 }}, because $pageCount starts at zero and counts the pages fetched so far.^{5, 6}

Only the columns you need. The columns parameter limits what a listing returns. For a job, display=all returns its sections and cost centres in one call, instead of one call per level.¹ Simpro’s API also has Cost to Complete job reports, in operations and financial views.⁴

The definitions for job custom fields are at /setup/customFields/projects/, each with an ID, a name, a type and whether it is locked. A job’s values are at /jobs/{jobID}/customFields/, and you update one with a PATCH to /jobs/{jobID}/customFields/{customFieldID}.⁴

• Look up the ID by name at the start of each run from the setup list, and stop with a clear error if the name is not found. n8n’s Stop And Error node fails the run on purpose and triggers the error workflow.⁹
• Never assume an ID carries across companies, builds or a test copy. Look it up each time.
• Treat an empty value as a fail, not a pass. The sample’s INV-5102 is held for exactly that.

• Too many requests. Simpro returns HTTP 429 to an integration that sends more than 10 requests a second to one build, until the rate drops.² In n8n, use the HTTP Request node’s Batching option (items per batch and a batch interval), and turn on Retry On Fail with Max Tries and Wait Between Tries.⁶ Simpro suggests display=all, pagination and its multiple-record routes to cut the number of calls.²
• A job someone has open. An update to a job that is open in Simpro can fail. Wait, try again later, and if it still fails after a few tries, tell the person who owns the job.
• Bad data. A 422 response lists each problem with a path (the field) and the value Simpro received.¹ Retrying sends the same bad data again. Send it to a person with the path and value.
• Anything else. In n8n, set an error workflow in the workflow’s settings. It starts with the Error Trigger node and runs when an execution fails, so it can email someone.^{9, 10} Note that the Error Trigger only runs for automatic executions, not when you test by hand.¹⁰

The build also created or updated Simpro jobs. To create one, Simpro needs at least a job Type (Project, Service or Prepaid) and a Site ID.⁴ Here retries need care: if a create times out after Simpro has saved the job, a blind retry makes a second job. Before creating, search for the job by a reference you control, such as the order number, and update it if it is already there.

Held invoices go to a person. n8n’s Wait node can pause a run until it receives a webhook call or a form submission. The run is saved to the database while it waits, and each run gets its own resume URL, $execution.resumeUrl, which you can put in an email.⁸

In the sample, the reviewer gets one email each morning listing the held invoices and their reasons, with a link to a short form. For each one they choose “fixed in Simpro, recheck” or “leave held”. The workflow then rechecks the ones marked fixed. The person decides. The workflow does not change the invoice.