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

# Verifying an Identity

Verify a consumer or business once to create an identity. Submit an identity you've already collected or embed Baselayer's hosted verification flow. Both options create a durable `principal_ref` (and `business_ref`, if a business is involved), against which credentials can be minted.

Using Baselayer's hosted verification flow lets you complete consumer verification using the consumer's name and phone number, and business verification using the business's registered name and address. For individuals acting as an authorized representative of a business, Baselayer also validates the authority of the individual to act on behalf of the business.

<Info>
  ### Before you start

  You need an org API key with identity submission permissions. Direct submission requires you to have already collected the person's full legal name, DOB, phone number, address, and SSN. An incomplete identity can never earn a `principal_ref`.&#x20;

  Hosted enrollment requires only a template configured for your org (see Path B below); the user supplies the rest.
</Info>

### Choosing a path

| Path | Use when |
| - | - |
| Direct submission | You already collected the identity through your own onboarding form and can send it server-to-server. |
| Hosted enrollment | You want the end user to enter their own identity directly; you never touch the raw PII. |

### Path A: Submit an identity you already collected

1. **Submit.** `POST /identity_submissions/consumer` (person only) or `POST /identity_submissions/consumer_business` (person + the business they operate). Both return `202` with a `submission_id` immediately — verification runs asynchronously.
2. **Poll or subscribe.** `GET /identity_submissions/{submission_id}` until `state` is terminal, or subscribe to the `OnboardingSession.completed` webhook. Recommended: poll every 2 seconds; consumer KYC usually completes in seconds, a full KYB pipeline can take minutes.
3. **Read the verdict.** `APPROVED`, `UNDER_REVIEW`, or `REJECTED`, plus the resulting `principal_ref` (and `business_ref` / `business_operator_link_status`, for a consumer+business submission).

Submissions are idempotent per `idempotency_key` — resubmitting the same key returns the original submission rather than starting a second verification.

### Path B: Use the hosted enrollment interface

1. **Pick a template** (optional). `GET /onboarding/templates` lists the flows configured for your org.
2. **Mint a session.** `POST /onboarding/sessions` with a `template_id` returns an `embed_url` and a one-time `session_token`. Render the URL in an iframe, or redirect the applicant to it.
3. **The applicant completes the flow** inside Baselayer's hosted UI — you don't call its internal steps yourself.
4. **Learn the outcome** the same way as Path A: poll `GET /identity_submissions/{id}` (the session's `id` *is* the `submission_id`) or receive the webhook.

### Re-verifying an identity

`POST /identities/principals/{principal_ref}/reverify` starts a fresh verification cycle against the identity's most recent submitted attributes — the `principal_ref` never changes. Use this instead of a fresh submission when an identity has expired.

### Checking an identity before minting

`GET /identities/principals/{principal_ref}` tells you whether an identity is current (`verification_state: CURRENT`), which attributes it can attest to (`active_keys`), and which businesses a person is linked to (where applicable).

### Troubleshooting

| Problem | Fix |
| - | - |
| `422` — submission payload failed validation (code `6200`) | Check the field notes in the [API Reference](/api-reference) — in particular, `phone_number` (not `phone`) and `address` as a single normalized line (not a structured object) are the most common misses. |
| `409` — a submission with this idempotency key already exists (code `6201`) | Expected behavior on a genuine retry; poll the original `submission_id` instead of resubmitting with a new key. |
| Operator link lands `UNDER_REVIEW` instead of `VERIFIED` | The business submission needs a `tin` that IRS-matches and a KYB-verified registry record — all three. Without a TIN, the business can still be `APPROVED`, but the link cannot auto-verify. |
| `409` — re-verification already in flight (code `6202`) / nothing to re-verify from (code `6203`) | Check the identity's current state (`GET /identities/principals/{principal_ref}`) before calling `reverify` again. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.