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, date range, and sort direction. 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
`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`
`direction`	string	No	`desc`	Sort direction on `createdAt`, `asc` or `desc`
`compact`	boolean	No	false	Strip nulls/empties to return a compact payload for AI agents

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"

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
`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`
`direction`	string	No	`desc`	Sort direction on `createdAt`, `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.

GET /jobs/

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 and trend analysis. Request body:

Field	Type	Required	Description
`company_id`	string	Yes	Your tenant identifier
`api_key`	string	Yes	Your tenant API key
`metric`	string	Yes	Metric to compute (e.g. `count`, `sla_punctuality`, `first_time_fix`)
`time_axis`	string	No	Time bucketing (`day`, `week`, `month`)
`period`	string	No	Period to analyse (e.g. `last_30_days`, `last_quarter`)
`compare_to`	string	No	Comparison period (e.g. `previous_period`)
`group_by`	string	No	Dimension to group by (`engineer`, `customer`, `job_type`, `site`)
`filters`	object	No	Additional filters
`limit`	integer	No	Max groups to return

Example:

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": "count",
    "time_axis": "week",
    "period": "last_30_days",
    "group_by": "engineer"
  }'

VH3 AI Intelligence

BigChange API

Jobs

Jobs

GET /jobs/feed

GET /jobs/feed/account

GET /jobs/

POST /aggregate/jobs

​Jobs

​GET /jobs/feed

​GET /jobs/feed/account

​GET /jobs/

​POST /aggregate/jobs

Jobs

GET /jobs/feed

GET /jobs/feed/account

GET /jobs/

POST /aggregate/jobs