Applicants API

Create and manage applicant records for identity verification, AML screening, and compliance workflows.

Applicants API

Applicants represent individuals or entities undergoing compliance checks. Create applicant records before starting verifications or AML screenings.

Overview

Applicants store:

Personal information (name, DOB, address)
Contact details (email, phone)
Verification history
AML screening results
Risk scores

0 Credits Creating applicants is free - credits consumed only when performing checks.

Create Applicant

POST/api/v3/applicants🔒 Auth Required0

Create a new applicant record

Create an applicant for verification or screening.

Request Body

Field	Type	Required	Description
`firstName`	string	Yes	First name (max 100 chars)
`lastName`	string	Yes	Last name (max 100 chars)
`email`	string	Yes	Email address (unique per organisation)
`dateOfBirth`	string	No	ISO 8601 date (YYYY-MM-DD)
`country`	string	No	ISO 3166-1 alpha-2 country code (e.g., GB, US)
`phone`	string	No	E.164 format (e.g., +44 7911 123456)
`address`	object	No	Address details
`nationality`	string	No	ISO 3166-1 alpha-2 code
`metadata`	object	No	Custom data (max 10 keys)

Address Object

Field	Type	Description
`street`	string	Street address
`city`	string	City
`postalCode`	string	Postal/ZIP code
`country`	string	ISO 3166-1 alpha-2 code

Example Request

const response = await fetch('https://api.veriplus.co.uk/api/v3/applicants', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    firstName: 'John',
    lastName: 'Doe',
    email: '[email protected]',
    dateOfBirth: '1990-01-15',
    country: 'GB',
    phone: '+44 7911 123456',
    address: {
      street: '123 High Street',
      city: 'London',
      postalCode: 'SW1A 1AA',
      country: 'GB'
    },
    nationality: 'GB',
    metadata: {
      customerId: 'cust_abc123',
      source: 'website'
    }
  })
});
 
const data = await response.json();
console.log('Applicant ID:', data.data.applicantId);

Response

{
  "success": true,
  "data": {
    "applicantId": "app_1234567890",
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "dateOfBirth": "1990-01-15",
    "country": "GB",
    "status": "ACTIVE",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Get Applicant

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

Retrieve applicant details

Retrieve full applicant details including verification history.

const applicantId = 'app_1234567890';
 
const response = await fetch(
  `https://api.veriplus.co.uk/api/v3/applicants/${applicantId}`,
  {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  }
);
 
const data = await response.json();
console.log('Applicant:', data.data);

Response

{
  "success": true,
  "data": {
    "applicantId": "app_1234567890",
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "dateOfBirth": "1990-01-15",
    "country": "GB",
    "phone": "+44 7911 123456",
    "address": {
      "street": "123 High Street",
      "city": "London",
      "postalCode": "SW1A 1AA",
      "country": "GB"
    },
    "nationality": "GB",
    "status": "ACTIVE",
    "riskScore": 15,
    "lastVerifiedAt": "2024-01-15T10:32:14Z",
    "metadata": {
      "customerId": "cust_abc123"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:32:14Z"
  }
}

List Applicants

GET/api/v3/applicants🔒 Auth Required0

List all applicants

Retrieve a paginated list of applicants.

Query Parameters

Parameter	Type	Description
`limit`	number	Results per page (default: 20, max: 100)
`cursor`	string	Pagination cursor
`status`	string	Filter by status (ACTIVE, SUSPENDED, ARCHIVED)
`country`	string	Filter by country code
`search`	string	Search by name or email
`createdFrom`	string	ISO 8601 date
`createdTo`	string	ISO 8601 date

const params = new URLSearchParams({
  status: 'ACTIVE',
  country: 'GB',
  limit: '50'
});
 
const response = await fetch(
  `https://api.veriplus.co.uk/api/v3/applicants?${params}`,
  {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  }
);
 
const data = await response.json();
console.log(`Found ${data.data.length} applicants`);

Response

{
  "success": true,
  "data": [
    {
      "applicantId": "app_123",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "status": "ACTIVE",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "xyz789",
    "total": 1234
  }
}

Update Applicant

PATCH/api/v3/applicants/:id🔒 Auth Required0

Update applicant information

Update applicant details. Only provided fields will be updated.

const response = await fetch(
  `https://api.veriplus.co.uk/api/v3/applicants/${applicantId}`,
  {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      phone: '+44 7911 654321',
      address: {
        street: '456 New Street',
        city: 'Manchester',
        postalCode: 'M1 1AA',
        country: 'GB'
      }
    })
  }
);
 
const data = await response.json();
console.log('Updated applicant:', data.data);

Delete Applicant

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

Archive applicant (soft delete)

Archive an applicant. Data is retained for compliance but applicant is hidden from lists.

Soft Delete

Applicants are archived, not permanently deleted. Use for GDPR "right to be forgotten" requests. Contact support for permanent deletion.

const response = await fetch(
  `https://api.veriplus.co.uk/api/v3/applicants/${applicantId}`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  }
);
 
if (response.ok) {
  console.log('Applicant archived');
}

Get Applicant Verification History

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

List all verifications for an applicant

Retrieve verification history for an applicant.

const response = await fetch(
  `https://api.veriplus.co.uk/api/v3/applicants/${applicantId}/verifications`,
  {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  }
);
 
const data = await response.json();
console.log('Verifications:', data.data);

Response

{
  "success": true,
  "data": [
    {
      "verificationId": "verif_abc123",
      "status": "COMPLETED",
      "result": "APPROVED",
      "profileType": "STANDARD",
      "createdAt": "2024-01-15T10:30:00Z",
      "completedAt": "2024-01-15T10:32:14Z"
    },
    {
      "verificationId": "verif_xyz789",
      "status": "COMPLETED",
      "result": "APPROVED",
      "profileType": "EXPRESS",
      "createdAt": "2024-01-10T14:20:00Z",
      "completedAt": "2024-01-10T14:21:30Z"
    }
  ]
}

Get Applicant AML History

GET/api/v3/applicants/:id/aml-screenings🔒 Auth Required0

List all AML screenings for an applicant

Retrieve AML screening history for an applicant.

const response = await fetch(
  `https://api.veriplus.co.uk/api/v3/applicants/${applicantId}/aml-screenings`,
  {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  }
);
 
const data = await response.json();
console.log('AML screenings:', data.data);

Response

{
  "success": true,
  "data": [
    {
      "screeningId": "aml_abc123",
      "status": "COMPLETED",
      "matches": 0,
      "riskLevel": "LOW",
      "categories": ["SANCTIONS", "PEP"],
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Applicant Risk Score

Each applicant has a risk score (0-100) calculated from:

Verification results
AML screening results
Country risk
Historical behaviour
Deepfake detection results

Score	Risk Level	Description
0-30	Low	Trustworthy, low fraud risk
31-60	Medium	Some risk factors present
61-80	High	Multiple risk factors
81-100	Very High	High fraud risk

Access risk score via /applicants/:id endpoint in riskScore field.

Duplicate Detection

VeriPlus automatically detects potential duplicate applicants based on:

Email address (must be unique)
Name + Date of Birth combination
Phone number

Error on duplicate email:

{
  "success": false,
  "error": {
    "code": "DUPLICATE_APPLICANT",
    "message": "An applicant with this email already exists",
    "details": {
      "existingApplicantId": "app_existing123"
    }
  }
}

Solution: Use existing applicant ID or update existing record.

Best Practices

Store Applicant IDs: Save applicant IDs in your database for future reference
Use Metadata: Link to your internal customer IDs via metadata field
Update Contact Info: Keep email/phone current for better results
Check Duplicates: Search before creating to avoid duplicates
Archive Inactive: Archive applicants who haven't been verified in 12+ months

Error Handling

Error Code	HTTP Status	Description	Solution
`APPLICANT_NOT_FOUND`	404	Applicant ID doesn't exist	Verify applicant ID
`DUPLICATE_APPLICANT`	409	Email already exists	Use existing applicant
`INVALID_EMAIL`	400	Email format invalid	Provide valid email
`INVALID_DATE_OF_BIRTH`	400	DOB format invalid	Use YYYY-MM-DD format
`INVALID_COUNTRY_CODE`	400	Unknown country code	Use ISO 3166-1 alpha-2

Next Steps

Verifications API

Start identity verification for applicants.

AML API

Screen applicants for sanctions and PEPs.

Webhooks

Receive real-time applicant updates.

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

Applicants API

Applicants API

Overview

Create Applicant

Request Body

Address Object

Example Request

Response

Get Applicant

Response

List Applicants

Query Parameters

Response

Update Applicant

Delete Applicant

Get Applicant Verification History

Response

Get Applicant AML History

Response

Applicant Risk Score

Duplicate Detection

Best Practices

Error Handling

Next Steps

Verifications API

AML API

Webhooks

Error Reference

Ready to integrate?

Ready to get started?

We value your privacy