> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vh3.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> Semantic and keyword search across your operational history

# 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                                            |

```bash theme={null}
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                   |

```bash theme={null}
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) |

```bash theme={null}
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         |

```bash theme={null}
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`

```bash theme={null}
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    |

```bash theme={null}
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)                                                                                                                                                               |

```bash theme={null}
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/{company_id}/{contact_id}

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.

```bash theme={null}
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](/guides/operational-discovery) for how summaries stay current in Connie sessions.

Incremental refresh endpoint: `POST /backfill/summary-kb` (tenant-authenticated; same `company_id` + `api_key` envelope).