# ID verification

Verify that a person is who they claim — government-ID document checks, liveness, or biometric matching — from a single API call. Your agent originates the verification and gets back a **hosted capture URL**; the person completes document/selfie capture there; the verdict comes back through the API or a webhook. No identity-vendor contract, no monthly minimum.

```bash
curl -X POST https://api.relaystation.ai/v1/idverify/verifications \
  -H 'Authorization: Bearer rs_live_<key>' \
  -H 'Idempotency-Key: kyc-jane-20260611' \
  -H 'Content-Type: application/json' \
  -d '{ "type": "document", "addons": { "aml": true } }'
```

The response carries the verification `id`, its `status`, and the `hostedUrl` to hand to the end-user.

## How a verification runs

1. **Originate** — `POST /v1/idverify/verifications` with a `type`: `document` (government-ID), `liveness` (live-person selfie), or `biometric` (selfie ↔ document face match). Optional `addons.aml` adds sanctions/watchlist screening, decoupled from the type. Optional `sandbox: true` runs the flow against the sandbox; `metadata` (≤ 4 KB) rides along for your own correlation.
2. **Capture** — hand the returned `hostedUrl` to the person; they complete the document/selfie capture on the hosted UI. Nothing in your stack touches the raw ID images.
3. **Resolve** — poll `GET …/{id}/status` (live from the provider, authoritative) or register a webhook. Statuses: `PENDING → IN_REVIEW → VERIFIED | REJECTED | FAILED | EXPIRED`, with a `finalResult` verdict and a composite `riskScore`. Webhook events: `verification.started / document_processed / age_check / manual_review / completed / failed / expired`.

## Billing

One price: **$0.50 per verification originated** (`idverify.verification`), charged on attempt. The charge stands whether the person passes or fails the check — what you're buying is the verification run, not a particular verdict. Reads, lists, and status polls are free. Every billable call requires an `Idempotency-Key`; a same-key retry returns the already-created verification without re-charging.

## The API

| Route | What it does | Price |
|---|---|---|
| `POST /v1/idverify/verifications` | Originate a verification; returns `id` + `hostedUrl` | $0.50 |
| `GET /v1/idverify/verifications` | List your verifications (paginated, UPPERCASE status filter) | free |
| `GET /v1/idverify/verifications/{id}` | Fetch the cached verification | free |
| `GET /v1/idverify/verifications/{id}/status` | Live status from the provider (authoritative, self-healing) | free |

## MCP tools

Callable over MCP at `https://api.relaystation.ai/mcp`: `idverify_create` (billable, directly invocable), `idverify_status`, and `idverify_list`. Same auth, same price as the HTTP routes.

## Agent-native by design

Identity capture is inherently human — someone has to hold the ID up to a camera — but everything around it is programmatic. An agent with an API key or an x402 wallet originates the check, relays the `hostedUrl` to the person, and consumes the verdict from a webhook or a status poll, without an identity-vendor dashboard in the loop. One balance funds it alongside every other Relaystation product.

## Next

[Quickstart](/docs/quickstart) · [Authentication](/docs/authentication) · [Webhooks](/docs/webhooks) · [x402 wire format](/docs/x402) · [API reference](/api-reference)