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

# Sandbox decision flow

# Sandbox decision flow

End-to-end technical proof of the Decision Platform path in **sandbox / founder-beta**. Field names match the Decision API contract (`packages/contracts`, OpenAPI at `GET /openapi.json` on a provisioned host).

This is **not** a live lending, payments, or capital facility. Hosts may still be coming online — use the base URL Vence issues for your org.

```
Entity
  → wallet / identity links
  → consent
  → transactions
  → feature evidence
  → policy pack
  → decision
  → replay
  → audit
  → outcome
```

## 1. Create the entity

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

{
  "external_id": "ent_partner_acme_001",
  "type": "business",
  "display_name": "Acme Partner Co"
}
```

```json theme={null}
{
  "id": "ent_partner_acme_001",
  "object": "entity",
  "external_id": "ent_partner_acme_001",
  "type": "business",
  "display_name": "Acme Partner Co",
  "environment": "sandbox",
  "created_at": "2026-07-21T17:55:00.000Z"
}
```

Exact response envelope may include additional bookkeeping fields; keep `external_id` stable.

## 2. Link wallet identity

```http theme={null}
POST /v1/entities/ent_partner_acme_001/identity-links HTTP/1.1
Host: sandbox.api.vence.one
Authorization: Bearer sk_sandbox_your_key_here
Content-Type: application/json

{
  "type": "wallet",
  "provider": "sandbox_simulated",
  "provider_subject": "DemoWalletAcme111111111111111111111111",
  "display_hint": "DemoWallet…1111 (simulated)"
}
```

Wallet links feed the Trust Graph. Sandbox demos use simulated addresses — not production chain data.

## 3. Record consent

Consent is scoped to the product you will underwrite:

```http theme={null}
POST /v1/entities/ent_partner_acme_001/consents HTTP/1.1
Host: sandbox.api.vence.one
Authorization: Bearer sk_sandbox_your_key_here
Content-Type: application/json

{
  "purpose": "underwrite:business_credit_line",
  "legal_basis": "sandbox_demo",
  "data_categories": ["transactions", "identity"]
}
```

## 4. Ingest transactions (feature evidence inputs)

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

{
  "direction": "credit",
  "amount_minor": 400000,
  "currency": "USD",
  "posted_at": "2026-01-12T12:00:00.000Z",
  "category": "revenue_saas"
}
```

Repeat for the entity’s history. Prefer normalized transactions over opaque blobs so features and policy stay explainable.

## 5. Build a feature snapshot

```http theme={null}
POST /v1/entities/ent_partner_acme_001/feature-snapshots HTTP/1.1
Host: sandbox.api.vence.one
Authorization: Bearer sk_sandbox_your_key_here
Content-Type: application/json

{
  "account_opened_at": "2024-06-01T00:00:00.000Z",
  "supplied_wallet_exposure_minor": 100000
}
```

The Feature Engine (`baseline-v1`) produces versioned features with lineage (completeness, stability, anomaly indicators, concentration, repayment history, and related keys). Underwrite can also compute a snapshot from stored transactions if none exists yet.

## 6. Underwrite (policy → decision)

Product selects the policy pack (Stage 2 product dimension). Example: `business_credit_line` → `sandbox-policy-v1`.

```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 for retrieve / replay / review / outcomes. Decision evidence (feature snapshot id, policy checksum, rule trace) is persisted server-side — use replay, not a free-form evidence array on this body.

**Score vs decision:** an optional external credit score (bureau or third-party scorer) can plug in via a provider interface later. It is an **input signal**, not the Vence verdict. The same entity can receive different verdicts under different product packs (payroll advance vs business line vs market-maker facility). Vence does not claim partnership with any specific scorer.

## 7. Replay (reproducibility)

```http theme={null}
GET /v1/decisions/dec_8f3a2c1b0e9d7a6b5c4d/replay HTTP/1.1
Host: sandbox.api.vence.one
Authorization: Bearer sk_sandbox_your_key_here
```

Replay re-evaluates the stored feature snapshot against the same policy version. Exact match confirms auditability. Illustrative shape:

```json theme={null}
{
  "decision_id": "dec_8f3a2c1b0e9d7a6b5c4d",
  "policy_version": "sandbox-policy-v1",
  "exact_match": true,
  "replayed_verdict": "approve_with_conditions",
  "original_verdict": "approve_with_conditions"
}
```

## 8. Audit trail

```http theme={null}
GET /v1/entities/ent_partner_acme_001/audit-trail HTTP/1.1
Host: sandbox.api.vence.one
Authorization: Bearer sk_sandbox_your_key_here
```

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "action": "entity.created",
      "occurred_at": "2026-07-21T17:55:00.000Z",
      "request_id": "req_entity_create_001"
    },
    {
      "action": "decision.created",
      "occurred_at": "2026-07-21T18:00:00.000Z",
      "request_id": "req_a1b2c3d4e5f60718"
    }
  ]
}
```

Also retrieve the canonical decision: `GET /v1/decisions/{decision_id}`.

## 9. Record an outcome (Trust Graph feedback)

```http theme={null}
POST /v1/decisions/dec_8f3a2c1b0e9d7a6b5c4d/outcomes HTTP/1.1
Host: sandbox.api.vence.one
Authorization: Bearer sk_sandbox_your_key_here
Content-Type: application/json

{
  "outcome_type": "repayment_observed",
  "occurred_at": "2026-08-15T12:00:00.000Z",
  "metadata": {
    "amount_minor": 250000,
    "currency": "USD",
    "note": "sandbox simulated repayment"
  }
}
```

Outcomes close the loop: monitoring and future underwrites can consume updated Trust Graph evidence.

## What “good” looks like

You can walk a risk committee from **entity and wallet links** through **features, policy version, checksum, reasons, replay, audit, and outcome** without a black box — in sandbox today, with honest founder-beta host labels.

## Related

* [Underwrite](/guides/underwrite)
* [Entities](/guides/entities)
* [Decision Engine](/platform/decision-engine)
* [Policy Engine](/platform/policy-engine)
* [API overview](/developers/api-overview)