Jobs

The Jobs endpoints provide access to your enriched job records, including AI-extracted fault types, outcomes, timings, and relationships to engineers, sites, and customers.

GET /jobs/feed

Returns a paginated feed of enriched jobs for your company. Supports filtering by entity, status, punctuality, date range, and sort field. All filters are optional and composable as AND conditions. Query parameters:

Param	Type	Required	Default	Description
`company_id`	string	Yes	-	Your tenant identifier
`api_key`	string	Yes	-	Your tenant API key
`page_size`	integer	No	20	Results per page (max 200)
`page_number`	integer	No	1	Page number (1-indexed)
`contact_id`	string	No	-	Filter by customer contact ID
`resource_id`	string	No	-	Filter by engineer/resource ID
`type_id`	string	No	-	Filter by job type ID
`category_id`	string	No	-	Filter by job category ID
`status`	string	No	-	Filter by status, single value or comma-separated (e.g. `completedOk,completedWithIssues`)
`result`	string	No	-	Filter by job result
`finished_early`	boolean	No	-	`true` = finished on/before planned end
`finished_late`	boolean	No	-	`true` = finished after planned end (preferred for late-finish lists; alias of `finished_early=false`)
`started_early`	boolean	No	-	`true` = started on/before planned start
`started_late`	boolean	No	-	`true` = started after planned start (preferred for late-start lists; alias of `started_early=false`)
`date_from`	string	No	-	ISO date/datetime, include jobs on or after (inclusive)
`date_to`	string	No	-	ISO date/datetime, exclude jobs on or after (exclusive)
`date_field`	string	No	`createdAt`	Which timestamp `date_from`/`date_to` apply to: `createdAt`, `plannedStartAt`, `plannedEndAt`, `actualStartAt`, `actualEndAt`
`sort_by`	string	No	`createdAt`	Sort field: `createdAt`, `endDeltaMins`, `startDeltaMins`, `actualEndAt`, `actualStartAt`. Null sort keys are pushed last
`direction`	string	No	`desc`	Sort direction on `sort_by`, `asc` or `desc`
`compact`	boolean	No	false	Strip nulls/empties to return a compact payload for AI agents

Punctuality filters combine with AND. Prefer finished_late=true / started_late=true for late questions. Job payloads still expose finishedEarly / startedEarly (and startDeltaMins / endDeltaMins where negative = early, positive = late). Do not pass conflicting early/late pairs for the same axis.

Example: completed jobs from May 2026

curl -G "https://api.vh3connect.io/api:kP8T1CK7/jobs/feed" \
  --data-urlencode "company_id=your-company-id" \
  --data-urlencode "api_key=your-api-key" \
  --data-urlencode "page_size=20" \
  --data-urlencode "status=completedOk,completedWithIssues" \
  --data-urlencode "date_from=2026-05-01" \
  --data-urlencode "date_to=2026-06-01" \
  --data-urlencode "date_field=actualEndAt"

Example: worst late finishes in a date window

curl -G "https://api.vh3connect.io/api:kP8T1CK7/jobs/feed" \
  --data-urlencode "company_id=your-company-id" \
  --data-urlencode "api_key=your-api-key" \
  --data-urlencode "finished_late=true" \
  --data-urlencode "date_from=2026-05-01" \
  --data-urlencode "date_to=2026-06-01" \
  --data-urlencode "date_field=actualEndAt" \
  --data-urlencode "sort_by=endDeltaMins" \
  --data-urlencode "direction=desc" \
  --data-urlencode "page_size=5"

GET /jobs/feed/account

Returns a paginated feed of jobs scoped to a parent account and all its child contacts. Pass any contact ID, parent or child, and the endpoint resolves the full hierarchy automatically.

This endpoint resolves the parent/child account hierarchy. If you pass a child contact ID, the parent is found and all sibling contacts are included. If you pass a parent, all children are included. Standalone contacts return only their own jobs.

How hierarchy resolution works:

You pass	What happens
A parent contact ID	Returns jobs for the parent + all child contacts
A child contact ID	Finds the parent, returns jobs for parent + all siblings
A standalone contact ID	Returns jobs for that contact only

Query parameters:

Param	Type	Required	Default	Description
`company_id`	string	Yes	-	Your tenant identifier
`api_key`	string	Yes	-	Your tenant API key
`contact_id`	string	Yes	-	Any contact ID in the account hierarchy (parent or child)
`page_size`	integer	No	20	Results per page (max 200)
`page_number`	integer	No	1	Page number (1-indexed)
`resource_id`	string	No	-	Filter by engineer/resource ID
`type_id`	string	No	-	Filter by job type ID
`category_id`	string	No	-	Filter by job category ID
`status`	string	No	-	Filter by status, single value or comma-separated (e.g. `completedOk,completedWithIssues`)
`result`	string	No	-	Filter by job result
`finished_early`	boolean	No	-	`true` = finished on/before planned end
`finished_late`	boolean	No	-	`true` = finished after planned end (preferred for late-finish lists)
`started_early`	boolean	No	-	`true` = started on/before planned start
`started_late`	boolean	No	-	`true` = started after planned start (preferred for late-start lists)
`date_from`	string	No	-	ISO date/datetime, include jobs on or after (inclusive)
`date_to`	string	No	-	ISO date/datetime, exclude jobs on or after (exclusive)
`date_field`	string	No	`createdAt`	Which timestamp `date_from`/`date_to` apply to: `createdAt`, `plannedStartAt`, `plannedEndAt`, `actualStartAt`, `actualEndAt`
`sort_by`	string	No	`createdAt`	Sort field: `createdAt`, `endDeltaMins`, `startDeltaMins`, `actualEndAt`, `actualStartAt`
`direction`	string	No	`desc`	Sort direction on `sort_by`, `asc` or `desc`
`compact`	boolean	No	false	Strip nulls/empties to return a compact payload for AI agents

Response includes an account block with the resolved hierarchy context:

{
  "account": {
    "parentContactId": 1234,
    "parentName": "Whitbread PLC",
    "parentReference": "W140",
    "childCount": 462,
    "contactIds": [1234, 5678, 5679, "..."],
    "contactGroup": "Parent - Agreed rates"
  },
  "jobs": ["..."],
  "page": 1,
  "pageSize": 25,
  "totalJobs": 312,
  "totalPages": 13
}

Example: all completed jobs for an account in Q1 2026

curl -G "https://api.vh3connect.io/api:kP8T1CK7/jobs/feed/account" \
  --data-urlencode "company_id=your-company-id" \
  --data-urlencode "api_key=your-api-key" \
  --data-urlencode "contact_id=5589521" \
  --data-urlencode "status=completedOk,completedWithIssues" \
  --data-urlencode "date_from=2026-01-01" \
  --data-urlencode "date_to=2026-04-01" \
  --data-urlencode "page_size=50"

Use cases:

Monthly account reviews, scope by date_from/date_to with date_field=actualEndAt to see all work delivered to a customer account in a period.
Account + type filtering, add type_id to see only fire alarm or HVAC jobs across the whole account hierarchy.
Account performance, combine with status=completedOk,completedWithIssues to measure first-visit fix rate across all child sites.
Account late finishes, use finished_late=true with date_field=actualEndAt and sort_by=endDeltaMins to rank overruns across the hierarchy.

GET /jobs/{job_id}

Returns the full enriched record for a specific job, including AI-extracted fields, linked relationships from the intelligence layer, and timing data. Path parameters:

Param	Type	Required	Description
`job_id`	string	Yes	The job identifier

Query parameters:

Param	Type	Required	Description
`company_id`	string	Yes	Your tenant identifier
`api_key`	string	Yes	Your tenant API key
`include_worksheets`	boolean	No	Include worksheet data
`compact`	boolean	No	Return compact response

Example:

curl -G "https://api.vh3connect.io/api:kP8T1CK7/jobs/12345" \
  --data-urlencode "company_id=your-company-id" \
  --data-urlencode "api_key=your-api-key" \
  --data-urlencode "include_worksheets=true"

POST /aggregate/jobs

Job metrics with groupBy dimensions and period comparison. Powers dashboard charts, trend analysis, and punctuality counts. Request body:

Field	Type	Required	Description
`company_id`	string	Yes	Your tenant identifier
`api_key`	string	Yes	Your tenant API key
`metric`	string	Yes	One of: `job_count`, `completion_rate`, `first_visit_fix_rate`, `avg_start_delta_mins`, `avg_end_delta_mins`
`time_axis`	string	No	Job timestamp for the period window (default `actualStartAt`): `actualStartAt`, `actualEndAt`, `createdAt`, `plannedStartAt`, `scheduledAt`
`period`	string	No	Period shorthand (e.g. `last_7_days`, `this_week`, `last_30_days`)
`compare_to`	string	No	Comparison period: `previous_period`, `same_period_last_week`, `same_period_last_month`
`group_by`	string	No	Dimension: `status`, `result`, `typeId`, `categoryId`, `resourceId`, `siteKey`, `vertical`, `day`, `week`, `month`
`filters`	object	No	Optional filters (see below)
`limit`	integer	No	Max groups to return

filters fields:

Field	Type	Description
`resourceId`, `contactId`, `siteKey`, `typeId`, `categoryId`	string	Entity scopes
`vertical`, `status`, `result`	string	Property filters
`finishedEarly`	boolean	`true` = finished on/before planned end
`finishedLate`	boolean	`true` = finished after planned end (preferred for late-finish counts)
`startedEarly`	boolean	`true` = started on/before planned start
`startedLate`	boolean	`true` = started after planned start (preferred for late-start counts)
`startDate`, `endDate`	string	Custom range when not using `period`

For punctuality counts, use metric=job_count with the boolean filters. Prefer finishedLate=true / startedLate=true. Pair time_axis with the question: finish / overrun → actualEndAt; start / arrival → actualStartAt. Do not estimate late counts from avg_end_delta_mins or avg_start_delta_mins — averages mask mixed early and late jobs. Follow up with GET /jobs/feed using the same filters, matching date_field, and sort_by=endDeltaMins (or startDeltaMins) for worst-N lists.

Example: jobs per engineer (last 30 days)

curl -X POST "https://api.vh3connect.io/api:kP8T1CK7/aggregate/jobs" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "your-company-id",
    "api_key": "your-api-key",
    "metric": "job_count",
    "time_axis": "actualStartAt",
    "period": "last_30_days",
    "group_by": "resourceId"
  }'

Example: finished late but started early (last 7 days)

curl -X POST "https://api.vh3connect.io/api:kP8T1CK7/aggregate/jobs" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "your-company-id",
    "api_key": "your-api-key",
    "metric": "job_count",
    "time_axis": "actualEndAt",
    "period": "last_7_days",
    "filters": {
      "startedEarly": true,
      "finishedLate": true
    }
  }'

VH3 AI Intelligence

BigChange API

Jobs

Jobs

GET /jobs/feed

GET /jobs/feed/account

GET /jobs/{job_id}

POST /aggregate/jobs

​Jobs

​GET /jobs/feed

​GET /jobs/feed/account

​GET /jobs/{job_id}

​POST /aggregate/jobs

Jobs

GET /jobs/feed

GET /jobs/feed/account

GET /jobs/{job_id}

POST /aggregate/jobs