> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withverifa.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withverifa.com/_mcp/server.

# Identities

> Persistent identity records, PII management, and GDPR operations.

An **identity** is a persistent record of a verified person. When a session
completes with an `external_ref`, Verifa creates or updates an identity that
aggregates all verification sessions for that person.

> **Note**
>
> **Environment isolation**: Verifa keys are environment-scoped. A live key
> (`vk_live_*`) cannot fetch sandbox identities (or sessions/workflows) and
> vice versa — mismatched requests return 404. Use the matching key for the
> environment you want to query.

## Why identities matter

Sessions are ephemeral — they represent a single verification attempt.
Identities are persistent — they represent a person across all their
interactions with your organization:

* **Reverification** — See a person's full verification history without
  re-running checks.
* **Duplicate detection** — Detect when the same person verifies under different
  references.
* **Continuous monitoring** — AML screening is tied to identities, not sessions,
  enabling ongoing watchlist monitoring.
* **GDPR deletion** — Delete all data for a person in one API call.

## Identity lifecycle

| Status         | Description                                                 |
| -------------- | ----------------------------------------------------------- |
| `pending`      | Identity created but no completed verification yet.         |
| `verified`     | Latest verification reached an approved outcome.            |
| `rejected`     | Latest verification was rejected (by policy or reviewer).   |
| `under_review` | Latest session needs review, or an open review case exists. |
| `merged`       | Identity was consolidated into another identity record.     |
| `redacted`     | All PII has been permanently deleted (GDPR erasure).        |

Status reflects the **most recent completed session's outcome**, so it can
downgrade — e.g. `verified` → `rejected` on a failed re-verification.

Manual flagging is orthogonal to status — an identity can be `verified`
and `is_flagged=true` at the same time. See `flag_reason`, `flagged_at`,
`flagged_by` on the response.

Identities are upserted — if a session completes with an `external_ref` that
already exists, the identity is updated with the latest verification data rather
than creating a duplicate.

## Creating identities

Identities are created automatically when a session completes with an
`external_ref`. You can also create stub identities via the API:

```bash
curl -X POST https://api.withverifa.com/api/v1/identities \
  -H "X-API-Key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "user_abc123"
  }'
```

## Listing identities

```bash
curl "https://api.withverifa.com/api/v1/identities?status=verified&limit=25" \
  -H "X-API-Key: vk_live_your_key_here"
```

### Filters

| Parameter | Type    | Description                          |
| --------- | ------- | ------------------------------------ |
| `status`  | string  | Filter by identity status.           |
| `q`       | string  | Search by external reference.        |
| `limit`   | integer | Max results (default: 25, max: 100). |
| `offset`  | integer | Items to skip.                       |

The identity list supports both offset-based and cursor-based pagination. Use
cursor-based for large datasets:

```bash
curl "https://api.withverifa.com/api/v1/identities?page[after]=identity_abc123&limit=25" \
  -H "X-API-Key: vk_live_your_key_here"
```

```json
{
  "data": [...],
  "pagination": {
    "next_cursor": "identity_def456",
    "prev_cursor": "identity_abc123",
    "has_next": true,
    "has_prev": true
  }
}
```

## Retrieving an identity

Fetch by ID or external reference:

```bash
curl https://api.withverifa.com/api/v1/identities/identity_abc123 \
  -H "X-API-Key: vk_live_your_key_here"
```

Returns decrypted PII, verification history, screening status, and tags:

```json
{
  "id": "identity_abc123",
  "external_ref": "user_abc123",
  "status": "verified",
  "is_flagged": false,
  "screening_status": "clear",
  "monitoring_enabled": true,
  "session_count": 2,
  "face_match_passed": true,
  "age_check_passed": true,
  "extracted_age": 28,
  "is_sandbox": false,
  "tags": ["vip"],
  "extracted_data": {
    "first_name": "Jane",
    "last_name": "Doe",
    "date_of_birth": "1997-06-15",
    "document_type": "drivers_license",
    "country": "US"
  },
  "first_verified_at": "2026-01-15T10:00:00Z",
  "last_verified_at": "2026-02-01T12:05:00Z",
  "created_at": "2026-01-15T10:00:00Z",
  "updated_at": "2026-02-01T12:05:00Z"
}
```

## Identity sessions

List all verification sessions for an identity:

```bash
curl https://api.withverifa.com/api/v1/identities/identity_abc123/sessions \
  -H "X-API-Key: vk_live_your_key_here"
```

## Updating an identity

```bash
curl -X PATCH https://api.withverifa.com/api/v1/identities/identity_abc123 \
  -H "X-API-Key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "updated_user_id"
  }'
```

## Archiving and restoring

Soft-archive an identity (excludes from list queries but preserves data):

```bash
curl -X POST https://api.withverifa.com/api/v1/identities/identity_abc123/archive \
  -H "X-API-Key: vk_live_your_key_here"
```

Restore an archived identity:

```bash
curl -X POST https://api.withverifa.com/api/v1/identities/identity_abc123/restore \
  -H "X-API-Key: vk_live_your_key_here"
```

## GDPR redaction

Permanently delete all PII for an identity (right to erasure, Article 17):

```bash
curl -X DELETE https://api.withverifa.com/api/v1/identities/identity_abc123/data \
  -H "X-API-Key: vk_live_your_key_here"
```

This:

* Nulls all encrypted PII fields and search hashes
* Sets the identity status to `redacted`
* Fires an `identity.updated` webhook
* The identity record itself is preserved for audit purposes (ID, status,
  timestamps)

## Screening status

Each identity tracks its aggregate screening status:

| Status    | Description                                 |
| --------- | ------------------------------------------- |
| `null`    | No screening has been run.                  |
| `clear`   | Latest screening found no matches.          |
| `hit`     | Latest screening found one or more matches. |
| `pending` | Screening is in progress.                   |

When `monitoring_enabled` is `true`, Verifa automatically re-screens the
identity on a regular schedule and when watchlists are updated. See
[Screening & Reports](/core-concepts/screening-reports) for details.

## Webhooks

| Event                  | When                                                                |
| ---------------------- | ------------------------------------------------------------------- |
| `identity.created`     | A new identity record was created.                                  |
| `identity.updated`     | Identity data was updated (new session, PII change, status change). |
| `identity.archived`    | Identity was archived.                                              |
| `identity.restored`    | Identity was restored from archive.                                 |
| `identity.tag-added`   | A tag was added to the identity.                                    |
| `identity.tag-removed` | A tag was removed from the identity.                                |

## Related

* [Sessions](/core-concepts/sessions) — How sessions create and update identities
* [Screening & Reports](/core-concepts/screening-reports) — Continuous monitoring
  for identities
* [Data Retention](/api-details/data-retention) — Automatic data lifecycle management