BigChange Web Services in Agent Builder

The BigChange Web Services step lets an agent fetch files and the older BigChange records that the REST step cannot reach. It can download a job card PDF, an invoice PDF or a quote PDF, list and download attachments, upload a file, read a job signature, and work with contracts, journeys, absences, expenses and routes. Each step does one thing, picked from 70 actions, and hands what BigChange sends back to the next step. A download hands on the file, so a later Outlook step can attach it to an email.

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

Agents

Build modular AI workflows with reusable nodes

Job card to the customer

1,240 / 10,000 creditsValidateResetRunsSettingsUpdate & Publish

Job finished

Job status changed

Read the job

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

Download the job card

Download job card PDF

2

Email the customer

1 action enabled

AI builderMap

1. 1BigChange Web Services in the Integration group of the Nodes panel.
2. 2The step on the canvas. Its summary shows the action, Download job card PDF.
3. 3Connection: the Web Services account this agent uses, shown by its web user email.
4. 4Endpoint: the action the step performs, chosen from the full list.
5. 5The action's fields. Here the job reference comes from the BigChange REST step before it.

Centrus works alongside BigChange. Jobs, contacts, quotes and invoices stay in BigChange. Use BigChange REST for those records, and use this step when you need the file or the record the REST API does not return. Typical work for this step is attachments, branded PDFs (job cards, invoices, quotes and sales opportunities), job signatures, financial document lines, contracts, live positions, journeys and odometers, resource absences, vehicle defects, job stops, the scheduling assistant, recurrence, expenses, custom fields, payments, working hours, skills, the activity log, JobWatch messages, stock make and model, and routes. For the REST step itself, see BigChange REST in Agent Builder.

Open the agent in Agent Builder and find BigChange Web Services in the Integration group of the Nodes panel, directly under BigChange REST. 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.

Read the job

Get job

BigChange Web Services

No endpoint selected

2

1. 1BigChange Web Services 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 Web Services 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

Read the job

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

Download the job card

Download job card PDF

Email the customer

1 action enabled

The Web Services connection belongs to this agent alone. It is separate from a BigChange REST connection on the same agent, and separate from any BigChange connection in chat, so connecting one does not connect the other. One Web Services connection covers every BigChange Web Services step in the agent, so you only connect once per agent. It does not cover the BigChange webhook trigger. That trigger uses the agent's BigChange REST connection.

You need three values: a Company key, a Web user email and a Web user password. The connect window says the company key is the Web Services header key, not the Core REST developer-portal customer ID that BigChange REST asks for. The web user needs permission in BigChange for attachments, PDFs and financial documents. If you do not have these values, ask your BigChange administrator.

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 Web Services step. In the Details panel, open Connection and click Connect.
3. 3In the Connect BigChange Web Services window, enter the Company key, Web user email and Web user password, then click Connect.
4. 4Centrus asks BigChange to list web users with those values. If BigChange accepts them, Connection reads Connected, followed by the web user email.

Centrus checks the three values when you click Connect. If a field is empty, or BigChange rejects the web user, nothing is saved and the window stays open with the error. A wrong password often comes back as BigChange Web Services HTTP 401. Try a dry run after a successful connect, as described under Test before it goes live.

Reusing a connection. If you have already connected Web Services 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 Web Services 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 Web Services 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 Web Services 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 Web Services steps stop working until someone connects it again. Other agents keep their own connections, and a BigChange REST connection on this agent is left as it is.

Select the step and open Endpoint in the Details panel. The section's own line reads Choose the Web Services action this node should call (attachments and branded PDFs). Endpoint tool type holds all 70 actions in one list that starts with List attachments. 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 titled with the action's name. The label on a field is the first sentence of its description, and a required field has an asterisk. Download job card PDF has Numeric job ID, Job reference and Optional job card ID (default 0). You need the job ID or the job reference. The job card ID can stay empty: BigChange then uses 0, which is the default card.

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. In the overview agent, Job reference holds the reference from Read the job, written {{ steps.integration-bigchange_rest-1791540900000-2.json.reference }}. Numeric job ID is a number field, so a reference pasted into it is turned into a number and lost. Use Job reference for a value from an earlier step, or attach the step to an AI step as a tool so the AI can supply the numeric ID.

Download attachment is the pair to List attachments. List attachments needs an entity type, such as Job, Invoice or WorksheetAnswer, plus a numeric ID or a reference, and it passes on one item per attachment. Download attachment then takes Attachment ID to download, which is text, so inside a Loop you can set it to {{ item.json.attachmentId }}. Leave Optional override file name empty to keep BigChange's own file name.

What the step passes on. A single download passes on one item, including the file name, the type and the size, and the file itself for the next step to attach or read. A list action passes on one item per record, so six attachments become six items. Later steps reach their fields through Step data references, and an AI step reads all of the items together. To download one file for each item, put Download attachment or Download invoice PDF inside a Loop, described in Conditions, loops and approvals.

As a tool for an AI step. Connect a BigChange Web Services 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 if there are more.

Job completed

Job status changed

Review the photos

GPT-5.6 Terra

Job photos

List attachments, Download attachment, Get job signature

1

1. 1The BigChange Web Services step attached to the Intelligence step as a tool.
2. 2Actions: the Web Services 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 Web Services 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. Do not give an Intelligence step the long lists (List contracts, List journeys, List resource absences, List expenses, List payments or List activity log). Centrus warns you, because the whole list would be loaded into the AI. Use the Ingest step for those, as described under Limits and good to know.

BigChange Web Services has no trigger of its own. Alerts come from the BigChange webhook trigger, which belongs to BigChange REST. Put that trigger at the start of the agent, then a BigChange REST Get step if you need the record, then the Web Services step that fetches the file. The trigger uses the agent's BigChange REST connection, so an agent that emails a job card needs both connections. Setting up the webhook, the full list of events, and what each event contains are covered in BigChange REST in Agent Builder. The general picture for every system is in Start an agent from a system alert.

Job finished

Job status changed

Download the job card

Download job card PDF

1. 1Connection on the BigChange webhook. This is the BigChange REST connection, not Web Services. Web Services has no trigger of its own.
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. Write actions in the steps after it still change BigChange.

What the Web Services step should read from the alert. The trigger hands on data.entityId, the ID of the record that changed. That ID is a number. Numeric job ID on Download job card PDF will not keep a pasted reference, so the usual pattern is a BigChange REST Get job in between, with Job ID or reference set to {{ trigger.json.data.entityId }}, and then Job reference on the Web Services step set to the reference that Get job returned. The same pattern works for a signature (Get job signature also has a text Job reference) and for photos: List attachments with the type Job, then Download attachment inside a Loop.

For an invoice or a quote, follow the matching REST Get and put the reference in Invoice reference or Quote / document reference, which are text fields. Job status changed also carries the old and new status, but a simulated alert only holds the entity ID, so those are empty on a simulation. A simulated alert is a real run: a Web Services write, such as Upload attachment or Email job confirmation, does change BigChange, and the run uses credits. Alerts only start runs once the agent is published. Simulate webhook and Run now work on drafts.

Job finished

Job status changed

Read the job

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

Download the job card

Download job card PDF

Email the customer

1 action enabled

Job card to the customer emails the branded job card 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. Read the job uses Get job with {{ trigger.json.data.entityId }}, so the agent has the contact, the site and the job reference, for example J-10482 for a boiler service at Riverside House for Northgate Housing. Download the job card uses Download job card PDF with that reference in Job reference. Email the customer sends the PDF from the agent's Outlook connection. Each finished job costs four credits.

Monday at 08:00

Weekly · Mon at 08:00

This week's invoices

List invoices

Each invoice

Batch size 1

Download the PDFs

Download invoice PDF

Email accounts

1 action enabled

Weekly invoice pack sends the accounts team the week's invoice PDFs at 08:00 every Monday. This week's invoices uses BigChange REST List invoices for the date window. Download the PDFs sits inside a Loop so it runs once per invoice, with Invoice reference set to {{ item.json.reference }}. Invoice reference is text, so the reference survives. Numeric invoice ID would not. Email accounts attaches the PDFs and sends them. The list costs 1 credit. Each PDF costs another credit, so twelve invoices cost twelve credits for that step.

Job completed

Job status changed

List the photos

List attachments

Each photo

Batch size 1

Download the photo

Download attachment

Compare the photos

Worksheet photos

Worksheet photo check reads the photos an engineer attached when they closed a job. The trigger listens for Job status changed, with the status filter set to the completed status. List the photos uses List attachments with the type Job and the job reference from a BigChange REST Get job step in front of it. Download the photo sits inside a Loop, with Attachment ID to download set to {{ item.json.attachmentId }}. Compare the photos is a File Parser step, which reads the file and pulls out what you name, such as a meter reading or a damage note. File Parser is covered under Steps an agent can use.

A dry run is the safe way to try a Web Services step. Open Runs in the toolbar, click Run now and choose Dry run (no actions performed). Read actions such as Download job card PDF, List attachments and List journeys call BigChange for real, so you see real files and real rows. Write actions, such as Upload attachment, Save expense and Email job confirmation, 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": 1 },
  "items": {
    "main": [
      {
        "fileName": "job-card-J-10482.pdf",
        "name": "job-card-J-10482.pdf",
        "mimeType": "application/pdf",
        "size": 186432,
        "jobId": 190123604,
        "jobRef": "J-10482"
      }
    ]
  }
}

Open a step in the run to see its output. A download's summary is Downloaded followed by the file name, or Downloaded and a count when a Loop fetched several. 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 Web Services step costs 1 automation credit each time it runs successfully, whatever the action and however large the file. A step that fails costs nothing. When the step is a tool, each call the AI makes costs 1 credit. Web Services has no trigger. A run started by the BigChange webhook still costs 1 credit for the run, like any other run, and the webhook trigger itself is free.

Inside a Loop, the step is charged on every pass, so a Loop over 40 invoices that downloads each PDF costs 40 credits for that step. A single list action is usually cheaper than fetching records one at a time, but a PDF still has to be downloaded one at a time. For allowances, limits and how to see what each run cost, see Automation credits and usage limits.

• Dates are year first. List journeys requires a start and an end, written as 2026-10-09. The same shape is used on List contracts, List resource absences, List expenses and List payments. Get job scheduling assistant will not look further than 7 days ahead.
• Wide lists use Ingest. List contracts, List journeys, List resource absences, List expenses, List payments and List activity log can be too large for one step. Use the Ingest step, described under Large lists, and do not attach those six actions to an Intelligence step.
• 20 MB per file. A download larger than 20 MB fails. The message states the limit in bytes (20,971,520) and the size BigChange returned.
• Timeouts. A call is given 120 seconds. An upload is given 180 seconds. After that the step fails.
• Uploads. Upload attachment can add a file to a job, an expense item, a contact note, a contact or a sales opportunity. It cannot attach a file to an invoice or a quote. Prefer a file already downloaded by an earlier step. Email job confirmation sends BigChange's own confirmation email, not an Outlook message, and the job must already be scheduled, accepted, on the way, or sent.
• Per-user integration mode. BigChange Web Services only works with the agent's own connection. In per-user mode the Connection section says the step still uses that connection, because Web Services has no per-user credentials. Keep agents that use it on the agent's own connection.
• Number fields. ID fields such as Numeric job ID and Numeric invoice ID only take numbers, so they cannot hold a reference to an earlier step. Text fields such as Job reference, Invoice reference and Attachment ID to download can. See Choose an action.
• Two connections. A job card agent needs BigChange REST for the webhook and for Get job, and Web Services for the PDF. Connecting one does not connect the other.

• BigChange Web Services 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. A BigChange REST connection on the same agent does not count.
• BigChange Web Services HTTP 401. BigChange rejected the web user email or password. Check them with your BigChange administrator, then disconnect and connect again. This can also appear when you click Connect, in which case nothing was saved.
• Could not verify Web Services credentials. BigChange did not accept the three values. Check the company key is the Web Services header key, not the REST customer ID, and that the web user can open attachments and financial documents.
• A field was left empty. Connect refuses to save until Company key, Web user email and Web user password are all filled in.
• Stored BigChange Web Services credentials are invalid. Please reconnect. Centrus cannot read the saved password. Disconnect, then connect again.
• BigChange Web Services credentials are incomplete. Please reconnect. The saved connection is missing one of the three values. Disconnect and connect again with all three.
• The PDF step finds nothing. Download job card PDF needs Numeric job ID or Job reference. Download invoice PDF needs Numeric invoice ID or Invoice reference. A number field will not keep a reference you pasted in. Use the text reference field, or a fixed number.
• No action selected. The step has no action yet. Choose one under Endpoint tool type.
• An alert never starts the agent. Web Services does not listen for alerts. Check the BigChange webhook on the same agent: the agent must be published, the event type ticked, and the webhook added in BigChange. See BigChange REST in Agent Builder.
• No other agents with this connection. None of the agents you created has a Web Services connection. Enter the three values by hand.
• A file step fails on size. The file is over 20 MB. Download it another way, or narrow what you asked for.
• A long list warns you. List contracts, List journeys, List resource absences, List expenses, List payments and List activity log should not be tools on an Intelligence step. Use Ingest.

The BigChange Web Services step offers 70 actions: 40 read from BigChange and 30 change it. Every call goes to https://webservice.bigchange.com/v01/services.ashx, with action naming the operation. JSON calls also send format=json. Upload attachment and Create account receipt use POST. Every other action uses GET. Where an action calls more than one operation, the table gives the main one.