# Start a Verification

> Coming soon, upon request — this feature is turned on for your tenant by the Aurea team. [Contact us](https://www.aureahub.com/contact)

Start the verification of one of your users — a person or a company — and get the link to the verification page; or, for the user's live verification, get it again with a fresh link.

## Overview

- Called from your server, signed by your tenant — the HMAC headers `x-tenant-api-key`, `x-timestamp` and `x-signature`, or a server token of a credential whose role is `tenantadmin` or `non_signing_admin` ([Authentication](https://docs.aureahub.com/docs/authentication.md), [Server Credentials](https://docs.aureahub.com/docs/guide-server-credentials.md)) —, in one environment (`isTestnet`). Not with a user's or an administrator's access token. Up to 600 calls a minute.
- `201`: a new verification, `started`. `200`: the user's live verification of that kind and purpose — `started`, `in_review` or `verified` —, never a second one. After `rejected` or `expired`, a new verification: `201` with a new `id`.
- `verificationUrl`: a fresh link while the verification is `started`; `null` when there is nothing to complete. Open it right away and exactly as it is, in the browser, an iframe or a WebView; never store, log or share it ([Identity Verification](https://docs.aureahub.com/docs/guide-identity.md) › Show the Verification Page, In a Mobile App).
- `returnUrl`, optional: accepted and checked — `https` or your app's own scheme, never `http` — but not used by the verification page, which ends on its own completion screen; bring the user back from your app.
- The rest of the answer is the verification as [Get a Verification](https://docs.aureahub.com/docs/identity-verification-get.md) answers it.

## Endpoint

### `POST /v1/identity/verifications`

Starts a user's verification, or answers the live one — with a fresh link to the verification page while it is started. Signed by your tenant.

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `userId` | string | yes | One of your tenant's users (UUID) |
| `kind` | string | yes | `person` (KYC) or `company` (KYB) |
| `purpose` | string | yes | What it is for: `bank_ramp` |
| `returnUrl` | string \| null | no | Accepted and checked (`https` or your app's own scheme, up to 2048 characters), but not used by the verification page: it ends on its own completion screen |
| `isTestnet` | boolean | no | `true` for the sandbox; `false` or omitted for production |

**Responses**

`201` Started

```json
{
  "id": "7c1e9a24-5b3d-4f8a-9e6c-2d0b4a8f1e37",
  "userId": "5d2c1b0a-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
  "kind": "person",
  "purpose": "bank_ramp",
  "state": "started",
  "nextStep": "continue_verification",
  "reason": null,
  "aml": null,
  "createdAt": "2026-11-12T10:02:11.000Z",
  "updatedAt": "2026-11-12T10:02:11.000Z",
  "verificationUrl": "https://…"
}
```

`200` In review

```json
{
  "id": "7c1e9a24-5b3d-4f8a-9e6c-2d0b4a8f1e37",
  "userId": "5d2c1b0a-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
  "kind": "person",
  "purpose": "bank_ramp",
  "state": "in_review",
  "nextStep": "wait_for_review",
  "reason": "manual_review",
  "aml": {
    "status": "PENDING"
  },
  "createdAt": "2026-11-12T10:02:11.000Z",
  "updatedAt": "2026-11-12T10:09:47.000Z",
  "verificationUrl": null
}
```

`400` Not valid

```json
{
  "statusCode": 400,
  "error": "BadRequestError",
  "message": "The request is not valid.",
  "details": {
    "code": "IDENTITY_INVALID",
    "fields": ["kind"]
  }
}
```

`403` Not switched on

```json
{
  "statusCode": 403,
  "error": "ForbiddenError",
  "message": "Identity verification is not on for this tenant's sandbox environment.",
  "details": {
    "code": "IDENTITY_DISABLED",
    "environment": "sandbox",
    "nextStep": "ask Aurea to switch identity verification on"
  }
}
```

`404` Not your user

```json
{
  "statusCode": 404,
  "error": "NotFoundError",
  "message": "No such user in this tenant.",
  "details": {
    "code": "IDENTITY_SUBJECT_NOT_FOUND"
  }
}
```

`409` Page not opened

```json
{
  "statusCode": 409,
  "error": "ConflictError",
  "message": "…",
  "details": {
    "code": "IDENTITY_SESSION_CONFLICT",
    "nextStep": "…"
  }
}
```

`503` Unavailable

```json
{
  "statusCode": 503,
  "error": "IdentityError",
  "message": "Identity verification is unavailable: try again later",
  "details": {
    "code": "IDENTITY_PROVIDER_UNAVAILABLE"
  }
}
```

---

Web version: https://docs.aureahub.com/#identity-verification-create