BigChange REST in Agent Builder

The BigChange REST step lets an agent read and change records in your BigChange account as part of a run. It can fetch a job, list tomorrow's work, add a note, put a flag on a job or mark an invoice as paid. Each step does one thing, picked from 202 actions, and hands what BigChange sends back to the next step. The same connection also drives the BigChange webhook trigger, which starts an agent as soon as something you care about changes in BigChange.

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

Agents

Build modular AI workflows with reusable nodes

Job completed summary

1,240 / 10,000 creditsValidateResetRunsSettingsUpdate & Publish

Job finished

Job status changed

Fetch the job

Get job · {{ trigger.json.data.entityId }}

2

Write the visit summary

GPT-5.6 Terra

Email the customer

1 action enabled

AI builderMap

1. 1BigChange REST in the Integration group of the Nodes panel.
2. 2The step on the canvas. Its summary shows the action, Get job, and the job it fetches.
3. 3Connection: the BigChange account this agent uses, shown by its customer ID.
4. 4Endpoint: the action the step performs, chosen from the full list.
5. 5The action's fields. Here the job ID comes from the alert that started the run.

Centrus works alongside BigChange. Your jobs, contacts and finance records stay in BigChange, and the agent reads and updates them there through BigChange's REST API. For attachments, PDF files and the other things the REST API does not cover, use the BigChange Web Services step instead, described in BigChange Web Services in Agent Builder. To ask about BigChange records in a conversation rather than in an agent, see BigChange REST in chat.

Open the agent in Agent Builder and find BigChange REST in the Integration group of the Nodes panel. 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 status changed

BigChange REST

No endpoint selected

2

1. 1BigChange REST 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 BigChange step or change its settings.

09:41

Centrus

Agents

Build modular AI workflows with reusable nodes

Chase overdue invoices

Save and Publish

Job finished

Job status changed

Fetch the job

Get job · {{ trigger.json.data.entityId }}

Write the visit summary

GPT-5.6 Terra

Email the customer

1 action enabled

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

You need three values from BigChange: your Customer ID, a Client ID and a Client Secret. The connect window says where to find them: in BigChange under Admin, then API Web Services. If you cannot see that page, ask your BigChange administrator for the values.

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 BigChange REST step. In the Details panel, open Connection and click Connect.
3. 3In the Connect BigChange REST window, enter the Customer ID, Client ID and Client Secret, then click Connect.
4. 4Connection now reads Connected, followed by your customer ID.

Centrus does not check the values when you click Connect. A mistyped Client ID or Client Secret only shows up the first time the step runs, as a failed step that starts BigChange REST token request failed (HTTP 401). Try the agent with a dry run straight after connecting, as described under Test before it goes live.

Reusing a connection. If you have already connected BigChange 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 BigChange 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 BigChange 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 BigChange 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 BigChange steps and trigger stop working until someone connects it again, and other agents keep their own connections.

Select the step and open Endpoint in the Details panel. Endpoint tool type holds all 202 actions in one list that starts with List jobs and the job group 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. Let AI populate endpoint fields hides the fields so that an AI can fill them, but on a step in the agent's main flow nothing fills them in when the step runs. To have an AI choose the values, attach the step to an AI step as a tool instead, as described below.

Each action then shows its own fields in a box below. Get job has a box called Job lookup input with one field, Job ID or reference, which takes either a BigChange job ID such as 190123604 or a job reference. Larger actions have more fields, and fields marked (optional) can be left empty.

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 the field you are filling in. In the overview agent, Job ID or reference holds {{ trigger.json.data.entityId }}, which is the ID of the job the BigChange alert was about.

Many ID fields only accept numbers, such as Entity ID and Note type ID on Create note, so a reference cannot be pasted into them. Fill those with a fixed number, or attach the step to an AI step as a tool so that the AI supplies the ID when it calls the action.

What the step passes on. When the step runs, it passes on what BigChange returned as items for the next step. Get job passes on one item, the job. A list action such as List jobs passes on one item per record, so six jobs become six items. Later steps reach their fields through Step data references, and an AI step reads all of the items together. To create or change one record for each item, put the step inside a Loop, described in Conditions, loops and approvals.

As a tool for an AI step. Connect a BigChange REST 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, then shows the first one and a count, such as Get job worksheets +3.

Job completed with issues

Job status changed

Review the worksheet

GPT-5.6 Terra

Worksheets and flags

Get job worksheets, List flags, Create job flag

1

1. 1The BigChange REST step attached to the Intelligence step as a tool.
2. 2Actions: the BigChange actions the AI may call.
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 BigChange REST 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 BigChange, put an Approval step in front of it.

The BigChange webhook trigger, in the Trigger group of the Nodes panel, starts the agent when BigChange reports a change you have ticked, such as a job changing status. It uses the agent's BigChange connection, so if a BigChange REST 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 BigChange.

Job finished

Job status changed

Fetch the job

Get job · {{ trigger.json.data.entityId }}

Write the visit summary

GPT-5.6 Terra

Email the customer

1 action enabled

1. 1Connection, shared with the agent's BigChange REST steps.
2. 2Event types: the events that start a run. Only Job status changed is ticked.
3. 3Set this up in BigChange: the steps to follow in BigChange and the address to paste there.
4. 4Simulate webhook: runs the agent once with a sample alert.

Every event it can listen for. There are 60 event types in 14 groups. Tick only the ones the agent needs, because each alert that matches starts a run and each run uses credits.

Some events arrive far more often than others. Tracking driving fires every mile, every minute or whenever a vehicle turns by more than 65 degrees, and Tracking heartbeat every six hours while a vehicle is parked with its ignition off. Tracking idling started fires once a vehicle has idled for more than two minutes. For Job status changed, BigChange only sends the statuses you pick in its portal, so pick at least one there.

Who sets it up, and where. The Centrus side is done by anyone who can edit the agent. The BigChange side needs someone who can manage API keys at developers.bigchange.com, and Set this up in BigChange lists their steps:

1. 1Open API Key Management at developers.bigchange.com and find the API key this agent uses, usually named Centrus AI. Do not create a second key.
2. 2On that key, open the menu, choose Manage webhooks, then Add Webhook.
3. 3Paste the endpoint address shown under Set this up in BigChange. It is the same for every organisation, and Centrus routes each alert by its customer ID.
4. 4Tick the same event types as the trigger. Do not tick attachment events, and do not tick Tracking driving unless the agent needs live vehicle updates. If you tick Job status changed, set the status filter.
5. 5Save, then allow up to 10 minutes before the first alerts arrive.

What the trigger hands on. Each alert becomes one item for the next step, with type, the event such as job.modified.status, customerId, and a data object. data.entityId is the ID of the record that changed, so the usual next step is the matching Get action, such as Get job with Job ID or reference set to {{ trigger.json.data.entityId }}. For Job status changed, data.previousStatus and data.newStatus hold the old and new status. Worksheet answers modified pairs with List worksheet answers, using data.entityType and data.entityId. Telematics alerts already hold the full details, and their entityId is a vehicle or asset reference rather than a BigChange vehicle ID, so do not follow them with Get vehicle.

Simulating an alert. Once the agent is saved, Simulate webhook runs it once with a sample alert for the event type and entity ID you enter. Use the ID of a real record so that the Get step after it finds something. A simulated alert is a real run rather than a dry run: write actions change BigChange, and the run uses credits. The sample only holds the entity ID, so steps that read data.newStatus or data.previousStatus find them empty.

Job finished

Job status changed

Fetch the job

Get job · {{ trigger.json.data.entityId }}

Write the visit summary

GPT-5.6 Terra

Email the customer

1 action enabled

Job completed summary emails the customer when a visit is finished. Job finished is a BigChange webhook with Job status changed ticked, and the status filter in BigChange set to the completed statuses. Fetch the job uses Get job with {{ trigger.json.data.entityId }}, so the agent has the whole job, including the contact, the site and the engineer. Write the visit summary turns the job into a short, plain note for the customer, and Email the customer sends it from the agent's Outlook connection. Each finished job costs five credits or a little more.

Weekdays at 16:00

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

Tomorrow's jobs

List jobs

Write the briefing

GPT-5.6 Terra

Email the planners

1 action enabled

Tomorrow's jobs briefing sends the planners a summary of the next day's work at 16:00 each weekday. Tomorrow's jobs uses List jobs with Date window set to Tomorrow and Status set to scheduled, and passes on one item per job. Write the briefing reads them all together and groups them by engineer, flagging jobs with no engineer or no planned start time, and Email the planners sends the result. The list costs 1 credit however many jobs it returns.

Job completed with issues

Job status changed

Review the worksheet

GPT-5.6 Terra

Worksheets and flags

Get job worksheets, List flags, Create job flag

Tell the service desk

1 action enabled

Worksheet check looks at jobs an engineer closes with issues. The trigger listens for Job status changed, with BigChange's status filter set to the completed with issues status. Review the worksheet has the BigChange REST step Worksheets and flags as a tool, with Get job worksheets, List flags and Create job flag chosen. The AI reads the job's worksheet answers, looks up the right flag and asks to put it on the job. Pause for approval is on, so each flag waits for someone to approve it in the Runs panel. Tell the service desk then emails what was found.

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

{
  "handles": { "main": 6 },
  "items": {
    "main": [
      {
        "id": 190123604,
        "reference": "J-10482",
        "status": "scheduled",
        "type": "Boiler service",
        "contactId": 34346334,
        "contactName": "Northgate Housing",
        "contactAddress": "Riverside House, 14 Quay Street, Bristol BS1 4DJ",
        "resourceName": "Dylan Hughes",
        "plannedStartAt": "2026-10-10T08:00:00Z",
        "plannedEndAt": "2026-10-10T09:30:00Z"
      },
      {
        "id": 190123618,
        "reference": "J-10483",

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 BigChange 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 BigChange REST 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 BigChange 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. For allowances, limits and how to see what each run cost, see Automation credits and usage limits.

• 1,000 records per list. List actions fetch up to five pages of 200 records. To work through more, up to 50,000, use the Ingest step, described under Large lists.
• List jobs defaults to today. With no dates, no date window and no status, List jobs returns today's jobs, using UK time. Status shows BigChange's own values, such as scheduled and completedOk.
• About 8 MB per read. A single read that returns more than about 8 MB fails. Narrow the filters or use Ingest.
• Busy periods. If BigChange says it is receiving too many requests, Centrus waits and tries again up to three times, after half a second, one and a half seconds and three seconds, before the step fails.
• Per-user integration mode. BigChange REST only works with the agent's own connection. The Connection section says the step uses it even in per-user mode, but in per-user mode BigChange REST steps fail with a message saying the action is not supported in that mode. Keep agents that use BigChange on agent-level mode.
• Number fields. Many ID fields only take numbers, so they cannot hold a reference to an earlier step. See Choose an action.
• Published agents only. Alerts only start runs once the agent is published. Simulate webhook and Run now work on drafts.

• BigChange 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.
• BigChange REST token request failed (HTTP 401). BigChange rejected the Client ID or Client Secret. Check them in BigChange under Admin, then API Web Services, then disconnect and connect again with the right values.
• Customer ID is required. The connection was saved without a customer ID. Disconnect and connect again with all three values.
• Stored BigChange credentials are invalid. Please reconnect. Centrus cannot read the saved credentials. Disconnect, then connect again.
• BigChange REST API call failed (HTTP 404). The record does not exist or the ID is wrong. Check the reference in the step's fields, and remember that a telematics alert's entity ID is not a vehicle ID.
• 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 on the trigger, the webhook has been added in BigChange on the same API key with the same event types, and, for Job status changed, that a status filter is set in BigChange. Allow 10 minutes after saving the webhook.
• No other agents with this connection. None of the agents you created has a BigChange connection. Enter the three values by hand.
• A field will not take a reference. It is a number field. Use a fixed number, choose an action that takes the ID as text, or let an AI fill it by using the step as a tool.
• A list stops at 1,000 records. That is the limit for one list action. Use Ingest for more.

The BigChange REST step offers 202 actions: 105 read from BigChange and 97 change it. Every endpoint below is on https://api.bigchange.com. Where an action is listed with the same endpoint as another, it calls that endpoint with different filters.