BigChange Notes and Worksheets API
Create and manage notes and note types with progress history, and read worksheets, worksheet groups, and worksheet questions used to capture structured job data on the JobWatch mobile app.
OpenAPI Specification
openapi: 3.0.3
info:
title: BigChange DX REST API
version: '1.0'
description: >-
OpenAPI description of the BigChange DX REST API (the modern REST interface to
the BigChange / JobWatch field service and job management platform).
Grounded: the base URL (https://api.bigchange.com), the path templates, the
HTTP methods, the Bearer JWT security scheme, and the required Customer-Id
header are all taken directly from BigChange's own published Swagger/OpenAPI
documents:
- https://api.bigchange.com/swagger/v1/swagger.json (BigChange DX, 108 paths)
- https://api.bigchange.com/swagger/asset-management/v1/swagger.json
- https://api.bigchange.com/swagger/webhooks/v1/swagger.json
Modeled: this document is an API Evangelist-authored, representative SUBSET of
the full published specification. Request and response BODY schemas are
summarized as generic objects here rather than reproduced field-by-field -
consult the upstream swagger.json documents above for the complete,
authoritative request/response models. Every path and method listed below
exists in the published BigChange spec.
contact:
name: BigChange Developer Portal
url: https://developers.bigchange.com/docs/rest/api-reference
servers:
- url: https://api.bigchange.com
description: BigChange DX production API (all products share this host)
security:
- bearer: []
tags:
- name: Jobs
- name: Contacts
- name: Persons
- name: Finance
- name: Stock
- name: Resources
- name: Users
- name: Vehicles
- name: Reference Data
- name: Assets
- name: Webhooks
paths:
/v1/jobs:
get:
tags: [Jobs]
summary: Get a list of jobs
description: >-
Returns a paged list of jobs. Supports filtering by type, contact,
resource, order number, and created-at date range, plus sorting and
pagination (pageNumber, pageSize). Modeled from the published spec.
parameters:
- $ref: '#/components/parameters/CustomerId'
- name: typeId
in: query
schema: { type: integer, format: int64 }
- name: contactId
in: query
schema: { type: integer, format: int64 }
- name: pageNumber
in: query
schema: { type: integer }
- name: pageSize
in: query
schema: { type: integer }
responses:
'200':
description: A paged list of jobs.
content:
application/json:
schema: { $ref: '#/components/schemas/PagedResult' }
post:
tags: [Jobs]
summary: Create a job
parameters:
- $ref: '#/components/parameters/CustomerId'
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/GenericObject' }
responses:
'201':
description: The created job.
content:
application/json:
schema: { $ref: '#/components/schemas/GenericObject' }
/v1/jobs/{jobId}:
get:
tags: [Jobs]
summary: Get a job
parameters:
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/JobId'
responses:
'200':
description: The requested job.
content:
application/json:
schema: { $ref: '#/components/schemas/GenericObject' }
patch:
tags: [Jobs]
summary: Update a job
parameters:
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/JobId'
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/GenericObject' }
responses:
'200':
description: The updated job.
content:
application/json:
schema: { $ref: '#/components/schemas/GenericObject' }
/v1/jobs/{jobId}/schedule:
put:
tags: [Jobs]
summary: Schedule or unschedule a job
description: Assign a job to a resource and time slot, or unschedule it.
parameters:
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/JobId'
requestBody:
content:
application/json:
schema: { $ref: '#/components/schemas/GenericObject' }
responses:
'204': { description: The job schedule was updated. }
/v1/jobs/{jobId}/start:
put:
tags: [Jobs]
summary: Set a job to started
parameters:
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/JobId'
responses:
'204': { description: The job was marked started. }
/v1/jobs/{jobId}/result:
put:
tags: [Jobs]
summary: Set a job's result
parameters:
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/JobId'
requestBody:
content:
application/json:
schema: { $ref: '#/components/schemas/GenericObject' }
responses:
'204': { description: The job result was recorded. }
/v1/jobTypes:
get:
tags: [Reference Data]
summary: Get a list of job types
parameters:
- $ref: '#/components/parameters/CustomerId'
responses:
'200':
description: A list of job types.
content:
application/json:
schema: { $ref: '#/components/schemas/GenericArray' }
/v1/contacts:
get:
tags: [Contacts]
summary: Get a list of contacts
parameters:
- $ref: '#/components/parameters/CustomerId'
responses:
'200':
description: A paged list of contacts.
content:
application/json:
schema: { $ref: '#/components/schemas/PagedResult' }
post:
tags: [Contacts]
summary: Create a contact
parameters:
- $ref: '#/components/parameters/CustomerId'
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/GenericObject' }
responses:
'201':
description: The created contact.
content:
application/json:
schema: { $ref: '#/components/schemas/GenericObject' }
/v1/contacts/{contactId}:
get:
tags: [Contacts]
summary: Get a contact
parameters:
- $ref: '#/components/parameters/CustomerId'
- name: contactId
in: path
required: true
schema: { type: integer, format: int64 }
responses:
'200':
description: The requested contact.
content:
application/json:
schema: { $ref: '#/components/schemas/GenericObject' }
/v1/persons:
get:
tags: [Persons]
summary: Get a list of persons
parameters:
- $ref: '#/components/parameters/CustomerId'
responses:
'200':
description: A paged list of persons.
content:
application/json:
schema: { $ref: '#/components/schemas/PagedResult' }
post:
tags: [Persons]
summary: Create a person
parameters:
- $ref: '#/components/parameters/CustomerId'
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/GenericObject' }
responses:
'201':
description: The created person.
content:
application/json:
schema: { $ref: '#/components/schemas/GenericObject' }
/v1/finance/invoices:
get:
tags: [Finance]
summary: Get a list of invoices
parameters:
- $ref: '#/components/parameters/CustomerId'
responses:
'200':
description: A paged list of invoices.
content:
application/json:
schema: { $ref: '#/components/schemas/PagedResult' }
post:
tags: [Finance]
summary: Create an invoice
parameters:
- $ref: '#/components/parameters/CustomerId'
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/GenericObject' }
responses:
'201':
description: The created invoice.
content:
application/json:
schema: { $ref: '#/components/schemas/GenericObject' }
/v1/finance/quotes:
get:
tags: [Finance]
summary: Get a list of quotes
parameters:
- $ref: '#/components/parameters/CustomerId'
responses:
'200':
description: A paged list of quotes.
content:
application/json:
schema: { $ref: '#/components/schemas/PagedResult' }
post:
tags: [Finance]
summary: Create a quote
parameters:
- $ref: '#/components/parameters/CustomerId'
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/GenericObject' }
responses:
'201':
description: The created quote.
content:
application/json:
schema: { $ref: '#/components/schemas/GenericObject' }
/v1/finance/purchaseOrders:
get:
tags: [Finance]
summary: Get a list of purchase orders
parameters:
- $ref: '#/components/parameters/CustomerId'
responses:
'200':
description: A paged list of purchase orders.
content:
application/json:
schema: { $ref: '#/components/schemas/PagedResult' }
/v1/stockItems:
get:
tags: [Stock]
summary: Get a list of stock items
parameters:
- $ref: '#/components/parameters/CustomerId'
responses:
'200':
description: A paged list of stock items.
content:
application/json:
schema: { $ref: '#/components/schemas/PagedResult' }
post:
tags: [Stock]
summary: Create a stock item
parameters:
- $ref: '#/components/parameters/CustomerId'
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/GenericObject' }
responses:
'201':
description: The created stock item.
content:
application/json:
schema: { $ref: '#/components/schemas/GenericObject' }
/v1/resources:
get:
tags: [Resources]
summary: Get a list of resources
parameters:
- $ref: '#/components/parameters/CustomerId'
responses:
'200':
description: A paged list of resources (the mobile workforce).
content:
application/json:
schema: { $ref: '#/components/schemas/PagedResult' }
/v1/users:
get:
tags: [Users]
summary: Gets a list of users
parameters:
- $ref: '#/components/parameters/CustomerId'
responses:
'200':
description: A paged list of back-office users.
content:
application/json:
schema: { $ref: '#/components/schemas/PagedResult' }
/v1/vehicles:
get:
tags: [Vehicles]
summary: Get a list of vehicles
parameters:
- $ref: '#/components/parameters/CustomerId'
responses:
'200':
description: A paged list of fleet vehicles.
content:
application/json:
schema: { $ref: '#/components/schemas/PagedResult' }
post:
tags: [Vehicles]
summary: Create a vehicle
parameters:
- $ref: '#/components/parameters/CustomerId'
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/GenericObject' }
responses:
'201':
description: The created vehicle.
content:
application/json:
schema: { $ref: '#/components/schemas/GenericObject' }
/asset-management/v1/assets:
get:
tags: [Assets]
summary: Get a list of assets
description: Published in BigChange's separate Asset Management OpenAPI document.
parameters:
- $ref: '#/components/parameters/CustomerId'
responses:
'200':
description: A paged list of customer assets.
content:
application/json:
schema: { $ref: '#/components/schemas/PagedResult' }
post:
tags: [Assets]
summary: Create an asset
parameters:
- $ref: '#/components/parameters/CustomerId'
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/GenericObject' }
responses:
'201':
description: The created asset.
content:
application/json:
schema: { $ref: '#/components/schemas/GenericObject' }
/webhooks/v1/subscriptions:
get:
tags: [Webhooks]
summary: Get webhook subscriptions
description: >-
Lists webhook subscriptions. BigChange webhooks are outbound HTTP
callbacks (server-to-consumer POST); there is no WebSocket transport.
parameters:
- $ref: '#/components/parameters/CustomerId'
responses:
'200':
description: A list of webhook subscriptions.
content:
application/json:
schema: { $ref: '#/components/schemas/GenericArray' }
/webhooks/v1/failed:
get:
tags: [Webhooks]
summary: Get failed webhook deliveries
parameters:
- $ref: '#/components/parameters/CustomerId'
responses:
'200':
description: A list of failed webhook deliveries.
content:
application/json:
schema: { $ref: '#/components/schemas/GenericArray' }
components:
securitySchemes:
bearer:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
Bearer JWT access token. Obtain an access token from BigChange's
authentication proxy using an API key issued in the developer portal
(Account > Manage API Keys / Integrations), then send it as
`Authorization: Bearer <access_token>`. Confirmed from the published
BigChange swagger security scheme ("Enter the access token only").
parameters:
CustomerId:
name: Customer-Id
in: header
required: true
description: >-
The customer (BigChange account) identifier. Required on every operation
in the published spec.
schema:
type: integer
format: int64
JobId:
name: jobId
in: path
required: true
schema:
type: integer
format: int64
schemas:
GenericObject:
type: object
description: >-
Placeholder object. See BigChange's published swagger.json for the full,
authoritative field-level schema of this resource.
additionalProperties: true
GenericArray:
type: array
items:
$ref: '#/components/schemas/GenericObject'
PagedResult:
type: object
description: Standard paged list envelope (modeled).
properties:
pageNumber:
type: integer
pageSize:
type: integer
totalCount:
type: integer
items:
$ref: '#/components/schemas/GenericArray'