Identities

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.

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 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:

$
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

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

Filters

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

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

1
{
2
  "data": [...],
3
  "pagination": {
4
    "next_cursor": "identity_def456",
5
    "prev_cursor": "identity_abc123",
6
    "has_next": true,
7
    "has_prev": true
8
  }
9
}

Retrieving an identity

Fetch by ID or external reference:

$
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:

1
{
2
  "id": "identity_abc123",
3
  "external_ref": "user_abc123",
4
  "status": "verified",
5
  "is_flagged": false,
6
  "screening_status": "clear",
7
  "monitoring_enabled": true,
8
  "session_count": 2,
9
  "face_match_passed": true,
10
  "age_check_passed": true,
11
  "extracted_age": 28,
12
  "is_sandbox": false,
13
  "tags": ["vip"],
14
  "extracted_data": {
15
    "first_name": "Jane",
16
    "last_name": "Doe",
17
    "date_of_birth": "1997-06-15",
18
    "document_type": "drivers_license",
19
    "country": "US"
20
  },
21
  "first_verified_at": "2026-01-15T10:00:00Z",
22
  "last_verified_at": "2026-02-01T12:05:00Z",
23
  "created_at": "2026-01-15T10:00:00Z",
24
  "updated_at": "2026-02-01T12:05:00Z"
25
}

Identity sessions

List all verification sessions for an identity:

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

Updating an identity

$
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):

$
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:

$
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):

$
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:

When monitoring_enabled is true, Verifa automatically re-screens the identity on a regular schedule and when watchlists are updated. See Screening & Reports for details.

Webhooks

Related

• Sessions — How sessions create and update identities
• Screening & Reports — Continuous monitoring for identities
• Data Retention — Automatic data lifecycle management