Verifications API

Complete API reference for identity verification workflows including document verification, biometrics, and face matching.

Verifications API

Create and manage identity verification workflows programmatically. Supports document verification, selfie capture, face matching, and liveness detection.

Overview

The Verifications API follows a three-step process:

Create Applicant - Store customer information
Start Verification - Initiate verification workflow
Check Status - Poll or receive webhook with results

1 Credit Document verification 3 Credits Selfie + Face match 1 Credit Enhanced verification (with liveness)

Create Verification

POST/api/v3/verifications🔒 Auth Required1 Credit

Start a new identity verification

Create a new verification for an existing applicant.

Request Body

Field	Type	Required	Description
`applicantId`	string	Yes	Applicant ID from `/applicants` endpoint
`profileType`	string	No	`EXPRESS`, `STANDARD`, or `ENHANCED` (default: `STANDARD`)
`callbackUrl`	string	No	Webhook URL for async results
`metadata`	object	No	Custom metadata (max 10 keys)

Verification Profiles

Profile	Checks	Time	Cost
EXPRESS	Document only	~30s	1 Credit
STANDARD	Document + Selfie + Face match	~60s	1 Credit
ENHANCED	Document + Liveness + Face match	~90s	2 Credits

Example Request

const response = await fetch('https://api.veriplus.co.uk/api/v3/verifications', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    applicantId: 'app_1234567890',
    profileType: 'STANDARD',
    callbackUrl: 'https://yourdomain.com/webhooks/verification',
    metadata: {
      orderId: 'order_abc123',
      source: 'mobile_app'
    }
  })
});
 
const data = await response.json();
console.log('Verification ID:', data.data.verificationId);

Response

{
  "success": true,
  "data": {
    "verificationId": "verif_abc123xyz",
    "applicantId": "app_1234567890",
    "status": "PENDING",
    "profileType": "STANDARD",
    "uploadUrl": "https://upload.veriplus.co.uk/v/abc123xyz",
    "expiresAt": "2024-01-15T11:30:00Z",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Upload URL: Direct the user to this URL to upload documents and selfie. URL expires in 1 hour.

Get Verification Status

GET/api/v3/verifications/:id🔒 Auth Required0

Retrieve verification results

Check the status and results of a verification.

const verificationId = 'verif_abc123xyz';
 
const response = await fetch(
  `https://api.veriplus.co.uk/api/v3/verifications/${verificationId}`,
  {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  }
);
 
const data = await response.json();
console.log('Status:', data.data.status);
console.log('Result:', data.data.result);

Response

{
  "success": true,
  "data": {
    "verificationId": "verif_abc123xyz",
    "applicantId": "app_1234567890",
    "status": "COMPLETED",
    "result": "APPROVED",
    "profileType": "STANDARD",
    "checks": {
      "document": {
        "status": "PASS",
        "documentType": "PASSPORT",
        "country": "GBR",
        "fraudScore": 12,
        "extractedData": {
          "firstName": "JOHN",
          "lastName": "DOE",
          "dateOfBirth": "1990-01-15",
          "documentNumber": "AB123456C",
          "expiryDate": "2030-01-15"
        }
      },
      "faceMatch": {
        "status": "PASS",
        "score": 92,
        "threshold": 85
      }
    },
    "creditsUsed": 2,
    "completedAt": "2024-01-15T10:32:14Z"
  }
}

Verification Statuses

Status	Description
`PENDING`	Awaiting user upload
`IN_PROGRESS`	Processing documents
`COMPLETED`	Verification finished
`FAILED`	Technical failure (retryable)
`MANUAL_REVIEW`	Requires human review

Verification Results

Result	Description	Action
`APPROVED`	All checks passed	Accept customer
`REJECTED`	Checks failed	Reject customer
`REVIEW`	Uncertain, needs manual review	Review manually

List Verifications

GET/api/v3/verifications🔒 Auth Required0

List all verifications

Retrieve a paginated list of verifications.

Query Parameters

Parameter	Type	Description
`limit`	number	Results per page (default: 20, max: 100)
`cursor`	string	Pagination cursor
`status`	string	Filter by status
`result`	string	Filter by result
`applicantId`	string	Filter by applicant
`createdFrom`	string	ISO 8601 date
`createdTo`	string	ISO 8601 date

const params = new URLSearchParams({
  status: 'COMPLETED',
  result: 'APPROVED',
  limit: '50',
  createdFrom: '2024-01-01T00:00:00Z'
});
 
const response = await fetch(
  `https://api.veriplus.co.uk/api/v3/verifications?${params}`,
  {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  }
);
 
const data = await response.json();
console.log(`Found ${data.data.length} verifications`);

Response

{
  "success": true,
  "data": [
    {
      "verificationId": "verif_abc123",
      "applicantId": "app_123",
      "status": "COMPLETED",
      "result": "APPROVED",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "xyz789",
    "total": 1234
  }
}

Get Verification Documents

GET/api/v3/verifications/:id/documents🔒 Auth Required0

Download uploaded documents

Retrieve URLs to download document images and selfies.

const response = await fetch(
  `https://api.veriplus.co.uk/api/v3/verifications/${verificationId}/documents`,
  {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  }
);
 
const data = await response.json();
 
// Download document image
const docResponse = await fetch(data.data.document.url);
const docBlob = await docResponse.blob();

Response

{
  "success": true,
  "data": {
    "document": {
      "url": "https://storage.veriplus.co.uk/docs/abc123.jpg?token=...",
      "expiresAt": "2024-01-15T11:30:00Z",
      "type": "PASSPORT"
    },
    "selfie": {
      "url": "https://storage.veriplus.co.uk/selfies/xyz789.jpg?token=...",
      "expiresAt": "2024-01-15T11:30:00Z"
    }
  }
}

Note: Download URLs expire in 1 hour. Tokens are single-use.

Retry Failed Verification

POST/api/v3/verifications/:id/retry🔒 Auth Required2 Credits

Retry a failed verification

Retry a verification that failed due to technical issues.

const response = await fetch(
  `https://api.veriplus.co.uk/api/v3/verifications/${verificationId}/retry`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  }
);
 
const data = await response.json();
console.log('New verification ID:', data.data.verificationId);

Note: Credits consumed for retry (not refunded from original attempt).

Delete Verification Data

DELETE/api/v3/verifications/:id🔒 Auth Required0

Delete verification data (GDPR compliance)

Permanently delete verification data including uploaded documents.

Permanent Deletion

This action is irreversible. All documents, selfies, and extracted data will be permanently deleted.

const response = await fetch(
  `https://api.veriplus.co.uk/api/v3/verifications/${verificationId}`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  }
);
 
if (response.ok) {
  console.log('Verification data deleted');
}

Custom Verification Profiles

Create custom verification workflows with specific checks and thresholds.

POST/api/v3/verification-profiles🔒 Auth Required0

Create a custom verification profile

const response = await fetch('https://api.veriplus.co.uk/api/v3/verification-profiles', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'High-Value Customer',
    description: 'For transactions above $10,000',
    steps: [
      {
        type: 'document',
        required: true,
        allowedDocuments: ['PASSPORT', 'NATIONAL_ID'],
        fraudThreshold: 30
      },
      {
        type: 'selfie',
        required: true,
        livenessType: 'ACTIVE'
      },
      {
        type: 'face_match',
        required: true,
        minimumScore: 90
      }
    ],
    autoApprove: {
      enabled: false
    }
  })
});
 
const data = await response.json();
console.log('Profile ID:', data.data.profileId);

See Verification Profiles for complete guide.

Webhooks

Receive real-time notifications for verification events:

Events:

verification.created - Verification started
verification.pending_upload - Awaiting user upload
verification.completed - Verification finished
verification.approved - Auto-approved
verification.rejected - Auto-rejected
verification.manual_review - Needs human review

Webhook Payload:

{
  "event": "verification.completed",
  "timestamp": "2024-01-15T10:32:14Z",
  "data": {
    "verificationId": "verif_abc123",
    "applicantId": "app_1234567890",
    "status": "COMPLETED",
    "result": "APPROVED"
  }
}

See Webhooks Documentation for setup instructions.

Error Handling

Error Code	HTTP Status	Description	Solution
`APPLICANT_NOT_FOUND`	404	Applicant ID doesn't exist	Verify applicant ID
`INSUFFICIENT_CREDITS`	402	Not enough credits	Purchase credits
`VERIFICATION_EXPIRED`	410	Upload URL expired	Create new verification
`INVALID_PROFILE`	400	Unknown profile type	Use EXPRESS/STANDARD/ENHANCED
`DUPLICATE_VERIFICATION`	409	Verification already exists	Use existing verification

Rate Limits

Plan	Verifications per Minute
FREE	5
BASIC	20
PROFESSIONAL	100
ENTERPRISE	Unlimited

Best Practices

Use Idempotency Keys: Prevent duplicate verifications during retries
Implement Webhooks: Don't poll for status updates
Handle Expiry: Upload URLs expire in 1 hour - create new verification if needed
Store Verification IDs: Save IDs in your database for audit trail
Delete Old Data: Comply with GDPR by deleting data after retention period
Monitor Credit Usage: Track credit consumption to avoid interruptions

Next Steps

Applicants API

Create and manage applicants.

Webhooks

Set up real-time event notifications.

Verification Profiles

Learn about custom verification workflows.

Error Reference

Complete error code documentation.

Ready to integrate?

Get your API key and start building in minutes.

Get API Key View API Reference

Ready to get started?

Start with our free plan. No credit card required.

Start Free Trial Contact Sales

Verifications API

Verifications API

Overview

Create Verification

Request Body

Verification Profiles

Example Request

Response

Get Verification Status

Response

Verification Statuses

Verification Results

List Verifications

Query Parameters

Response

Get Verification Documents

Response

Retry Failed Verification

Delete Verification Data

Custom Verification Profiles

Webhooks

Error Handling

Rate Limits

Best Practices

Next Steps

Applicants API

Webhooks

Verification Profiles

Error Reference

Ready to integrate?

Ready to get started?

We value your privacy