BigChange

BigChange Jobs API

Create, retrieve, update, schedule, start, cancel, and report on jobs and job groups. Manage job line items, job stock, worksheets and answers, constraints, flags, and status history for field-service work orders.

GitHub OpenAPI

Documentation

📖
Documentation
https://developers.bigchange.com/docs/rest/api-reference
📖
APIReference
https://developers.bigchange.com/docs/category/rest/api-reference/v-2-0-0/jobs

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/bigchange/refs/heads/main/openapi/bigchange-openapi.yml

Other Resources

🔗
PostmanCollection
https://raw.githubusercontent.com/api-evangelist/bigchange/refs/heads/main/collections/bigchange.postman_collection.json
🔗
OpenCollection
https://raw.githubusercontent.com/api-evangelist/bigchange/refs/heads/main/collections/bigchange.opencollection.json
🔗
APIsJSON
https://raw.githubusercontent.com/api-evangelist/bigchange/refs/heads/main/apis.yml

OpenAPI Specification

bigchange-openapi.yml Raw ↑ 
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'