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

# Briefings

> Pre-visit engineer briefings with full operational context

# Briefings

Generate a structured pre-visit briefing and call script for an engineer assigned to a job. Pulls job and customer context from the intelligence layer (regenerates the account summary when requested) and produces markdown briefing content plus a natural-language call opener.

Designed for `onTheWay` or `scheduled` job transitions.

## POST /briefing/generate

Generate an engineer briefing for a specific job.

**Request body:**

| Field                      | Type    | Required | Description                                                                                                         |
| -------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `company_id`               | string  | Yes      | Your tenant identifier                                                                                              |
| `api_key`                  | string  | Yes      | Your tenant API key                                                                                                 |
| `job_id`                   | integer | Yes      | Job to brief                                                                                                        |
| `contact_id`               | integer | Yes      | Customer contact for the job                                                                                        |
| `force_regenerate_summary` | boolean | No       | Bypass the cached customer summary and regenerate                                                                   |
| `job_payload`              | object  | No       | Raw job fallback when the job is not yet in the intelligence layer (ignored if the job already exists in the graph) |

**Response fields:**

| Field              | Type   | Description                                                                  |
| ------------------ | ------ | ---------------------------------------------------------------------------- |
| `briefing`         | string | Structured field service briefing (markdown)                                 |
| `call_script`      | string | Natural-language call opener for voice agents                                |
| `customer_summary` | string | Full customer analytical report used as context                              |
| `job_data`         | object | Job reference, status, type, customer, engineer, planned times, site address |
| `resource_contact` | object | Engineer `mobile` and `email` from the graph                                 |
| `parent_contact`   | object | Parent customer `contact_id` and `name` when `HAS_PARENT` exists             |
| `engineer_name`    | string | Assigned engineer name                                                       |
| `generated_at`     | string | ISO 8601 generation timestamp                                                |
| `usage`            | object | Token usage for AI generation                                                |

**Example:**

```bash theme={null}
curl -X POST "https://api.vh3connect.io/api:kP8T1CK7/briefing/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "your-company-id",
    "api_key": "your-api-key",
    "job_id": 12345,
    "contact_id": 678
  }'
```

**Use cases:**

* **Pre-visit pack:** Deliver site history, equipment context, and diagnostic precedents before arrival.
* **Voice briefing:** Feed `call_script` to an outbound call agent; send `briefing` via `POST /briefing/send-email` after the call.
* **Dispatcher assist:** Regenerate with `force_regenerate_summary: true` when account context has changed since the last visit.

**Notes:**

* Uses platform AI; subject to capacity limits (`503` with `Retry-After` when saturated).
* Returns `404` when the job or contact cannot be resolved.
* Typical latency 5–15s depending on summary cache hit.