Identity Verification

The Identity Verification API manages the full KYC lifecycle — from initiating a verification to retrieving status and handling manual reviews. Each verification tracks document checks, liveness, and overall compliance status.

POST/verifications/identity

Start a new identity verification for a user. If an active (PENDING/IN_PROGRESS) verification exists, it returns the existing one.

Request Body

Parameter	Type	Description
`userId`required	string	Unique identifier for the user to verify
`tier`	enum	Verification tier: BASIC, STANDARD, or ENHANCED. Defaults to BASIC.

Verification Tiers

Parameter	Type	Description
`BASIC`	tier	Document verification only
`STANDARD`	tier	Document + liveness check
`ENHANCED`	tier	Document + liveness + sanctions screening

Code Examples

curl -X POST https://api.verifyhq.com/v1/verifications/identity \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "tier": "ENHANCED"
  }'

Response

201 Createdjson

{
  "id": "ver_abc123",
  "userId": "user_123",
  "tier": "ENHANCED",
  "status": "PENDING",
  "steps": {
    "document": "PENDING",
    "liveness": "PENDING"
  },
  "createdAt": "2025-01-15T10:30:00Z"
}

GET/verifications/identity/:id

Retrieve a verification by its unique ID.

curl https://api.verifyhq.com/v1/verifications/identity/ver_abc123 \
  -H "X-API-Key: your_api_key"

Response

200 OKjson

{
  "id": "ver_abc123",
  "userId": "user_123",
  "tier": "ENHANCED",
  "status": "VERIFIED",
  "steps": {
    "document": "VERIFIED",
    "liveness": "PASSED"
  },
  "completedAt": "2025-01-15T10:35:00Z",
  "createdAt": "2025-01-15T10:30:00Z"
}

GET/verifications/identity/user/:userId

List all verifications for a specific user with pagination.

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20, max: 100)

Examplebash

curl "https://api.verifyhq.com/v1/verifications/identity/user/user_123?page=1&limit=10" \
  -H "X-API-Key: your_api_key"

POST/verifications/identity/:id/review

Submit a manual review decision. For verifications in MANUAL_REVIEW or PENDING status.

Request Body

Parameter	Type	Description
`decision`required	enum	VERIFIED or REJECTED
`reviewedBy`required	string	Identifier of the reviewer
`reviewNotes`required	string	Notes explaining the review decision

Requestjson

{
  "decision": "VERIFIED",
  "reviewedBy": "admin_john",
  "reviewNotes": "Document manually verified. All fields match."
}

POST/verifications/identity/:id/restart

Invalidate the current verification and start a new one. Use when a previous verification was rejected or expired.

Examplebash

curl -X POST https://api.verifyhq.com/v1/verifications/identity/ver_abc123/restart \
  -H "X-API-Key: your_api_key"

Verification Statuses

Parameter	Type	Description
`PENDING`	status	Verification created, awaiting document/liveness submissions
`IN_PROGRESS`	status	Documents submitted, verification processing
`MANUAL_REVIEW`	status	Requires human review (flagged by AI)
`VERIFIED`	status	All checks passed successfully
`REJECTED`	status	Verification failed one or more checks
`EXPIRED`	status	Verification timed out (not completed within window)