Search

The Search endpoints let you find relevant past jobs, outcomes, and intake records by describing what you’re looking for in natural language. The platform uses hybrid search, combining meaning-based matching with keyword retrieval, to surface relevant results even when terminology differs.

POST /search/outcomes

Search across AI-enriched job outcomes. This is the primary search endpoint for finding jobs by what happened, what was done, or what the result was. Request body:

Field	Type	Required	Description
`company_id`	string	Yes	Your tenant identifier
`api_key`	string	Yes	Your tenant API key
`query_text`	string	Yes	Natural language search query
`limit`	integer	No	Max results to return (default: 10)
`type_id`	string	No	Filter by job type
`category_id`	string	No	Filter by job category
`resource_id`	string	No	Filter by engineer/resource
`contact_id`	string	No	Filter by customer (contact). Preferred scope for account-level precedent search
`cleanup`	boolean	No	Whether to clean the results metadata

curl -X POST "https://api.vh3connect.io/api:kP8T1CK7/search/outcomes" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "your-company-id",
    "api_key": "your-api-key",
    "query_text": "air conditioning unit not cooling",
    "limit": 5
  }'

POST /search/outcomes/enriched

Semantic search over job outcomes with relationship enrichment from the intelligence layer. Same request body and filters as POST /search/outcomes. Adds related_works grouped by job type, engineer, and site for each hit set. Request body:

Field	Type	Required	Description
`company_id`	string	Yes	Your tenant identifier
`api_key`	string	Yes	Your tenant API key
`query_text`	string	Yes	Natural language search query (3–2000 characters)
`limit`	integer	No	Max results (default 10, max 100)
`type_id`	integer	No	Filter by job type
`category_id`	integer	No	Filter by job category
`job_group_id`	integer	No	Filter by job group
`vertical`	string	No	Filter by AI-classified vertical
`sub_vertical`	string	No	Filter by AI-classified sub-vertical
`resource_id`	integer	No	Filter by engineer
`contact_id`	integer	No	Filter by customer contact
`site_key`	string	No	Filter by site
`start_date`	string	No	Lower bound on `actual_start_at` (`YYYY-MM-DD`)
`end_date`	string	No	Upper bound on `actual_start_at` (`YYYY-MM-DD`)
`status`	string	No	Filter by job status
`result`	string	No	Filter by job result

Response fields:

Field	Type	Description
`hits`	array	Slim outcome hits (`job_id`, `job_ref`, `score`, `contact_id`, `status`, `summary`, etc.)
`count`	integer	Number of hits
`related_works`	object	`by_type`, `by_engineer`, `by_site` aggregates derived from the hit set

curl -X POST "https://api.vh3connect.io/api:kP8T1CK7/search/outcomes/enriched" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "your-company-id",
    "api_key": "your-api-key",
    "query_text": "replaced PCB on Vaillant ecoTEC, F28 fault cleared",
    "limit": 10,
    "contact_id": 12345
  }'

Use cases:

Fault resolution: Find similar past fixes and see completion patterns for that job type.
Engineer fit: Check whether engineers on matched outcomes have history with the customer or fault class.
Site risk: Surface repeat failures at the site alongside semantically similar outcomes.

Notes:

Slower than /search/outcomes due to relationship enrichment (~500ms–1s additional).
related_works keys are derived from returned hits only, not the full matching corpus.
Returns 502 if semantic search or enrichment fails.

POST /search/intake

Search across raw job intake text, the original fault descriptions as entered by dispatchers or customers. Request body:

Field	Type	Required	Description
`company_id`	string	Yes	Your tenant identifier
`api_key`	string	Yes	Your tenant API key
`query_text`	string	Yes	Natural language search query
`limit`	integer	No	Max results to return (default: 10)

curl -X POST "https://api.vh3connect.io/api:kP8T1CK7/search/intake" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "your-company-id",
    "api_key": "your-api-key",
    "query_text": "heating system tripping",
    "limit": 5
  }'

POST /search/intake/enriched

Semantic search over job intake text with relationship enrichment, returns richer context by joining linked records to each result. Request body:

Field	Type	Required	Description
`company_id`	string	Yes	Your tenant identifier
`api_key`	string	Yes	Your tenant API key
`query_text`	string	Yes	Natural language search query
`limit`	integer	No	Max results to return

curl -X POST "https://api.vh3connect.io/api:kP8T1CK7/search/intake/enriched" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "your-company-id",
    "api_key": "your-api-key",
    "query_text": "fire alarm fault",
    "limit": 5
  }'

GET /search/autocomplete

Fuzzy / phonetic / email-aware lookup across contacts, persons (site contacts and account holders), engineers, jobs, and taxonomy entities. Returns results grouped by entity type plus a flat results[] array for back-compat. Query parameters:

Param	Type	Required	Description
`company_id`	string	Yes	Your tenant identifier
`api_key`	string	Yes	Your tenant API key
`q`	string	Yes	Search text, name, postcode, email address, UUID personId, phone, reference, or numeric id
`limit`	integer	No	Max results per group (default 10, max 50)
`types`	string	No	Comma-separated filter. Allowed: `contact`, `person`, `engineer`, `job`, `job_type`, `job_category`, `contact_group`, `resource_group`

Search capabilities:

Name / phonetic: Smyth finds Smith; PureGym finds Pure Gym
Email: type a full or partial email (ric@vezzahub.com, ric@) to find the matching person directly. Results carry matchedVia: "email".
UUID / personId: paste a standard UUID to resolve the person directly via their ids array. Returns matchedVia: "person_id" with score 1.0.
Postcode: UK postcodes with or without a space (NN10 5AB / NN105AB)
Reference: job reference or order number prefix
Numeric id: bare integer resolves contactId, resourceId, or jobId

curl -G "https://api.vh3connect.io/api:kP8T1CK7/search/autocomplete" \
  --data-urlencode "company_id=your-company-id" \
  --data-urlencode "api_key=your-api-key" \
  --data-urlencode "q=ric@vezzahub.com" \
  --data-urlencode "limit=10"

The response groups results under groups.contacts, groups.people, groups.engineers, groups.jobs, groups.jobTypes, groups.jobCategories, groups.contactGroups, and groups.resourceGroups. Each result includes a matchedVia field indicating why it was returned (name, email, person_id, postcode, phonetic, reference, id, site_bridge, etc.). Use cases:

Typeahead UI: Power customer, site, and job pickers in dispatch or ingest review screens.
Email entity resolution: Resolve portal payloads to contact_id and site_key before POST /ingest/email/portal.
Connie grounding: Disambiguate names or postcodes before semantic search or graph queries.

Notes:

Minimum query length is 2 characters. Accepts any entity Id such as contact, job, job_group_id, reference, resource etc
Use GET /search/autocomplete/diagnose when all groups return empty (index health).

GET /search/autocomplete/diagnose

Health check for the autocomplete index pipeline (always returns 200; inspect missing, populating, advice). Query parameters:

Param	Type	Required	Description
`company_id`	string	Yes	Your tenant identifier
`api_key`	string	Yes	Your tenant API key

curl -G "https://api.vh3connect.io/api:kP8T1CK7/search/autocomplete/diagnose" \
  --data-urlencode "company_id=your-company-id" \
  --data-urlencode "api_key=your-api-key"

POST /search/summary-sections

Hybrid search across Customer Summary knowledge sections. Each customer can have up to seven modular sections (overview, job history, equipment, analyses, performance, communication, risk). Each section is indexed independently so you can search one dimension or all of them. Results are ranked without an LLM call. Request body:

Field	Type	Required	Description
`company_id`	string	Yes	Your tenant identifier
`api_key`	string	Yes	Your tenant API key
`query_text`	string	Yes	Natural language search query
`section_key`	string	No	Limit to one section. Allowed: `customer_overview`, `job_history_patterns`, `systems_equipment`, `key_analyses`, `operational_performance`, `communication_summary`, `risk_opportunity`
`contact_id`	string	No	Scope to one customer
`limit`	integer	No	Max results (default: 10)

curl -X POST "https://api.vh3connect.io/api:kP8T1CK7/search/summary-sections" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "your-company-id",
    "api_key": "your-api-key",
    "query_text": "recurring boiler issues on PPM contracts",
    "section_key": "risk_opportunity",
    "limit": 5
  }'

GET /search/summary-sections/by-contact//

Return the full stored Customer Summary for one contact (all sections). Use when you need the complete account brief in a single call rather than a ranked search.

curl -G "https://api.vh3connect.io/api:kP8T1CK7/search/summary-sections/by-contact/your-company-id/your-contact-id" \
  --data-urlencode "api_key=your-api-key"

Summaries are generated from the operational graph and refreshed incrementally by the account summary pipeline. See Operational discovery for how summaries stay current in Connie sessions.

VH3 AI Intelligence

BigChange API

Search

Search

POST /search/outcomes

POST /search/outcomes/enriched

POST /search/intake

POST /search/intake/enriched

GET /search/autocomplete

GET /search/autocomplete/diagnose

POST /search/summary-sections

GET /search/summary-sections/by-contact//

​Search

​POST /search/outcomes

​POST /search/outcomes/enriched

​POST /search/intake

​POST /search/intake/enriched

​GET /search/autocomplete

​GET /search/autocomplete/diagnose

​POST /search/summary-sections

​GET /search/summary-sections/by-contact//

Search

POST /search/outcomes

POST /search/outcomes/enriched

POST /search/intake

POST /search/intake/enriched

GET /search/autocomplete

GET /search/autocomplete/diagnose

POST /search/summary-sections

GET /search/summary-sections/by-contact//