BigChange API

Unified read/write proxy to your BigChange field service data. Covers jobs, contacts, invoices, quotes, sales opportunities, purchase orders, resources, vehicles, stock, worksheets, and reference data. Tenant scope is resolved from your API key. No company_id is required on these requests. We’ve added some usefuil features such as pre handled authentication, compactions and data output optimisation.

Base URL

https://api.vh3connect.io/api:YdihQNr3

Authentication

Pass your VH3 API key in the X-API-Key header on every request. This is the same key issued for the VH3 AI Intelligence layer; only the transport differs.

curl -X POST "https://api.vh3connect.io/api:YdihQNr3/jobs/list" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "pageNumber": 1,
    "pageSize": 20
  }'

Header	Required	Description
`X-API-Key`	Yes	Your tenant API key
`Content-Type`	Yes (POST)	`application/json`

Missing or invalid keys return 401 Unauthorised. See Authentication for the full two-API comparison.

Common response codes

Code	Meaning
`200`	Success
`201`	Created
`400`	Bad request, invalid or missing parameters
`401`	Unauthorised, missing or invalid API key
`403`	Forbidden, insufficient permissions
`404`	Not found
`422`	Validation error
`429`	Rate limited
`500`	Internal server error

Pagination

List endpoints accept pageNumber (1-based) and pageSize. Finance list responses also include pageItemCount (items in the current page, use to detect the last page).

Param	Default	Max
`pageSize`	100	1000

Sorting

Most list endpoints accept:

Param	Values
`sortBy`	Field name (varies by endpoint, e.g. `name`, `createdAt`)
`direction`	`ascending` or `descending`

Date ranges

BigChange enforces a maximum 12-month window on date-range filters. If createdAtTo minus createdAtFrom (or equivalent pair) exceeds twelve calendar months, the API returns a validation error.

Rule	Detail
Format	ISO 8601 UTC, e.g. `2026-01-01T00:00:00Z`
Typical pair	`createdAtFrom` + `createdAtTo`, inclusive bounds on record creation time
Max span	12 months, always; not configurable per tenant
Sort tie-in	Finance lists (`invoices`, `quotes`) usually sort by `createdAt` when filtering by date

Where date ranges apply:

Endpoint	Date filter fields	Notes
`POST /jobs/list`	`createdAtFrom`, `createdAtTo`	Required for job list queries
`POST /contacts/list`	`createdAtFrom`	Optional lower bound on contact creation
`POST /invoices/list`	`createdAtFrom`, `createdAtTo`	Optional; combine with `contactId`, `jobId`, `reference`, etc.
`POST /quotes/list`	`createdAtFrom`, `createdAtTo`	Optional; same pattern as invoices
`POST /purchase_orders/list`	`createdAtFrom`, `createdAtTo`	At least one non-date filter still required
`POST /sales_opportunities/list`	`createdAtFrom`, `createdAtTo`, `dueDateFrom`, `dueDateTo`	At least one filter required; due-date pair also subject to 12-month max

Status timestamps on write endpoints (paidAt, sentAt, plannedStartAt, note dueAt) are single instants, not ranges, they are not subject to the 12-month window rule.

Custom fields

Pass custom fields as an array when creating or updating records:

{
  "customFields": [
    { "definitionId": 123, "value": "High priority" },
    { "definitionId": 456, "value": null }
  ]
}

Set value to null to clear an existing value.

Common enum values

Domain	Field	Values
All lists	`direction`	`ascending`, `descending`
Contacts	`status` (on stop)	`contactOnStop`, `creditLimitOnStop`
Contacts	`appliesTo` (stop/unstop)	`contactOnly`, `contactAndChildren`
Jobs	`status` (result)	`completedOk`, `completedWithIssues`
Notes	`status`	`open`, `completed`, `cancelled`
Notes	`entityType`	`contact`, `job`, `resource`, `stockItem`, `vehicle`, `salesOpportunity`, `contract`
Persons	`consent.status`	`awaiting`, `refused`, `granted`
Persons	`consent.medium`	`email`, `click`, `telephone`

Endpoint-specific enums are listed on each page where they apply.

Path format

Request URLs are {baseUrl}{path} with one slash between base and path, e.g. https://api.vh3connect.io/api:YdihQNr3 + /jobs/list. Some BigChange routes include repeated segments by design (e.g. /stock/stock/item_get); that is not a double-slash error.

Endpoint groups

Group	Description
Contacts	Contacts, groups, site access hours, on-stop
Jobs	Jobs, constraints, stock, groups, types
Invoices	Invoices and line items
Quotes	Quotes and line items
Sales opportunities	Opportunities, stages, probabilities, line items
Purchase orders	Purchase orders, series, line items
Notes	Notes and note types
Persons	Site contacts and consent
Resources	Engineers/technicians and resource groups
Vehicles	Fleet vehicles
Stock	Stock details, items, movements, suppliers, categories
Worksheets	Worksheet definitions, questions, answers
Reference data	Department and nominal codes

​BigChange API

​Base URL

​Authentication

​Common response codes

​Pagination

​Sorting

​Date ranges

​Custom fields

​Common enum values

​Path format

​Endpoint groups