Simpro in Agent Builder

The Simpro step lets an agent read and change records in your Simpro build as part of a run. It can list today's diary, fetch a job, add a note, raise a quote or record a payment. Each step does one thing, picked from 147 actions, and hands what Simpro sends back to the next step. The same connection also drives the Simpro webhook trigger, which starts an agent when something you have ticked changes in Simpro.

app.centrus.ai/app/agents/workflow-builder

Agents

Build modular AI workflows with reusable nodes

Today's diary

1,240 / 10,000 creditsValidateResetRunsSettingsUpdate & Publish

Weekdays at 16:00

Daily at 16:00 · Mon, Tue, Wed, Thu, Fri

Today's visits

List schedules · today

2

Write the briefing

GPT-5.6 Terra

Email the planners

1 action enabled

AI builderMap

1. 1Simpro in the Integration group of the Nodes panel.
2. 2The step on the canvas. Its summary shows the action, List schedules, and the date window today.
3. 3Connection: the Simpro build this agent uses, shown by its address.
4. 4Endpoint: the action the step performs, chosen from the full list.
5. 5The action's fields. Here the diary is limited to today.

Centrus works alongside Simpro. Your jobs, quotes and finance records stay in Simpro, and the agent reads and updates them there through Simpro's API. To ask about Simpro records in a conversation rather than in an agent, see Simpro in chat. Connecting Simpro in chat does not connect it here. How the two connections differ is covered in Integrations overview.

Open the agent in Agent Builder and find Simpro in the Integration group of the Nodes panel. It sits with the other job systems, after BigChange Web Services. Drag it onto the canvas and connect the step before it to its left-hand side. Until you choose an action, its summary on the canvas reads No endpoint selected.

Job finished

Job stage complete

Simpro

No endpoint selected

2

1. 1Simpro in the Integration group. Drag it onto the canvas.
2. 2The new step. It reads No endpoint selected until you choose an action in its Details panel.

On a phone, Agent Builder shows the canvas only. The Nodes panel is hidden on screens narrower than 768 pixels and the Details panel on screens narrower than 1,024 pixels, so you can follow an agent's steps on a phone but need a tablet or computer to add a Simpro step or change its settings.

09:41

Centrus

Agents

Build modular AI workflows with reusable nodes

Chase overdue invoices

Save and Publish

Weekdays at 16:00

Daily at 16:00 · Mon, Tue, Wed, Thu, Fri

Today's visits

List schedules · today

Write the briefing

GPT-5.6 Terra

Email the planners

1 action enabled

The Simpro connection belongs to this agent alone. It is separate from your Simpro connection in chat, so connecting one does not connect the other. One connection covers every Simpro step in the agent and its Simpro webhook trigger, so you only connect once per agent.

You need three values. Base URL is the address your team uses to open Simpro, such as https://meridianfm.simprosuite.com. It must start with https. Access token is the API key from Simpro's developer settings. Company ID is the company number Simpro uses in its API paths. Use 0 for a build with one company. On a build with several companies, use the ID of the company this agent should work in. The info icon on Company ID explains that 0 is a valid company number.

1. 1Save the agent with Save draft. Until it has been saved once, the Connection section reads Save this workflow as a draft first, then connect the account. and Connect is greyed out.
2. 2Select the Simpro step. In the Details panel, open Connection and click Connect.
3. 3In the Connect Simpro window, enter the Base URL, Access token and Company ID, then click Connect.
4. 4Connection now reads Connected, followed by the build address.

Centrus checks the address and the access token when you click Connect, by calling Simpro's company list. A wrong token or a build you cannot reach stops the save with Could not verify Simpro credentials. An address that is not https is refused before that check, with Simpro base URL must use https or Simpro base URL must be a valid https URL. After a successful connect, try the agent with a dry run, as described under Test before it goes live.

Reusing a connection. If you have already connected Simpro on another agent you created, choose that agent under Copy from existing agent. Centrus fills in the three fields from it, and you click Connect to save them on this agent. The list only shows agents you created that are not archived and have a Simpro connection, so an agent someone else shared with you never appears. When there are none, the box reads No other agents with this connection.

Sharing and copying the agent. When you share an agent, its Simpro connection stays with it, and everyone who runs it uses that connection rather than their own. When you duplicate an agent, the steps are copied but the connection is not, so connect Simpro again on the copy. Copy from existing agent makes that quick. For the details, see Share an agent.

Disconnecting. Disconnect removes the credentials from this agent only. Its Simpro steps and trigger stop working until someone connects it again, and other agents keep their own connections. The webhook secret, described under Start an agent from Simpro alerts, stays the same if you connect again.

Select the step and open Endpoint in the Details panel. Endpoint tool type holds all 147 actions in one list that starts with List companies, then the job and quote actions. The list has no search box and no headings, so the tables at the end of this guide are the quickest way to find the exact name you need.

Keep Set endpoint fields here on a step in the agent's main flow. Let AI populate endpoint fields hides the fields so that an AI can fill them, but on a main-flow step nothing fills them in when the step runs. To have an AI choose the values, attach the step to an Intelligence step as a tool instead, as described below.

Each action then shows its own fields in a box titled with the action's name. Get job has two boxes to fill: Simpro job ID (required) and Simpro company ID. Leave Simpro company ID empty to use the company you connected. The label on a field is the first sentence of its help text, and the same help is repeated underneath, so some labels read like instructions. A field with no help text is labelled from its name, such as Job Id and Subject on Create job note.

To use a value from an earlier step, open Step data references at the top of the Details panel and click a field to copy its reference, then paste it into a text field. Text fields, such as Subject, Note and Date Window, keep what you paste. Number boxes do not. Simpro job ID (required), Job Id, Quote Id and the other ID boxes only keep a number, so a reference such as the job id from a Simpro alert is dropped as you type it.

That is why a Simpro alert is usually followed by an Intelligence step that has the Simpro step as a tool, rather than by a Get job step with the id typed in. The AI reads the alert and fills the number itself. The examples below are built that way.

What the step passes on. When the step runs, it passes on what Simpro returned as items for the next step. Get job passes on one item, the job. A list action such as List schedules passes on one item per record, so six bookings become six items. Later steps reach their fields through Step data references, and an AI step reads all of the items together. Simpro's own names are kept, such as ID, Date, Staff and Blocks on a schedule. To create or change one record for each item, the field you are filling has to be a text field that can hold a reference. Where the id is a number box, use the step as a tool, or the Ingest step described under Large lists. Loops are described in Conditions, loops and approvals.

As a tool for an AI step. Connect a Simpro step to the Tools side of an Intelligence step and its Details panel changes. Instead of one endpoint, Actions lets you choose several, with a search box, and the AI decides when to call each one and fills in the fields itself. The step's summary on the canvas lists up to three actions, such as Get job, Create job note. Wide lists, such as every job in the company, are meant to run on the main path or through Ingest. Their info icon says not to attach them as a tool.

Job finished

Job stage complete

Write the visit note

GPT-5.6 Terra

Job and note

Get job, Create job note

1

1. 1The Simpro step attached to the Intelligence step as a tool.
2. 2Actions: the Simpro actions the AI may call. The AI fills the job ID from the alert.
3. 3Pause for approval: each call the AI makes waits for someone to approve it in the Runs panel.

Pause for approval appears on every Simpro step but only applies to calls an AI makes, so it has no effect on a step in the main flow. To ask someone before a main-flow step changes Simpro, put an Approval step in front of it.

The Simpro webhook trigger, in the Trigger group of the Nodes panel, starts the agent when Simpro reports a change you have ticked, such as a job reaching the complete stage. It uses the agent's Simpro connection, so if a Simpro step is already connected, the trigger is too. Setting up, testing and costs for every system are covered in Start an agent from a system alert. This section covers what is particular to Simpro.

Job finished

Job stage complete

Write the visit note

GPT-5.6 Terra

Job and note

Get job, Create job note

Email the office

1 action enabled

1. 1Connection, shared with the agent's Simpro steps. It is closed here, and reads Connected.
2. 2Event types: the events that start a run. Only Job stage complete is ticked. The line under each name is Simpro's event id.
3. 3Set this up in Simpro: the steps to follow in Simpro, the callback address and the secret.
4. 4Simulate webhook: runs the agent once with a sample alert. It does not call Simpro.

Every event it can listen for. There are 95 event types in 28 groups. Tick only the ones the agent needs, because each alert that matches starts a run and each run uses credits. The line under each name is the id Simpro uses, so you can match the ticks here to the events you select on the subscription.

Who sets it up, and where. Centrus does not create the subscription. Anyone who can edit the agent does the Centrus side. A Simpro administrator adds the subscription. If API is missing from the Setup menu, the person signed in is not an administrator. Set this up in Simpro lists the steps:

1. 1Connect Simpro on the trigger and save the agent. Copy the Secret. It stays the same if you reconnect.
2. 2In Simpro, sign in as an administrator. Open System, then Setup. Hover API near the bottom and choose Webhook Subscriptions.
3. 3Choose Create Subscription. Enter a name. Email is optional. Simpro may send debug mail there.
4. 4Paste the secret from this node into Secret, and the Callback URL into Callback URL. The address is https://api.centrus.ai/agent-builder-v2/webhooks/simpro.
5. 5Select the same events as the ticks on this node. Set Status to Enabled. Save.
6. 6Choose Test Subscription. Centrus accepts the test and does not start a run.

Unticking an event in Centrus does not stop Simpro sending it until you edit that subscription. A second Centrus agent on the same build needs its own subscription and its own secret. Centrus only matches alerts from the build address you entered when you connected, including a missing www or a host posted without https, so connect with the same address your team signs in to.

What the trigger hands on. Each alert becomes one item for the next step. It carries ID (the event, such as job.stage.complete), build, description, name, action, reference and date_triggered. It does not carry the job or the quote itself. reference holds the ids Simpro sends for that record. The simulate box's own example is a job id. The usual next step is an Intelligence step with Get job or Get quote as a tool, so the AI can pass that id. A Get step on the main path cannot hold the reference in its ID box, as described under Choose an action.

Simulating an alert. Once the agent is saved, Simulate webhook runs it once for the event type you choose and the Reference you paste, for example {"jobID":12871,"companyID":0}. The run does not call Simpro for the alert itself. Write actions the agent takes afterwards do change Simpro, and the run uses credits. Use the id of a real record so that a following Get, called by the AI, finds something. The button stays grey until Reference has something in it.

Weekdays at 16:00

Daily at 16:00 · Mon, Tue, Wed, Thu, Fri

Today's visits

List schedules · today

Write the briefing

GPT-5.6 Terra

Email the planners

1 action enabled

Today's diary emails the planners a summary of today's bookings at 16:00 each weekday. Today's visits uses List schedules with Date Window set to today. The window is the diary date, not the date the job was raised. The step passes on one item per booking, with the staff member, the hours and the time blocks. Write the briefing reads them together and groups them by engineer, and Email the planners sends the result to Sarah Price. The list costs 1 credit however many bookings it returns.

Job finished

Job stage complete

Write the visit note

GPT-5.6 Terra

Job and note

Get job, Create job note

Email the office

1 action enabled

Job completed note writes a note on the job and emails the office when a job reaches the complete stage. Job finished is a Simpro webhook with Job stage complete ticked. Write the visit note has the Simpro step Job and note as a tool, with Get job and Create job note chosen. The AI reads the job id from the alert, fetches the job, and drafts a short note, for example that Dylan Hughes finished the boiler service at Riverside House for Northgate Housing. Pause for approval is on, so the note waits for someone to approve it in the Runs panel. Email the office then sends Sarah Price what was written.

Job finished

Job stage complete

Review the form

GPT-5.6 Terra

Job and form

Get job, Get job form, Create job note

Tell the service desk

1 action enabled

Form check looks at the form on a job an engineer has just completed. The trigger is the same Job stage complete event. Review the form has Get job, Get job form and Create job note as tools. The AI loads the job, reads the rendered form, and asks to put a note on the job when something needs the office, such as a failed test at Harbour View Apartments. Pause for approval is on for the note. Tell the service desk emails Priya Shah what was found. Simpro has no separate event for an accepted quote. For that, tick Quote status changed and have the AI read the quote and carry on only when the status is the one your business uses for accepted.

A dry run is the safe way to try a Simpro step. Open Runs in the toolbar, click Run now and choose Dry run (no actions performed). Read actions such as Get job and List schedules call Simpro for real, so you see real data. Write actions are skipped, and the step's summary says what it would have done, so nothing in Simpro changes. Run for real performs every action, including the writes.

{
  "handles": { "main": 6 },
  "items": {
    "main": [
      {
        "ID": 88421,
        "Type": "job",
        "Reference": "12871",
        "Date": "2026-10-09",
        "TotalHours": 1.5,
        "Staff": { "ID": 214, "Name": "Dylan Hughes" },
        "Blocks": [{ "StartTime": "08:00", "EndTime": "09:30" }]
      }
    ]
  }
}

Open a step in the run to see its output. The panel shows the first 50 items of each output, and later steps still receive all of them. A dry run costs 1 credit for the whole run. A simulated Simpro alert is not a dry run, so test write actions with Run now first. For Run now, dry runs and the Runs panel in full, see Test an agent before it goes live.

A Simpro step costs 1 automation credit each time it runs successfully, whatever the action and however many records it returns. A step that fails costs nothing. When the step is a tool, each call the AI makes costs 1 credit. The Simpro webhook trigger is free, but every run it starts costs 1 credit, like any other run.

Inside a Loop, the step is charged on every pass, so a Loop over 40 jobs that fetches each one costs 40 credits for that step. A single list action is usually cheaper than fetching records one at a time. A quote status alert starts a run for every status change, including the ones a later step ignores, and that run still pays the 1 credit run fee. For allowances, limits and how to see what each run cost, see Automation credits and usage limits.

• 1,000 records by default. List actions fetch up to five pages of 200 records. Page size can be raised to 250. You can raise the page count for a small list, but a wide list should use the Ingest step, described under Large lists.
• Two different dates. List jobs, List quotes and List invoices filter the date the record was raised. List schedules filters the diary date. The date windows you can type include today, this_week, this_month, last_7_days, last_30_days, next_7_days and in_7_days. There is no Tomorrow value. For a single day that is not today, set Date From and Date To to that day, as YYYY-MM-DD.
• Company ID 0. On a single-company build, 0 is the right company. Leave the company field on an action empty to use the company you connected.
• About 8 MB per read. A single read that returns more than about 8 MB fails. Narrow the filters, lower the page size, or use Ingest.
• 60 seconds. Each call to Simpro waits up to 60 seconds. There is no automatic retry if Simpro is busy.
• Per-user integration mode. Simpro only works with the agent's own connection. The Connection section says so, but in per-user mode the step fails with a message that the action is not supported in that mode. The Simpro webhook cannot use per-user credentials either. Keep agents that use Simpro on agent-level mode.
• Number fields. ID boxes only take numbers, so they cannot hold a reference to an earlier step. See Choose an action.
• Deletes. Delete job line item and Unschedule job remove the record in Simpro. Stock lines on a job cannot be deleted. There is no undo in Centrus.
• Published agents only. Alerts only start runs once the agent is published. Simulate webhook and Run now work on drafts.

• Simpro is not connected to this agent. Open the step's Connection section and click Connect. If you have duplicated the agent, the copy needs its own connection.
• Could not verify Simpro credentials. Simpro rejected the access token, or the build address did not answer, when you clicked Connect. Check the key in Simpro and the address your team signs in to, then try again.
• Simpro base URL must use https. The address has to start with https. A host on its own, or an http address, is refused.
• Simpro credentials are incomplete. Please reconnect. The connection was saved without a build address or an access token. Disconnect and connect again with all three values.
• Stored Simpro credentials are invalid. Please reconnect. Centrus cannot read the saved access token. Disconnect, then connect again.
• Simpro HTTP 401, or another Simpro HTTP error, naming the path. Simpro refused the call. 401 means the token is no longer accepted. 404 means the record or the path was not found. Check the ID in the step's fields.
• A required ID is missing. The step ran without the job, quote or other ID the action needs. On a main-flow step, type the number. From an alert, use the step as a tool so the AI can fill it.
• No action selected. The step has no action yet. Choose one under Endpoint tool type.
• An alert never starts the agent. Check that the agent is published, the event type is ticked, the subscription in Simpro uses the same events, the same secret and the callback address, and that the build address on the connection matches the one your team signs in to. Test Subscription in Simpro does not start a run. Unticking an event in Centrus does not stop Simpro until you edit the subscription.
• No other agents with this connection. None of the agents you created has a Simpro connection. Enter the three values by hand.
• A field will not take a reference. It is a number box. Use a fixed number, or let an AI fill it by using the step as a tool.
• A list stops after five pages. That is the default. Raise the page count only for a small list, or use Ingest for more.

The Simpro step offers 147 actions: 88 read from Simpro and 59 change it. Every path below is added to the Base URL you connected, for example https://meridianfm.simprosuite.com. {companyId} is the company on the connection unless the action's company field is filled in. Where an action can call more than one path, the table gives the main one.