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

# Underwrite

# Underwrite

Underwrite is the flagship Decision Platform call: given an entity and context, return who should get access or credit — and **why**.

## Flow

### Ensure the entity exists

`POST /v1/entities` (or retrieve by id). Keep your `external_id` stable.

### Attach context

Identity links, consents, transactions, and feature snapshots as your program requires.

### Call underwrite

`POST /v1/underwrite` with your product / program code and an `Idempotency-Key`.

### Persist the record

Store `id` (decision id), verdict, reasons, recommended limit, policy version, and model version.

### Monitor

Subscribe to webhooks and monitoring so material changes re-enter policy.

## Sandbox example (founder-beta)

Illustrative `sandbox-policy-v1` response for a business credit line request. Field names match the Decision API contract (`packages/contracts` + `/v1/underwrite`). Host status: **founder-beta / coming online** — use the base URL Vence issues for your org.

```http theme={null}
POST /v1/underwrite HTTP/1.1
Host: sandbox.api.vence.one
Authorization: Bearer sk_sandbox_your_key_here
Idempotency-Key: idem_uw_acme_20260721_001
Content-Type: application/json

{
  "entity_id": "ent_partner_acme_001",
  "product": "business_credit_line",
  "requested_amount": 40000,
  "currency": "USD"
}
```

```json theme={null}
{
  "id": "dec_8f3a2c1b0e9d7a6b5c4d",
  "object": "underwriting_decision",
  "environment": "sandbox",
  "verdict": "approve_with_conditions",
  "recommended_limit": 40000,
  "repayment_probability": 0.807,
  "risk_tier": "A-",
  "confidence": 0.879,
  "reason_codes": [
    {
      "code": "customer_concentration",
      "label": "Revenue concentration above policy comfort band",
      "impact": "negative"
    },
    {
      "code": "repayment_observed",
      "label": "Repayment activity observed in transaction history",
      "impact": "positive"
    }
  ],
  "conditions": [
    {
      "code": "customer_concentration",
      "label": "Elevated customer concentration — monitor exposure"
    }
  ],
  "model_version": "sandbox-policy-v1",
  "policy_version": "sandbox-policy-v1",
  "policy_checksum": "acba373cd9d201f9794c571b935e184b7737a24c715350441b0f27dcc2201b72",
  "request_id": "req_a1b2c3d4e5f60718",
  "created_at": "2026-07-21T18:00:00.000Z"
}
```

`id` is the decision id used in retrieve / replay / review paths. Decision evidence (feature snapshot, policy checksum, rule trace) is persisted server-side — retrieve it via `GET /v1/decisions/{id}/replay`, not as a free-form array on the underwrite body.

## What you get back

* Verdict (`approve` / `approve_with_conditions` / `manual_review` / `decline`)
* Recommended limit (major units) when policy approves
* Principal reason codes (with impact)
* Conditions (when applicable)
* Policy version, model version, and policy checksum
* Confidence and repayment probability when the engine returns them

## Retrieve and replay

* `GET /v1/decisions/{decision_id}` — canonical decision
* `GET /v1/decisions/{decision_id}/replay` — replay policy evaluation for audit
* `POST /v1/decisions/{decision_id}/reviews` — human review
* `POST /v1/decisions/{decision_id}/outcomes` — record real-world outcomes into the Trust Graph

Use Console → Playground to inspect the same decision a human operator sees.

## What “good” looks like

You explain the decision to a risk committee without opening a black box. That is the product.

See [Sandbox decision flow](/guides/sandbox-decision-flow) for the full entity → features → policy → decision → replay → audit → outcome path with request/response examples. Also [Entities](/guides/entities), [Decision Engine](/platform/decision-engine), [Webhooks](/developers/webhooks).