---
title: "Persona"
description: "Use Persona for MainSDK identity checks with configurable flows - API key, main.yaml per market, sandbox testing and swapping."
section: "integrations"
canonical: "https://mainsdk.dev/docs/integrations/persona"
updated: "2026-10-28"
---

# Persona

> Use Persona for MainSDK identity checks with configurable flows - API key, main.yaml per market, sandbox testing and swapping.

Canonical: https://mainsdk.dev/docs/integrations/persona · Updated: 2026-10-28

Persona runs identity verification flows you configure, such as a government ID check with a selfie. Behind [`verify`](https://mainsdk.dev/docs/interfaces/verify), it runs `verify.identity()` in the markets you route to it. Pick it when you want to shape the verification steps per use case without changing app code.

> **Note:** Built (spec `verify`). The Persona requests (an inquiry from a template, a one-time link, the inquiry read back by its id) follow Persona's public docs and are tested against recorded replies, not a live account. Run one inquiry in the sandbox before a market depends on it.

## Interfaces it serves

### Phone, email and identity checks (`verify`)

- Status: Building for 0.7 · ships as a beta API
- Driver: `persona` (Persona). identity
- Docs: https://mainsdk.dev/docs/interfaces/verify.md

```yaml
verify:
  driver: persona
```

Swap to another provider: `twilio-verify`, `bird`, `local`, `digilocker`, `onfido`.

## Before you start

1. **Get a Persona account.** It has a sandbox and a production environment.
2. **Build an inquiry template** for the checks your flow needs.
3. **Create an API key** for each environment and keep it in your secrets manager.

## Configure

```yaml title="main.yaml"
verify:
  driver: twilio-verify      # phone and email checks
  identity: { us: persona }  # market to identity driver
  require: { us: high }      # persona reaches high
  drivers:
    persona:
      key: secret:PERSONA_API_KEY   # the API key of the environment
      template: itmpl_123           # the inquiry template that runs the checks
```

## Use it

```ts title="lib/kyc.ts"
import { verify } from "mainsdk/verify";

export async function startCheck(user: string) {
  const started = await verify.identity({
    level: "high",
    market: "us",
    claims: ["age_over_18"],
    purpose: "Open an account",
    user,
    consent: { policy: "privacy-2026-10" },
  });
  return started.url;   // Persona's one-time link; later verify.identity.complete({ id: started.id })
}
```

## Local development and testing

Use Persona's sandbox with a sandbox key. In tests, set `verify.identity.default: local`: the local fake approves with `code: "approve"` and keeps nothing but the asked claims.

## What MainSDK adds on top

One call for identity checks in every market, routed by `identity`, and swappable with no code change. Only the claims you ask for are kept, each labelled, with a consent record; a level the driver cannot reach fails with `MAIN-VERIFY-0004` before the person is sent anywhere.

See [Phone, email and identity checks](https://mainsdk.dev/docs/interfaces/verify).

## Limits and notes

- Built `verify` driver (spec `verify`). It declares its own host, `withpersona.com`, so `network.allow` does not change.
- Persona reaches the `high` level; the template you name decides which checks run.
- Identity results are personal data; label the fields that store them in [`db`](https://mainsdk.dev/docs/interfaces/db).

## Swap to or from it

```yaml title="main.yaml"
verify:
  identity: { us: onfido }   # was { us: persona }
```

Results you keep live in your own `db`. Inquiries already run stay in Persona.

## FAQ

**Can I use Persona in one market and DigiLocker in India?** Yes. Route each market in `identity`, for example `{ us: persona, in: digilocker }`.

## Next

- [Phone, email and identity checks](https://mainsdk.dev/docs/interfaces/verify)
- [Onfido](https://mainsdk.dev/docs/integrations/onfido) and [DigiLocker](https://mainsdk.dev/docs/integrations/digilocker)
- [Swap a driver](https://mainsdk.dev/docs/guides/swap-a-driver)