# Insert Index Facts

> Record new user-supplied metric values against a deal or one of its entities in the Lev API.

Source: https://www.lev.com/docs/build/index/insert-facts

Last updated: 2026-09-16

---
### `POST /api/external/v2/deals/{deal_id}/index/facts`

Record one or more user-supplied metric values on a deal

#### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `deal_id` | `integer` | Yes | The deal ID |

#### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `values` | `array` | Yes | One or more metric values to record. Must contain at least one item. |
| `values[].metric_id` | `integer` | Yes | Metric definition id (greater than 0) from /index/metric-definitions. |
| `values[].value` | `string` | Yes | The value to record. Must not be blank. |
| `values[].entity_ref` | `string` | No | Entity to attach the value to, from /index/entities (for example, property:690). Must match the metric's entity type. |
| `values[].group_ref` | `string` | No | Groups several submitted values under the same not-yet-created entity. Use only when no entity_ref is available. |

Response: `200` `results` reports the outcome of each submitted value in request order; `metric_sot_values` aggregates the SOTs that were written. Each `results[].sot` has the same shape as a `metric_sot_values` entry.

#### Error Responses

- **422** (validation_error): values must contain at least one item; value must not be blank
- **401** (unauthorized): Authentication required
- **404** (not_found): Deal not found
- **503** (service_unavailable): Deal fact insert is temporarily unavailable. Please try again shortly.