Quickstart on VeraFi API

Overview

This guide provides details about the VeraFi APIs and related information, which is helpful to automate end-to-end identity verification workflows and integrate secure document, face, and liveness validation within your platform. The VeraFi API suite supports token-based authentication and offers endpoints for document upload, facial matching, liveness detection, and verification logging. Using these APIs, developers can easily connect verification steps, capture confidence scores, and record analytics for compliance and reporting. This section helps you set up authentication, test API endpoints, and build a working verification flow to start using VeraFi in your applications.

API Information

All API requests are made over HTTPS. The VeraFi API is exposed under the title:
VeraFi.Api
  • Protocol: HTTPS

  • Content Type:application/json (default); file uploads use multipart/form-data

Headers

Some endpoints require additional headers.
  • Authorization: Bearer <token> (recommended for all protected endpoints)
  • Accept: application/json
  • Note:
    A token query parameter is supported on a few endpoints, but prefer the Authorization header for consistency and security.
Authentication Endpoints
Endpoint Method Purpose Auth Required Request Body Success Response Error Response 
/auth/login
 POST Authenticate a user with password (or OTP flow) and return a session token. No 
{
"username_or_email": "string", 
"password": "string (hashed)",
"role": "string (optional)"
}

(or fields for OTP login as configured)

 200 OK → 
{ 
"token": "...", 
"user": { … },
"roles": [ … ] 
}
  • 400 invalid credentials
  • 429 too many attempts
  • 500 server error.
 
/auth/session
 GET Validate the session token and return user, tenant, and subscription snapshot. Yes Token in Authorization: Bearer <token> or supported ?token=... 200 OK → 
{ 
"user": { … },
"tenant": { … },
"subscription": { … }
 }
  • 401 invalid/expired token
  • 403 forbidden
  • 500 server error.
 
/auth/forgot-password
 POST Start password-reset by sending an OTP to the registered channel. No 
{ 
"email": "user@example.com" 
}
 200 OK → 
{ 
"message": "OTP sent" 
}
  • 404 user not found
  • 429 rate-limited
  • 500 server error.
 
/auth/reset-password
 POST Complete password reset using the received OTP. No 
{
"email": "user@example.com", 
"otp": "123456",
"new_password": "newpassword123"
}
200 OK → 
{
 "message": "Password updated"
 }
  • 400 invalid/expired OTP
  • 422 validation error
  • 500 server error.

1. Authenticate and Authorize

i. Login with Password

Using this API, you can authenticates the user by verifying credentials using a username/email and password combination. It returns a session token upon successful login.

Request Parameters

The following are the request parameters for POST/auth/login:
Field Data Type Required Description 
username_or_email
 String Yes Username or registered email address of the user. 
password
 String Yes Password associated with the account. 
role
 String No (Optional) Specific role to validate during authentication (e.g., admin, operator).

Method: POST

URL: https://verafi.duckdns.org/auth/login

Request Body
{
 "username_or_email": "john@example.com", 
 "password": "securepassword123",
 "role": ["admin", "operator"]
}

Response Parameters

The following are the response parameters for POST/auth/login:
Field Data Type Description 
user_id
 Integer Unique identifier of the authenticated user. 
name
 String Full name of the authenticated user. 
username
 String Username of the user. 
email
 String Registered email address of the user. 
roles
 Array of String List of roles assigned to the user (e.g., admin, operator). 
token
 String Session token (UUID) generated for subsequent authenticated requests.
Response
{
 "user_id": 1,
 "name": "John Doe",
 "username": "johndoe",
 "email": "john@example.com",
 "roles": ["admin", "operator"], 
 "token": "uuid-token-string"
}
Note:
  • The password is verified against the bcrypt hash stored in the database for secure authentication.
  • The role parameter is optional. When provided, the system validates that the user possesses the specified role.
  • A session token is returned upon successful login. This token must be included in the authorization header for all subsequent authenticated API requests.

ii. Login with One Time Password (OTP)

This API enables you to authenticates a user using a One-Time Password (OTP) sent to their registered email or mobile number and it returns a session token upon successful verification.

Request Parameters

The following are the request parameters for POST/auth/login:
Field Data Type Required Description 
username_or_email
 String Yes Username or registered email address of the user. 
otp
 String Yes One-Time Password (OTP) provided to the user for verification. 
role
 String No (Optional) Specific role to validate during authentication (e.g., admin, operator).

Method: POST

URL: https://verafi.duckdns.org/auth/login

Request Body
{
 "username_or_email": "john@example.com", 
 "otp": "123456",
 "role": ["admin", "operator"]
}

Response Parameters

The following are the response parameters for POST/auth/login:
Field Data Type Description 
user_id
 Integer Unique identifier of the authenticated user. 
name
 String Full name of the authenticated user. 
username
 String Username of the user. 
email
 String Registered email address of the user. 
roles
 Array of String List of roles assigned to the user (e.g., admin, operator). 
token
 String Session token (UUID) generated for subsequent authenticated requests.
Response
{
 "user_id": 1,
 "name": "John Doe",
 "username": "johndoe",
 "email": "john@example.com",
 "roles": ["admin", "operator"], 
 "token": "uuid-token-string"
}
Note:
  • The OTP must be valid and not expired. Each OTP has a 5-minute expiry window.
  • The OTP is consumed and becomes invalid immediately after successful verification.

iii. Send OTP for Login

Using this API, you can send a One-Time Password (OTP) to the user’s registered email address to initiate the authentication process.

Request Parameters

The following are the request parameters for POST/auth/send-otp:
Field Data Type Required Description 
username_or_email
 String Yes Username or registered email address of the user requesting OTP-based login.

Method: POST

URL: https://verafi.duckdns.org/auth/send-otp

Request Body
{
 "username_or_email": "john@example.com"
}

Response Parameters

The following are the response parameters for POST/auth/send-otp:
Field Data Type Description 
message
 String Confirms that the OTP has been successfully sent to the user’s registered email.
Response
{
 "message": "OTP sent to email"
}
Note:
  • The OTP is sent via the configured Gmail sender account.
  • Each OTP is valid for 5 minutes from the time of generation.
  • The endpoint is rate limited that the users can request a new OTP only once every 2 minutes.

iv. Verify the OTP

This API enables you to validate the OTP provided by the user and return an authentication token upon successful verification.

Request Parameters

The following are the request parameters for POST/auth/verify-otp:
Field Data Type Required Description 
username_or_email
 String Yes Username or registered email address of the user. 
otp
 String Yes One-Time Password (OTP) sent to the user for verification.

Method: POST

URL: https://verafi.duckdns.org/auth/verify-otp

Request Body
{
 "username_or_email": "john@example.com",
 "otp": "123456"
}

Response Parameters

The following are the response parameters for POST/auth/verify-otp:
Field Data Type Description 
user_id
 Integer Unique identifier of the authenticated user. 
name
 String Full name of the authenticated user. 
username
 String Username of the user. 
email
 String Registered email address of the user. 
roles
 Array of String List of roles assigned to the user (e.g., admin, operator). 
token
 String Session token (UUID) generated for subsequent authenticated requests.
Response
{
 "user_id": 1,
 "name": "John Doe",
 "username": "johndoe",
 "email": "john@example.com",
 "roles": ["admin", "operator"], 
 "token": "uuid-token-string"
}

v. Initiate Password Reset

This API enables you to initiate the password reset process by sending a One-Time Password (OTP) to the user’s registered email address for verification.

Request Parameters

The following are the request parameters for POST/auth/forgot-password:
Field Data Type Required Description 
email
 String Yes Registered email address of the user requesting a password reset.

Method: POST

URL: https://verafi.duckdns.org/auth/forgot-password

Request Body
{
 "email": "user@example.com"
}

Response Parameters

The following are the response parameters for POST/auth/forgot-password:
Field Data Type Description 
message
 String Confirms that the OTP has been successfully sent to the user’s registered email.
Response
{
 "message": "OTP sent to email"
}

vi. Reset the Password

This API enables you to reset the user’s password after verifying the One-Time Password (OTP).

Request Parameters

The following are the request parameters for POST/auth/reset-password:
Field Data Type Required Description 
email
 String Yes Registered email address of the user requesting the password reset. 
otp
 String Yes One-Time Password (OTP) received by the user for verification. 
new_password
 String Yes The new password to be set for the user account. Must meet password policy requirements.

Method: POST

URL: https://verafi.duckdns.org/auth/reset-password

Request Body
{
 "email": "user@example.com", 
 "otp": "123456",
 "new_password": "newpassword123"
}

Response Parameters

The following are the response parameters for POST/auth/reset-password:
Field Data Type Description 
message
 String Indicates the result of the password reset operation.
Response
{
 "message": "Password reset successful"
}
Note:
  • The new password is hashed using bcrypt before being stored in the system for enhanced security.
  • The OTP is consumed and becomes invalid immediately after a successful password reset.
  • If the OTP is invalid or expired, the request returns an error message (e.g., “Invalid or expired OTP”).

vii. Validate Session and Retrieve User Details

This API enables you to validate the session token and retrieves detailed user and subscription information.

Response Parameters

The following are the response parameters for GET /auth/session?token={token}:
Field Data Type Description 
user_id
 Integer Unique identifier of the user. 
name
 String Full name of the user. 
username
 String Username used for authentication. 
email
 String Registered email address of the user. 
roles
 Array of String List of roles assigned to the user (e.g., admin, user). 
tenant_id
 Integer Unique identifier of the tenant or organization the user belongs to. 
tenant_name
 String Name of the tenant or organization. 
subscription_tier
 String Type of subscription plan (e.g., Premium, Basic). 
subscription_service
 String Name of the service associated with the subscription (e.g., ID Verification). 
max_reports
 Integer Maximum number of reports allowed under the subscription. 
reports_used
 Integer Number of reports already used by the user. 
subscription_start_date
 String (ISO 8601) Start date and time of the subscription period. 
subscription_end_date
 String (ISO 8601) End date and time of the subscription period. 
days_remaining
 Integer Number of days left until the subscription expires. 
monthly_price
 Number Monthly subscription cost. 
subscription_status
 String Current status of the subscription. Possible values: - active: More than 7 days remaining - expiring_soon: 1–7 days remaining - expired: Past end date
Response
{
 "user_id": 1,
 "name": "John Doe",
 "username": "johndoe",
 "email": "john@example.com", 
 "roles": ["admin"],
 "tenant_id": 1,
 "tenant_name": "Acme Corp",
 "subscription_tier": "Premium",
 "subscription_service": "ID Verification", 
 "max_reports": 1000,
 "reports_used": 150,
 "subscription_start_date": "2024-01-01T00:00:00Z", 
 "subscription_end_date": "2024-12-31T23:59:59Z", 
 "days_remaining": 300,
 "monthly_price": 99.99,
 "subscription_status": "active"
}
Note:
Subscription Status Values
The subscription_status field indicates the current state of the user’s active subscription based on the remaining validity period:
Value Description
active The subscription is valid with more than 7 days remaining before expiry.
expiring_soon The subscription is approaching expiry, with 1 to 7 days remaining.
expired The subscription period has ended, and renewal is required to continue using the service.

2. Manage Users

i. Add a New User

Using this API, you can register a new user account in the system.

Request Parameters

The following are the request parameters for POST /users/:
Field Data Type Required Description 
email
 String Yes Registered email address for the new user account. Must be unique. 
password
 String Yes Password for the new account. Must meet password policy requirements.

Method: POST

URL: https://verafi.duckdns.org/users/

Request Body
{
 "email": "user@example.com",
 "password": "securepassword123"
}

Response Parameters

The following are the response parameters for POST /users/:
Field Data Type Description 
id
 Integer Unique identifier of the newly created user. 
email
 String Registered email address of the user. 
full_name
 String / Null Full name of the user (if provided during registration). 
is_active
 Boolean Indicates whether the user account is active. 
is_superuser
 Boolean Indicates whether the user has administrative privileges. 
created_at
 String (ISO 8601) Date and time when the user account was created.
Response
{
 "id": 1,
 "email": "user@example.com", 
 "full_name": null,
 "is_active": true,
 "is_superuser": false,
 "created_at": "2024-01-01T00:00:00Z"
}
Note:
  • Passwords are hashed using bcrypt before storage to ensure security.
  • Duplicate email addresses are not allowed; the API will return an error if the email already exists.
  • Newly created accounts are active by default but may require email verification depending on configuration.

ii. Retrieve User Details by Id

Using this API, you can retrieve detailed information for a specific user using their unique identifier.

Request Parameters

The following are the request parameters for GET/users/{user_id}:
Field Data Type Location Required Description 
user_id
 Integer Path Yes Unique identifier of the user whose details you want to retrieve.

Method: GET

URL: https://verafi.duckdns.org/users/%7Buser_id%7D

Request Body
GET /users/{user_id}

Response Parameters

The following are the response parameters for GET /users/{user_id}:
Field Data Type Description 
id
 Integer Unique identifier of the user. 
email
 String Registered email address of the user. 
full_name
 String Full name of the user. 
is_active
 Boolean Indicates whether the user account is active. 
is_superuser
 Boolean Indicates whether the user has administrative privileges. 
created_at
 String (ISO 8601) Date and time when the user account was created.
Response
{
 "id": 1,
 "email": "user@example.com", 
 "full_name": "John Doe",
 "is_active": true,
 "is_superuser": false,
 "created_at": "2024-01-01T00:00:00Z"
}
Note:
  • Requires a valid authentication token in the request header.
  • If the user_id does not exist, the API returns a 404 Not Found error.
  • Access to user information may be restricted based on role-based permissions.

iii. View All User Details

This API enables you to retrieve a paginated list of all registered user accounts with their details.

Request Parameters

The following are the request parameters for GET /users/?skip=0&limit=100:
Field Data Type Required Default Description
skip Integer No 0 Number of user records to skip before starting to return results. This is used for pagination.
limit Integer No 100 Maximum number of user records to return in the response.

Method: GET

URL: https://verafi.duckdns.org/users/?skip=0&limit=100

Request Body
GET /users/?skip=0&limit=100
Field Data Type Required Default Description
skip Integer No 0 Number of user records to skip before starting to return results. This is used for pagination.
limit Integer No 100 Maximum number of user records to return in the response.

Response Parameters

The following are the response parameters for GET /users/?skip=0&limit=100:
Field Data Type Description 
id
 Integer Unique identifier of the user. 
email
 String Registered email address of the user. 
full_name
 String Full name of the user. 
is_active
 Boolean Indicates whether the user account is active. 
is_superuser
 Boolean Indicates whether the user has administrative privileges. 
created_at
 String (ISO 8601) Date and time when the user account was created.
Response
[
 {
  "id": 1,
  "email": "user1@example.com", 
  "full_name": "John Doe",
  "is_active": true,
  "is_superuser": false,
  "created_at": "2024-01-01T00:00:00Z"
 },
 {
 "id": 2,
 "email": "user2@example.com", 
 "full_name": "Jane Smith",
 "is_active": true,
 "is_superuser": false,
 "created_at": "2024-01-02T00:00:00Z"
 }
]
Note:
  • Requires a valid authentication token in the request header.
  • Results are paginated using skip and limit parameters.
  • The API is typically accessible only to users with administrative privileges or elevated roles.

iv. Update User Account Details

This API allows you to update an existing user’s account information and settings.

Request Parameters

The following are the request parameters for PUT /users/{user_id}:
Field Data Type Required Description 
email
 String No Updated email address of the user. Must be unique if changed. 
full_name
 String No Updated full name of the user. 
is_active
 Boolean No Indicates whether the user account should be active or inactive.

Method: PUT

URL: https://verafi.duckdns.org/users/%7Buser_id%7D

Request Body
{
 "email": "newemail@example.com", 
 "full_name": "John Smith",
 "is_active": true
}

Response Parameters

The following are the response parameters for PUT /users/{user_id}:
Field Data Type Description 
id
 Integer Unique identifier of the updated user. 
email
 String Updated email address of the user. 
full_name
 String Updated full name of the user. 
is_active
 Boolean Indicates whether the user account is active. 
is_superuser
 Boolean Indicates whether the user has administrative privileges. 
created_at
 String (ISO 8601) Date and time when the user account was originally created.
Response
{
 "id": 1,
 "email": "newemail@example.com", 
 "full_name": "John Smith",
 "is_active": true,
 "is_superuser": false,
 "created_at": "2024-01-01T00:00:00Z"
}
Note:
  • Requires a valid authentication token with sufficient privileges to modify user accounts.
  • Only editable fields (email, full_name, is_active) should be included in the request body.
  • The API will return a 400 Bad Request error if validation fails or a 404 Not Found if the user_id does not exist.

v. Remove User Account Details

Using this API, you can permanently delete a user account from the system.

Request Parameters

The following are the request parameters for DELETE /users/{user_id}:
Field Data Type Location Required Description 
user_id
 Integer Path Yes Unique identifier of the user account to be permanently deleted.

Method: DELETE

URL: https://verafi.duckdns.org/users/%7Buser_id%7D

Request Body
DELETE/users/{user_id}

Response Parameters

The following are the response parameters for DELETE /users/{user_id}:
Field Data Type Description 
message
 String Confirms that the user has been successfully deleted.
Response
{
 "message": "User deleted successfully"
}

3. Manage Document Types

i. View All Document Types

Using this API, you can retrieve a paginated list of all available document types supported for identity verification processing.

Request Parameters

The following are the response parameters for GET /document-types/?skip=0&limit=100:
Field Data Type Required Default Description
skip Integer No 0 Number of document type records to skip before returning results. Used for pagination.
limit Integer No 100 Maximum number of document type records to return in the response.

Method: GET

URL: https://verafi.duckdns.org/document-types/?skip=0&limit=100

Request Body
GET /document-types/?skip=0&limit=100

Response Parameters

The following are the response parameters for GET /document-types/?skip=0&limit=100:
Field Data Type Description 
Id
 Integer Unique identifier of the document type. 
DocumentType
 String Name of the document type available for verification. 
Description
 String Description of the document type and its verification purpose.
Response
[
 {
  "Id": 1,
  "DocumentType": "Driver License",
  "Description": "US Driver License verification"
 },
{
 "Id": 2,
 "DocumentType": "Passport",
 "Description": "International Passport verification"
 }
]

ii. Retrieve Document Type by Id

This API enables you to retrieve detailed specifications, metadata, and configuration information for a specific document type used in verification processes.

Request Parameters

The following are the request parameters for GET/document-types/{document_type_id}:
Field Data Type Required Description 
document_type_id
 Integer Yes Unique identifier of the document type to retrieve.

Method: GET

URL: https://verafi.duckdns.org/document-types/%7Bdocument_type_id%7D

Request Body
GET/document-types/{document_type_id}

Response Parameters

The following are the response parameters for GET/document-types/{document_type_id}:
Field Data Type Description 
Id
 Integer Unique identifier of the document type. 
DocumentType
 String Name of the document type (e.g., Driver License, Passport). 
Description
 String Description of the document type and its verification purpose. 
ExpectedJson
 String JSON schema or expected structure for the document’s verification payload. 
CreatedBy
 String Name of the user or system that created the document type record. 
CreatedOn
 String (ISO 8601) Date and time when the document type record was created. 
LastModifiedBy
 String Name of the user who last modified the document type record. 
LastModifiedOn
 String (ISO 8601) Date and time when the document type record was last updated. 
isActive
 Boolean Indicates whether the document type is currently active and available for use. 
VerticalThresholdScore
 Integer Minimum acceptable score for verification threshold within a vertical or category.
Response
{
  "Id": 1,
  "DocumentType": "Driver License",
  "Description": "US Driver License verification", 
  "ExpectedJson": "{}",
  "CreatedBy": "system",
  "CreatedOn": "2024-01-01T00:00:00Z",
  "LastModifiedBy": "admin",
  "LastModifiedOn": "2024-01-15T00:00:00Z",
  "isActive": true,
  "VerticalThresholdScore": 80
}

iii. Retrieve Document Type by Name

With this API, you can retrieve detailed specifications and metadata for a specific document type using its name as the identifier.

Request Parameters

The following are the request parameters for GET/document-types/by-name/{document_type_name}:
Field Data Type Required Description 
document_type_name
 String Yes The unique name of the document type to retrieve. This value is used to look up and return the document type’s metadata and specifications.

Method: GET

URL: https://verafi.duckdns.org/document-types/by-name/%7Bdocument_type_name%7D

Request Body
GET/document-types/by-name/{document_type_name}

Response Parameters

The following are the response parameters for GET/document-types/by-name/{document_type_name}:
Field Data Type Description 
Id
 Integer Unique identifier of the document type. 
DocumentType
 String Name of the document type. 
Description
 String Description of the document type and its verification purpose. 
ExpectedJson
 String JSON schema or expected payload format for verification. 
CreatedBy
 String Name of the user or system that created the document type record. 
CreatedOn
 String (ISO 8601) Date and time when the document type record was created. 
LastModifiedBy
 String Name of the user who last modified the document type record. 
LastModifiedOn
 String (ISO 8601) Date and time when the record was last updated. 
isActive
 Boolean Indicates whether the document type is currently active. 
VerticalThresholdScore
 Integer Minimum verification threshold score for the document type.
Response
{
 "Id": 1,
 "DocumentType": "Driver License",
 "Description": "US Driver License verification", 
 "ExpectedJson": "{}",
 "CreatedBy": "system",
 "CreatedOn": "2024-01-01T00:00:00Z",
 "LastModifiedBy": "admin",
 "LastModifiedOn": "2024-01-15T00:00:00Z",
 "isActive": true,
 "VerticalThresholdScore": 80
}

4. Manage Document Details

i. View Document Details

This API enables you to retrieve detailed field definitions, display labels, and validation criteria for a specific document type.

Request Parameters

The following are the request parameters for GET/document-detail?document_type=1:
Field Data Type Required Description
document_type Integer Yes The ID of the document type (e.g., 1–4) for which detailed field specifications are requested.

Method: GET

URL: https://verafi.duckdns.org/document-detail?document_type=1

Request Body
GET/document-detail?document_type=1

Response Parameters

The following are the response parameters for GET/document-detail?document_type=1:
Field Data Type Description 
Id
 Integer Unique identifier of the document field. 
DocId
 Integer Identifier linking the field to its parent document type. 
FieldKey
 String System key or internal name representing the document field. 
FieldLabelToDisplay
 String Display name or label for the field (user-facing). 
isCritical
 Boolean Indicates whether the field is critical for verification. 
Weightage
 Integer Numeric value representing the importance or contribution of the field to the overall verification score.
Response
[
 {
  "Id": 1,
  "DocId": 1,
  "FieldKey": "name",
  "FieldLabelToDisplay": "Full Name", 
  "isCritical": true,
  "Weightage": 85
 }
]

ii. Update the Critical Field Status

Using this API, you can update the critical status (isCritical) of a specific field within a document type to indicate its importance in the verification process.

Request Parameters

The following are the request parameters for POST/document-detail:
Field Data Type Required Description 
Id
 Integer Yes Unique identifier of the document field to be updated. 
isCritical
 Boolean Yes Updated critical status value. Set to true to mark the field as critical or false to remove critical designation.

Method: POST

URL: https://verafi.duckdns.org/document-detail

Request Body
{
 "Id": 1,
 "isCritical": true
}

Response Parameters

The following are the response parameters for POST/document-detail:
Field Data Type Description 
Id
 Integer Unique identifier of the document field. 
DocId
 Integer Identifier linking the field to its parent document type. 
FieldKey
 String Internal key name of the field. 
FieldLabelToDisplay
 String Display label or user-facing name of the field. 
isCritical
 Boolean Indicates the updated critical status of the field. 
Weightage
 Integer Weight or score contribution of the field in the verification process.
Response
{
 "Id": 1,
 "DocId": 1,
 "FieldKey": "name",
 "FieldLabelToDisplay": "Full Name", 
 "isCritical": true,
 "Weightage": 85
}

iii. Rename the Field Label

This API enables you to update the display label of a document field to modify how it appears in user interfaces and verification reports.

Request Parameters

The following are the request parameters for POST/document-detail/rename:
Field Data Type Required Description 
Id
 Integer Yes Unique identifier of the document field to be renamed. 
NewFieldToDisplay
 String Yes New display label to be used for the field.

Method: POST

URL: https://verafi.duckdns.org/document-detail/rename

Request Body
{
 "Id": 1,
 "NewFieldToDisplay": "Customer Full Name"
}

Response Parameters

The following are the response parameters for POST/document-detail/rename:
Field Data Type Description 
Id
 Integer Unique identifier of the document field. 
DocId
 Integer Identifier linking the field to its parent document type. 
FieldKey
 String Internal key name of the field (system reference). 
FieldLabelToDisplay
 String Updated display label or user-facing name for the field. 
isCritical
 Boolean Indicates whether the field is marked as critical for verification. 
Weightage
 Integer Weight or scoring value assigned to the field.
Response
{
 "Id": 1,
 "DocId": 1,
 "FieldKey": "name",
 "FieldLabelToDisplay": "Customer Full Name", 
 "isCritical": true,
 "Weightage": 85
}
Note:
  • Requires a valid authentication token and edit permissions for document configurations.
  • The field’s system key (FieldKey) remains unchanged only the display name is modified.
  • Updating the display label affects all user interfaces, reports, and APIs referencing this field.
  • Returns a 404 Not Found error if the specified field Id does not exist.

5. Manage Critical Fields and Configuration

i. View All Critical Fields

Using this API, you can retrieve all fields marked as critical for a specified document type, along with their display labels and weightage values.

Request Parameters

The following are the request parameters for POST/displaycriticalfield:
Field Data Type Required Description 
documentType
 String Yes Name of the document type (e.g., Driver License, Passport) for which critical fields are to be retrieved.

Method: POST

URL: https://verafi.duckdns.org/displaycriticalfield

Request Body
{
"documentType": "Driver License"
}

Response Parameters

The following are the response parameters for POST/displaycriticalfield:
Field Data Type Description 
status
 String Indicates the success or failure of the request (e.g., "success"). 
documentType
 String Name of the document type for which the critical fields were retrieved. 
data
 Array of Object List of fields designated as critical for the specified document type. 
data[].FieldKey
 String Internal key name of the field. 
data[].FieldLabelToDisplay
 String Display label or user-facing name for the field. 
data[].Weightage
 Integer Weight or scoring value assigned to the field. 
count
 Integer Total number of critical fields returned.
Response
{
 "status": "success",
 "documentType": "Driver License", 
 "data": [
  {
   "FieldKey": "name",
   "FieldLabelToDisplay": "Full Name",  
   "Weightage": 85
  }
 ],
 "count": 1
}
Note:
  • Useful for identifying high-priority verification fields within a document type.
  • The Weightage value reflects the relative importance of each field in scoring or verification.
  • Returns an empty data array and count: 0 if no critical fields exist for the specified document type.

ii. Retrieve the Confidence Color Codes

Using this API, you can retrieve the color-coding configuration for confidence levels used in visual indicators (e.g., dashboards, verification UI components).

Method: POST

URL: https://verafi.duckdns.org/fetchconfidencecode

Request Body
GET/fetchconfidencecode

Response Parameters

The following are the response parameters for GET/fetchconfidencecode:
Field Data Type Description 
status
 String Indicates the result of the API call (e.g., "success"). 
data
 Array of Object List of configured confidence level color mappings. 
data[].fromconfidence
 Integer Lower boundary of the confidence score range. 
data[].toconfidence
 Integer Upper boundary of the confidence score range. 
data[].colorcodetailwind
 String Tailwind CSS color class used for UI border or background styling. 
data[].colorcode_hex
 String Hexadecimal color value representing the confidence range. 
data[].hoverDescription
 String Tooltip or descriptive text displayed on hover for the confidence level. 
count
 Integer Total number of configured confidence color ranges.
Response
{
 "status": "success", 
 "data": [
  {
   "fromconfidence": 0,
   "toconfidence": 50,
   "colorcodetailwind": "border-red-500", 
   "colorcode_hex": "#ef4444",
"hoverDescription": "Low confidence"
  }
],
"count": 3
}
Note:
  • Each range defines visual thresholds for representing confidence scores (e.g., low, medium, high).
  • The colorcodetailwind value is intended for frontend frameworks using Tailwind CSS classes.
  • The count value reflects the total number of configured confidence ranges in the system.

6. Manage Verification Logs

i. Create a New Verification Log

This API enables you to create a new verification log entry to record all verification activities and outcomes for a given document session.

Request Parameters

The following are the request parameters for POST/insert-logs:
Field Data Type Required Description 
SessionID
 String (UUID) No Optional session identifier. If not provided, a new UUID is auto-generated. 
DocumentTypeID
 String Yes Unique identifier of the document type associated with the verification. 
ExtractedName
 String No Name extracted from the submitted document. 
ExtractedDocNumber
 String No Document number extracted from the verification process. 
ExtractedInfoJson
 String (JSON) No JSON structure containing extracted metadata or OCR details from the document. 
DocumentVerification
 Boolean No Indicates whether the document verification process passed successfully. 
LivenessVerification
 Boolean No Indicates whether liveness detection verification passed successfully. 
PhotoVerification
 Boolean No Indicates whether facial photo matching was verified successfully. 
PhraseVerification
 Boolean No Indicates whether phrase-based verification was performed successfully. 
PhoneVerification
 Boolean No Indicates whether phone number verification was successful. 
EmailVerification
 Boolean No Indicates whether email address verification was successful. 
FaceSnapshotsJson
 String (JSON) No JSON object containing face snapshot metadata captured during verification. 
FinalVerification
 Boolean Yes Final decision indicating whether the overall verification was successful. 
UserID
 Integer Yes Identifier of the user who initiated or owns the verification session.

Method: POST

URL: https://verafi.duckdns.org/insert-logs

Request Body
{
 "SessionID": "optional-session-uuid", 
 "DocumentTypeID": "1",
 "ExtractedName": "John Doe",
 "ExtractedDocNumber": "D123456789", 
 "ExtractedInfoJson": "{}",
 "DocumentVerification": true, 
 "LivenessVerification": true, 
 "PhotoVerification": true,
 "PhraseVerification": false, 
 "PhoneVerification": true,
 "EmailVerification": false, 
 "FaceSnapshotsJson": "{}", 
 "FinalVerification": true, 
 "UserID": 1
}

Response Parameters

The following are the response parameters for POST/insert-logs:
Field Data Type Description 
Id
 Integer Unique identifier for the newly created verification log. 
SessionID
 String (UUID) Session identifier associated with the verification. 
DocumentTypeID
 String Identifier of the document type verified. 
ExtractedName
 String Name extracted from the document. 
ExtractedDocNumber
 String Extracted document number. 
ExtractedInfoJson
 String (JSON) JSON structure containing extracted data. 
DocumentVerification
 Boolean Result of the document verification process. 
LivenessVerification
 Boolean Result of the liveness verification process. 
PhotoVerification
 Boolean Result of photo verification. 
PhraseVerification
 Boolean Result of phrase verification. 
PhoneVerification
 Boolean Result of phone verification. 
EmailVerification
 Boolean Result of email verification. 
FaceSnapshotsJson
 String (JSON) JSON object containing face snapshot metadata. 
FinalVerification
 Boolean Final status indicating whether the verification process passed. 
UserID
 Integer Identifier of the user who created the log entry. 
CreatedOn
 String (ISO 8601) Timestamp when the log entry was created. 
LastModifiedOn
 String (ISO 8601) Timestamp of the most recent modification. 
IsActive
 Boolean Indicates whether the log entry is currently active.
Response
{
 "Id": 1,
 "SessionID": "550e8400-e29b-41d4-a716-446655440000",
 "DocumentTypeID": "1",
 "ExtractedName": "John Doe",
 "ExtractedDocNumber": "D123456789", 
 "ExtractedInfoJson": "{}",
 "DocumentVerification": true, 
 "LivenessVerification": true, 
 "PhotoVerification": true,
 "PhraseVerification": false, 
 "PhoneVerification": true,
 "EmailVerification": false, 
 "FaceSnapshotsJson": "{}", 
 "FinalVerification": true, 
 "UserID": 1,
 "CreatedOn": "2024-10-16T10:00:00Z",
 "LastModifiedOn": "2024-10-16T10:00:00Z",
 "IsActive": true
}
Note:
  • SessionID is auto-generated if not provided in the request.
  • CreatedOn and LastModifiedOn timestamps are automatically assigned by the system.
  • All boolean verification flags (DocumentVerification, PhotoVerification, etc.) are optional but useful for granular tracking of verification components.
  • This endpoint helps in maintaining audit trails and verification logs for compliance and reporting.

ii. Retrieve Verification Logs Using Filter

Using this API, you can retrieve verification logs with filtering, sorting, and pagination.

Request Parameters

The following are the response parameters for GET/retrieve-logs:
Field Data Type Required Default Notes 
token
 String Yes — Authentication token. 
skip
 Integer No 0 Number of records to skip (pagination offset). 
limit
 Integer No 50 Page size. Max 1000. 
document_type_id
 String / Integer No — Filter logs by document type. 
user_id
 Integer No — Filter logs by user ID. 
start_date
 String (YYYY-MM-DD) No — Inclusive start of date range (compares against CreatedOn). 
end_date
 String (YYYY-MM-DD) No — Inclusive end of date range. 
sort_by
 String No CreatedOn Sort field (e.g., CreatedOn, FinalVerification, etc.). 
sort_order
 String No desc asc or desc.

Method: GET

URL: https://verafi.duckdns.org/retrieve-logs

Request Body
GET/retrieve-logs

Response Parameters

The following are the response parameters for GET/retrieve-logs:
Field Data Type Description 
Id
 Integer Unique identifier of the verification log. 
SessionID
 String (UUID) Session identifier for the verification flow. 
DocumentTypeID
 String Document type ID associated with the log. 
ExtractedName
 String Name extracted from the document, if available. 
DocumentVerification
 Boolean Result of document verification. 
FinalVerification
 Boolean Overall verification decision. 
CreatedOn
 String (ISO 8601) Creation timestamp of the log entry. 
tenant_name
 String Tenant/organization name associated with the log. 
tenant_id
 Integer Tenant/organization ID.
Response
[
{
 "Id": 1,
 "SessionID": "uuid-string", 
 "DocumentTypeID": "1",
 "ExtractedName": "John Doe", 
 "DocumentVerification": true, 
 "FinalVerification": true,
 "CreatedOn": "2024-01-01T12:00:00Z",
 "tenant_name": "Acme Corp", 
 "tenant_id": 1
 }
]
Table 1. Access Control
Role Scope
Product Owner Can view all logs from all tenants.
Admin Can view logs from their tenant only.
Operator Can view logs from their tenant only.
Note:
  • Use skip and limit to paginate; limit is capped at 1000.
  • When both start_date and end_date are supplied, results are filtered inclusively on CreatedOn.
  • Defaults to sort_by=CreatedOn&sort_order=desc.
  • Returns an empty array [] if no logs match the filters.
  • Requests with invalid dates or out-of-range limit may return 400 Bad Request.

iii. Retrieve the Log Count

With this API, you can retrieve the total number of verification logs available, optionally filtered by the same parameters used in /retrieve-logs. This endpoint supports pagination and analytics.

Request Parameters

The following are the request parameters for GET/retrieve-logs-count:
Field Data Type Required Default Description 
token
 String Yes — Authentication token. 
document_type_id
 String / Integer No — Filter logs by document type. 
user_id
 Integer No — Filter logs by user ID. 
start_date
 String (YYYY-MM-DD) No — Start date for filtering (inclusive). 
end_date
 String (YYYY-MM-DD) No — End date for filtering (inclusive). 
tenant_id
 Integer No — Filter logs by tenant (available to Product Owner and Admin roles only).

Method: GET

URL: https://verafi.duckdns.org/retrieve-logs-count

Request Body
GET/retrieve-logs-count

Response Parameters

The following are the response parameters for GET/retrieve-logs-count:
Field Data Type Description 
total_count
 Integer Total number of verification logs that match the applied filters.
Response
{
 "total_count": 1250
}

iv. View Verification Count for a User

Using this API, you can retrieve the total number of verifications completed by a specific user within a defined date range.

Request Parameters

The following are the request parameters for GET/user-verification-count:
Field Data Type Required Description 
user_id
 Integer Yes Unique identifier of the user whose verification count is to be retrieved. 
start_date
 String (YYYY-MM-DD) No Start date for the reporting period (inclusive). 
end_date
 String (YYYY-MM-DD) No End date for the reporting period (inclusive). 
token
 String Yes Authentication token to validate user access.

Method: GET

URL: https://verafi.duckdns.org/user-verification-count

Request Body
GET/user-verification-count

Response Parameters

The following are the response parameters for GET/user-verification-count:
Field Data Type Description 
user_id
 Integer Unique identifier of the user for whom the statistics are retrieved. 
verification_count
 Integer Total number of verifications performed by the user within the specified date range.
Response
{
"user_id": 1,
"verification_count": 45
}
Table 2. Access Control
Role Scope
Product Owner Can view verification counts for any user.
Admin / Operator / Standard User Can view only their own verification count.
Note:
  • If start_date and end_date are not provided, the API returns the lifetime verification count for the user.
  • Date filtering is inclusive of both boundaries.
  • Returns 0 for verification_count if no verifications were found in the specified period.
  • Returns a 403 Forbidden error if a user attempts to view another user’s count without sufficient permissions.

7. Manage Verification Configuration

i. Retrieve Verification Configuration

Using this API, you can retrieve the current system configuration settings and verification parameters that control various stages of the verification workflow.

Request Parameters

The following are the request parameters for GET/verification-config:
Field Data Type Required Description
None — — This API does not require any request parameters.

Method: GET

URL: https://verafi.duckdns.org/verification-config

Request Body
GET/verification-config

Response Parameters

The following are the response parameters for GET/verification-config:
Field Data Type Description 
success
 Boolean Indicates whether the request was successful. 
message
 String Descriptive message indicating the status of the request. 
data
 Object Contains the configuration settings for verification features. 
data.<SettingKey>
 Object Each configuration key represents a feature toggle or parameter. 
data.<SettingKey>.value
 Boolean Indicates whether the feature is enabled (true) or disabled (false). 
data.<SettingKey>.description
 String Description of the corresponding configuration setting.
Response
{
 "success": true,
 "message": "Verification configuration retrieved successfully", 
 "data": {
  "ENABLE_DOCUMENT_UPLOAD": {
   "value": true,
   "description": "Enable document upload functionality"
  },
  "ENABLE_LIVENESS_CHECK": {
   "value": true,
   "description": "Enable liveness detection"
  },
 "ENABLE_VIDEO_FACE": {
  "value": true,
  "description": "Enable video face capture"
 },
 "ENABLE_LIVE_PHRASE": {
  "value": true,
  "description": "Enable live phrase verification"
 },
 "ENABLE_FACE_MATCH": {
  "value": true,
  "description": "Enable face matching"
 },
 "ENABLE_OTP_VERIFICATION": {
  "value": true,
  "description": "Enable OTP verification"
 },
 "ENABLE_EMAIL_VERIFICATION": {
  "value": true,
  "description": "Enable email verification"
 },
 "ENABLE_CRITICAL_FIELDS_CHECK": {
  "value": true,
  "description": "Enable critical fields validation"
 },
 "ENABLE_PHRASE_VERIFICATION": {
  "value": true,
  "description": "Enable phrase verification"
  }
 }
}
Note:
  • The returned configuration is used to control feature availability across verification modules.
  • Configuration flags can be toggled by system administrators or product owners via backend or configuration management endpoints.
  • This endpoint is commonly used by front-end applications to dynamically enable or disable verification features in the UI.
  • Returns success: false if the configuration data cannot be loaded or accessed.

ii. Update Verification Configuration

This API enables you to retrieve the current system configuration settings and verification parameters that control various stages of the verification workflow.

Request Parameters

The following are the request parameters for GET/verification-config:
Field Data Type Required Description 
config_key
 String Yes The configuration key identifying the verification feature to update. Must match one of the valid config keys listed below. 
config_value
 Boolean Yes The new value for the configuration (true to enable, false to disable).

Method: GET

URL: https://verafi.duckdns.org/verification-config

Request Body
{ 
 "config_key": "ENABLE_LIVENESS_CHECK", 
 "config_value": "false"
}

Response Parameters

The following are the response parameters for GET/verification-config:
Field Type Description 
success
 Boolean Indicates whether the configuration update was successful. 
message
 String Confirmation message indicating which configuration was updated. 
data
 Object Contains the updated configuration details. 
data.config_key
 String The name of the configuration parameter updated. 
data.config_value
 Boolean The new boolean value applied to the configuration parameter.
Response
{
 "success": true,
 "message": "Configuration 'ENABLE_LIVENESS_CHECK' updated successfully", 
 "data": {
  "config_key": "ENABLE_LIVENESS_CHECK", 
  "config_value": false 
 }
}
Important:
The following are the valid configuration keys:
  • ENABLE_DOCUMENT_UPLOAD
  • ENABLE_LIVENESS_CHECK
  • ENABLE_VIDEO_FACE
  • ENABLE_LIVE_PHRASE
  • ENABLE_FACE_MATCH
  • ENABLE_OTP_VERIFICATION
  • ENABLE_EMAIL_VERIFICATION
  • ENABLE_CRITICAL_FIELDS_CHECK
  • ENABLE_PHRASE_VERIFICATION
Note:
  • Updates take effect immediately across the verification workflow.
  • Invalid or unrecognized config_key values return a 400 Bad Request error.
  • This endpoint is used primarily by administrators or product owners to enable or disable verification features dynamically.
  • When successful, the response confirms both the updated key and its new value.

8. Manage Configuration Store

i. Retrieve Configuration Store

Using this API, you can retrieve configuration parameters for a specific tenant or global system settings used for verification, branding, and platform customization.

Request Parameters

The following are the request parameters for GET/config-store?token={token}:
Parameter Data Type Required Description 
token
 String Yes Authentication token used to identify the tenant and authorize access to configuration parameters.

Method: GET

URL: https://verafi.duckdns.org/config-store?token=%7Btoken%7D

Request Body
GET/config-store?token={token}

Response Parameters

The following are the response parameters for GET/config-store?token={token}:
Field Data Type Description 
key_name
 String Name of the configuration parameter. 
value
 String Current value assigned to the configuration key. 
description
 String Brief explanation of the configuration’s purpose. 
is_available
 Boolean Indicates whether the configuration is currently active or accessible.
Response
[
 {
  "key_name": "ENABLE_DOCUMENT_UPLOAD",
  "value": "True", 
  "description": "Enable document upload functionality", 
  "is_available": true 
 },
 {
  "key_name": "PRIMARY_COLOR", 
  "value": "#3B82F6",
  "description": "Primary brand color", 
  "is_available": true
 },
 { 
  "key_name": "PRODUCT_LOGO",
  "value": "https://example.com/logo.png", 
  "description": "Product logo URL",
  "is_available": true
 }
]
Note:
Configuration Types
  • Boolean Keys:These keys are used for verification and storage settings
  • Appearance Keys: These keys are used for branding and UI customization
  • System Keys: The system keys enables internal configuration (e.g., AES_KEY - masked in response)

ii. Update Configuration Store

This API enables you to update one or more tenant-specific configuration entries, then returns the full, updated configuration list (same format as GET /config-store).

Request Parameters

The following are the request parameters for POST/config-store?token={token}:
Field Data Type Required Description 
key_name
 String Yes Name of the configuration key to update. Must be one of the Editable Configuration Keys below. 
value
 String Yes New value to set. For Boolean keys, use "True" or "False" (case-insensitive). 
description
 String No Optional description to store alongside the key. 
is_available
 Boolean No Whether this key is exposed/active for the tenant.

Method: POST

URL: https://verafi.duckdns.org/config-store?token=%7Btoken%7D

Request Body
[
 {
  "key_name": "ENABLE_LIVENESS_CHECK",
  "value": "True",
  "description": "Enable liveness detection", 
  "is_available": true
 },
 {
  "key_name": "PRIMARY_COLOR", 
  "value": "#10B981",
  "description": "Primary brand color", 
  "is_available": true
 }
]

Response Parameters

The following are the response parameters for POST/config-store?token={token}:
Field Data Type Description 
key_name
 String Configuration key name. 
value
 String Current value stored for the key. 
description
 String Description of the key. 
is_available
 Boolean Whether the key is currently available.
Response
[
 {
  "key_name": "ENABLE_DOCUMENT_UPLOAD",
  "value": "True", 
  "description": "Enable document upload functionality", 
  "is_available": true 
 },
 {
  "key_name": "PRIMARY_COLOR", 
  "value": "#3B82F6",
  "description": "Primary brand color", 
  "is_available": true
 },
 { 
  "key_name": "PRODUCT_LOGO",
  "value": "https://example.com/logo.png", 
  "description": "Product logo URL",
  "is_available": true
 }
]
Important:

The following are the editable configuration keys:

Boolean Keys (use "True" / "False"):
  • STORE_ID_AND_LICENSE_PHOTO
  • STORE_VIDEO
  • STORE_EXTRACTED_FACES
  • ENABLE_DOCUMENT_UPLOAD
  • ENABLE_CRITICAL_FIELDS_CHECK
  • ENABLE_LIVENESS_CHECK
  • ENABLE_VIDEO_FACE
  • ENABLE_FACE_MATCH
  • ENABLE_PHRASE_VERIFICATION
  • ENABLE_LIVE_PHRASE
  • ENABLE_OTP_VERIFICATION
  • ENABLE_EMAIL_VERIFICATION
Appearance Keys:
  • PRODUCT_LOGO
  • PRODUCT_NAME_IMAGE
  • PRODUCT_NAME
  • PRIMARY_COLOR
Note:
  • Re-posting the same key_name/value pair keeps the setting unchanged.
  • Unknown key_name → 400 Bad Request. Some keys (e.g., secure/system keys) are not editable via this endpoint.
  • For Boolean keys, the service normalizes "true", "True", "FALSE", etc., to stored string values "True"/"False".
  • Response is the authoritative post-update view used by clients to refresh UI state.
Attention:
This API returns the updated configuration list with the same format as GET.

9. Manage Tenants

i. View Tenant Details

This API returns a paginated list of tenants with subscription, usage, and (optionally) user details and analytics.

Request Parameters

The following are the request parameters for GET/tenant-management/tenants:
Field Data Type Required Default Description 
skip
 Integer No 0 Number of records to skip (offset). 
limit
 Integer No 100 Max records to return. 
include_users
 Boolean No true Include user details per tenant. 
active_only
 Boolean No false If true, return only active tenants. 
detailed
 Boolean No true Include detailed analytics (e.g., counts, revenue).

Method: GET

URL: https://verafi.duckdns.org/tenant-management/tenants

Request Body
GET/tenant-management/tenants

Response Parameters

The following are the response parameters for GET/tenant-management/tenants:
Field Data Type Description 
status
 String Request result (e.g., "success"). 
tenants
 Array<Object> List of tenant entries. 
tenants[].tenant_id
 Integer Tenant ID. 
tenants[].name
 String Tenant name. 
tenants[].subscription_tier
 String Plan tier (e.g., Premium). 
tenants[].subscription_service
 String Subscribed product/service. 
tenants[].onboarding_date
 String (ISO 8601) When the tenant was onboarded. 
tenants[].subscription_start_date
 String (ISO 8601) Subscription start. 
tenants[].subscription_end_date
 String (ISO 8601) Subscription end. 
tenants[].reports_used
 Integer Reports consumed. 
tenants[].max_reports
 Integer Reports allowance. 
tenants[].is_active
 Boolean Active flag. 
tenants[].admin_users
 Integer Count of admins. 
tenants[].operator_users
 Integer Count of operators. 
tenants[].total_users
 Integer Total users. 
tenants[].monthly_price
 Number Monthly price. 
tenants[].days_left
 Integer Days remaining in subscription. 
tenants[].status
 String Subscription status (active, expiring_soon, expired). 
tenants[].users
 Array<Object> Included only if include_users=true. 
tenants[].users[].user_id
 Integer User ID. 
tenants[].users[].name
 String User name. 
tenants[].users[].email
 String Email. 
tenants[].users[].role
 String Role (e.g., admin, operator). 
tenants[].users[].last_login
 String (ISO 8601) Last login timestamp. 
tenants[].users[].is_active
 Boolean User active flag. 
summary
 Object Aggregate metrics (present if detailed=true). 
summary.total_tenants
 Integer Total tenants returned (after filters). 
summary.active_tenants
 Integer Count of active tenants. 
summary.total_users
 Integer Total users across returned tenants. 
summary.monthly_revenue
 Number Sum of monthly_price across returned tenants. 
summary.total_reports_used
 Integer Sum of reports_used across returned tenants.
Response
{
 "status": "success", 
 "tenants": [
  { 
   "tenant_id": 1,
   "name": "Acme Corp",
   "subscription_tier": "Premium",
   "subscription_service": "ID Verification", 
   "onboarding_date": "2024-01-01T00:00:00Z",
   "subscription_start_date": "2024-01-01T00:00:00Z", 
   "subscription_end_date": "2024-12-31T23:59:59Z", 
   "reports_used": 150,
   "max_reports": 1000, "is_active": true,
   "admin_users": 2,
   "operator_users": 5,
   "total_users": 7,
   "monthly_price": 99.99, 
   "days_left": 300,
   "status": "active", 
   "users": [
    {
     "user_id": 1,
     "name": "John Doe", 
     "email": "john@example.com", "role": "admin",
     "last_login": "2024-11-01T10:30:00Z",
     "is_active": true
    }
   ]
  }
 ],
 "summary": {
 "total_tenants": 1,
 "active_tenants": 1,
 "total_users": 7,
 "monthly_revenue": 99.99,
 "total_reports_used": 150
 }
}
Important:

Status Values

The following are the tenant status:
  • active: More than 5 days remaining.
  • expiring_soon: 1–5 days remaining.
  • expired: Past end date.
Note:
  • Supports pagination with skip and limit.
  • Use active_only=true to filter tenants nearing expiry or to exclude expired tenants when combined with status logic on the client.
  • include_users=false reduces payload size for list views.
  • detailed=false omits summary for lighter responses.

ii. Retrieve Tenant User Details

With this API, you can retrieve a complete directory of users belonging to a specified tenant organization, including roles, login details, and account status.

Request Parameters

The following are the request parameters for GET/tenant-management/tenants/{tenant_id}/users:
Field Data Type Required Description 
tenant_id
 Integer Yes Unique identifier of the tenant whose user directory needs to be retrieved.

Method: GET

URL: https://verafi.duckdns.org/tenants/%7Btenant_id%7D/users

Request Body
GET/tenant-management/tenants/{tenant_id}/users

Response Parameters

The following are the response parameters for GET/tenant-management/tenants/{tenant_id}/users:
Field Data Type Description 
status
 String Indicates whether the request was successful (e.g., "success"). 
tenant_id
 Integer Unique identifier of the tenant. 
tenant_name
 String Name of the tenant organization. 
users
 Array of Object List of users associated with the tenant. 
users[].user_id
 Integer Unique identifier of the user. 
users[].name
 String Full name of the user. 
users[].email
 String Email address of the user. 
users[].role
 String Role of the user (e.g., admin, operator). 
users[].last_login
 String (ISO 8601) Timestamp of the user’s most recent login. 
users[].is_active
 Boolean Indicates whether the user account is currently active. 
total_users
 Integer Total number of users associated with the tenant.
Response
{
 "status": "success", 
 "tenant_id": 1,
 "tenant_name": "Acme Corp", 
 "users": [
  {
   "user_id": 1,
   "name": "John Doe",
   "email": "john@example.com", "role": "admin",
   "last_login": "2024-11-01T10:30:00Z",
   "is_active": true
   }
  ],
  "total_users": 1
}
Note:
  • Accessible to Product Owners (all tenants) and Admins (their own tenant only).
  • The total_users count reflects active and inactive users unless filtered at the source.
  • Commonly used in tenant administration dashboards to view, manage, or audit user accounts.
  • Returns a 404 Not Found error if the specified tenant_id does not exist or is inaccessible to the requester.

iii. Create a New Tenant

Using this API, you can establish a new tenant organization in the system with the specified subscription details.

Request Parameters

The following are the request parameters for POST/tenant-management/tenants:
Field Data Type Required Description 
name
 String Yes Name of the new tenant organization. Must be unique. 
subscription_tier_id
 Integer Yes Identifier for the subscription tier to be assigned (e.g., Basic, Premium). 
subscription_service_id
 Integer Yes Identifier for the subscribed service (e.g., ID Verification).

Method: POST

URL: https://verafi.duckdns.org/tenant-management/tenants

Request Body
{
 "name": "New Company",
 "subscription_tier_id": 1,
 "subscription_service_id": 1
}

Response Parameters

The following are the response parameters for POST/tenant-management/tenants:
Field Data Type Description 
status
 String Indicates whether the request was successful (e.g., "success"). 
message
 String Descriptive confirmation message about tenant creation. 
tenant_id
 Integer Unique identifier assigned to the newly created tenant.
Response
{
 "status": "success",
 "message": "Tenant 'New Company' created successfully", 
 "tenant_id": 2
}

iv. Onboard New Tenants

This API enables you to execute the complete tenant onboarding workflow, including tenant creation, admin user setup, subscription initialization, and configuration provisioning.

Request Parameters

The following are the request parameters for POST/tenant-management/onboard:
Field Data Type Required Description 
tenant_name
 String Yes Name of the new tenant organization. Must be unique. 
subscription_tier_id
 Integer Yes Identifier for the chosen subscription tier (e.g., Basic, Premium). 
subscription_service_id
 Integer Yes Identifier for the subscribed service (e.g., ID Verification). 
subscription_start_date
 String (YYYY-MM-DD) Yes Start date of the tenant’s subscription. The end date is automatically computed based on the plan duration. 
admin_name
 String Yes Full name of the tenant’s administrative user. 
admin_username
 String Yes Username for the tenant’s administrative user. Must be unique within the system. 
admin_email
 String Yes Email address of the administrative user. 
admin_password
 String Yes Password for the administrative account (hashed using bcrypt before storage).

Method: POST

URL: https://verafi.duckdns.org/tenant-management/onboard

Request Body
{
 "tenant_name": "New Company", 
 "subscription_tier_id": 1,
 "subscription_service_id": 1,
 "subscription_start_date": "2024-01-01", 
 "admin_name": "John Admin",
 "admin_username": "jadmin",
 "admin_email": "admin@newcompany.com", 
 "admin_password": "securepassword123"
}

Response Parameters

The following are the response parameters for POST/tenant-management/onboard:
Field Data Type Description 
status
 String Indicates whether the onboarding was successful (e.g., "success"). 
message
 String Confirmation message detailing the onboarding outcome. 
tenant_id
 Integer Unique identifier of the newly created tenant. 
user_id
 Integer Unique identifier of the created administrative user. 
tenant_name
 String Name of the newly onboarded tenant organization. 
admin_username
 String Username of the administrative account. 
admin_email
 String Email address of the administrative account. 
subscription_tier
 String Name of the assigned subscription tier. 
subscription_service
 String Name of the subscribed service. 
monthly_price
 Number Monthly subscription cost associated with the tier. 
max_reports
 Integer Maximum number of reports allowed under the subscription plan. 
subscription_end_date
 String (ISO 8601) Computed end date and time for the subscription period.
Response
{
 "status": "success",
 "message": "Tenant 'New Company' onboarded successfully", 
 "tenant_id": 2,
 "user_id": 10,
 "tenant_name": "New Company", 
 "admin_username": "jadmin",
 "admin_email": "admin@newcompany.com", 
 "subscription_tier": "Basic",
 "subscription_service": "ID Verification", 
 "monthly_price": 29.99,
 "max_reports": 100,
 "subscription_end_date": "2025-01-01T00:00:00Z"
}
Important:
Onboarding Process
  1. Validates the provided subscription_tier_id and subscription_service_id.
  2. Creates a new tenant record in the system database.
  3. Generates an administrative user account, hashing the password using bcrypt.
  4. Assigns the admin role to the created user.
  5. Initializes tenant-specific configuration settings and verification feature toggles.
  6. Copies global appearance configurations (e.g., brand colors, logo) into the tenant’s configuration store.
Note:
  • Requires Product Owner or System Admin privileges.
  • Automatically assigns default active status to both the tenant and the admin user.
  • Returns 409 Conflict if the tenant_name or admin_username already exists.
  • This endpoint provides an end-to-end setup for immediate tenant access and operation post-onboarding.

v. Validate Tenant Onboarding

Using thiS API, you can validate all onboarding inputs and configurations for a new tenant without actually creating any records in the system. This endpoint is used to pre-check data consistency and readiness before executing the onboarding process.

Request Parameters

The following are the request parameters for POST/tenant-management/onboard/validate:
Field Data Type Required Description 
tenant_name
 String Yes Name of the tenant to be created. Must be unique within the system. 
subscription_tier_id
 Integer Yes Identifier of the selected subscription tier (e.g., Basic, Premium). 
subscription_service_id
 Integer Yes Identifier of the subscription service (e.g., ID Verification). 
subscription_start_date
 String (YYYY-MM-DD) Yes Proposed start date of the subscription period. 
admin_name
 String Yes Full name of the administrative user to be created. 
admin_username
 String Yes Username for the administrative user. Must be unique. 
admin_email
 String Yes Email address of the administrative user. Must not be in use. 
admin_password
 String Yes Password to be validated for complexity (minimum length, characters, etc.).

Method: POST

URL: https://verafi.duckdns.org/tenant-management/onboard/validate

Request Body
{
 "tenant_name": "New Company", 
 "subscription_tier_id": 1,
 "subscription_service_id": 1,
 "subscription_start_date": "2024-01-01", 
 "admin_name": "John Admin",
 "admin_username": "jadmin",
 "admin_email": "admin@newcompany.com", 
 "admin_password": "securepassword123"
}

Response Parameters

The following are the response parameters for POST/tenant-management/onboard/validate:
Field Data Type Description 
errors
 Array of Object List of validation errors encountered during data verification. 
errors[].field
 String Name of the field that failed validation. 
errors[].message
 String Description of the validation issue related to the field.
Response
{
  "errors": [
  {  
   "field": "tenant_name",
   "message": "Tenant name already exists"
  } 
 ]
}
Important:
Table 3. Validation Rules
Validation Type Description
Uniqueness Checks Ensures tenant name, admin username, and admin email are not already in use.
Subscription Validation Verifies that the provided subscription_tier_id and subscription_service_id exist and are compatible.
Date Validation Ensures the subscription_start_date is a valid and current/future date.
Password Policy Confirms that the password meets minimum complexity and security standards.
Note:
  • This endpoint performs non-persistent validation; no database or configuration changes occur.
  • Used prior to calling /tenant-management/onboard to ensure smooth onboarding execution.
  • Returns an empty errors array when all input data is valid and ready for onboarding.
  • Useful for frontend validation workflows or pre-flight API checks in automated onboarding tools.

vi. Retrieve User Dashboard Data

This API enables you to retrieve subscription info, usage statistics, daily breakdowns, and computed dashboard metrics for a given user.

Request Parameters

The following are the request parameters for GET/tenant-management/user-dashboard-data:
Field Data Type Required Default Notes 
user_id
 Integer Yes — Target user identifier. 
days_back
 Integer No 30 Range of days to include (max 365).

Method: GET

URL: https://verafi.duckdns.org/tenant-management/user-dashboard-data

Request Body:
GET/tenant-management/user-dashboard-data

Response Parameters

The following are the response parameters for GET/tenant-management/user-dashboard-data:
Field Description Data Type 
status
 Request result (e.g., "success"). String 
user_id
 The requested user. Integer 
tenant_id
 User’s tenant ID. Integer 
tenant_name
 Tenant/organization name. String 
subscription_info
 Current subscription details. Object 
subscription_info.tier
 Subscription tier (e.g., Premium). String 
subscription_info.service
 Subscribed service (e.g., ID Verification). String 
subscription_info.max_reports
 Total report allowance. Integer 
subscription_info.used_reports
 Reports consumed to date. Integer 
subscription_info.start_date
 Subscription start. String (ISO 8601) 
subscription_info.end_date
 Subscription end. String (ISO 8601) 
subscription_info.days_left
 Days remaining in term. Integer 
subscription_info.is_active
 Whether the subscription is active. Boolean 
subscription_info.price
 Monthly price. Number 
subscription_info.status
 active / expiring_soon / expired. String 
subscription_info.usage_percentage
 (used_reports / max_reports) * 100. Number 
usage_stats
 Aggregated usage over the selected period. Object 
usage_stats.total_reports
 Total reports generated. Integer 
usage_stats.document_reports
 Document verification reports. Integer 
usage_stats.sms_reports
 SMS/phone-related reports. Integer 
usage_stats.email_reports
 Email-related reports. Integer 
usage_stats.weekly_average
 Avg. reports per week in period. Number 
usage_stats.period_days
 Number of days represented. Integer 
daily_usage
 Per-day usage within the period. Array<Object> 
daily_usage[].date
 Calendar date. String (YYYY-MM-DD) 
daily_usage[].reports
 Total reports that day. Integer 
daily_usage[].document_reports
 Document reports that day. Integer 
daily_usage[].sms_reports
 SMS reports that day. Integer 
daily_usage[].email_reports
 Email reports that day. Integer 
dashboard_metrics
 Computed indicators for UI. Object 
dashboard_metrics.reports_remaining
 max_reports - used_reports. Integer 
dashboard_metrics.is_near_limit
 True if remaining is below internal threshold. Boolean 
dashboard_metrics.is_expiring_soon
 True if status == expiring_soon. Boolean 
dashboard_metrics.current_usage_rate
 Avg. reports per day over period. Number 
dashboard_metrics.projected_days_until_limit
 Projection based on current rate. Integer
Response
{
 "status": "success", 
 "user_id": 1,
 "tenant_id": 1,
 "tenant_name": "Acme Corp", 
 "subscription_info": {
  "tier": "Premium",
  "service": "ID Verification", 
  "max_reports": 1000,
  "used_reports": 150,
  "start_date": "2024-01-01T00:00:00Z", 
  "end_date": "2024-12-31T23:59:59Z",
  "days_left": 300, 
  "is_active": true, 
  "price": 99.99,
 "status": "active",
  "usage_percentage": 15.0
 },
 "usage_stats": {
  "total_reports": 45,
  "document_reports": 30, 
  "sms_reports": 10,
  "email_reports": 5,
  "weekly_average": 10.5,
  "period_days": 30
},
"daily_usage": [
 {
  "date": "2024-10-10",
  "reports": 5, 
  "document_reports": 3,
  "sms_reports": 1,
  "email_reports": 1
 }
],
"dashboard_metrics": {
 "reports_remaining": 850, 
 "is_near_limit": false,
 "is_expiring_soon": false, 
 "current_usage_rate": 1.5,
 "projected_days_until_limit": 566
 }
}

vii. Legacy Execution for Tenant Management Operations

Using this API, you can provide a single unified endpoint for executing multiple tenant and user management operations.
Note:
This endpoint exists for legacy support and backward compatibility. New integrations should use the individual REST endpoints (e.g., /tenant-management/tenants, /tenant-management/onboard, etc.).
Table 4. Supported Operations
Operation Name Description 
create_tenant
 Creates a new tenant organization. 
create_tenant_with_users
 Creates a tenant and one or more associated user accounts. 
add_users_to_existing_tenant
 Adds new users to an existing tenant. 
create_users_without_tenant
 Creates standalone user accounts not linked to any tenant. 
assign_users_to_tenant
 Assigns existing users to a specified tenant. 
update_tenant_license
 Updates subscription license or tier information for a tenant. 
add_roles_to_user
 Grants additional roles or permissions to a user. 
remove_roles_from_user
 Revokes specific roles from a user. 
create_role
 Creates a new user role definition in the system. 
get_tenant_info
 Retrieves details of a specific tenant. 
get_user_info
 Retrieves details of a specific user. 
list_all_tenants
 Lists all tenants currently registered in the system. 
list_tenant_users
 Lists all users associated with a given tenant.

Request Parameters

The following are the request parameters for POST/tenant-management/execute:
Field Data Type Required Description
operation String Yes Specifies which legacy operation to execute (see list above).
tenant Object Conditional Tenant-related data, required for tenant operations (e.g., create_tenant, update_tenant_license).
user Object Conditional User-related data, required for user operations (e.g., add_roles_to_user, get_user_info).
license_info Object Conditional License or subscription information, used for update_tenant_license and similar operations.

Method: POST

URL: https://verafi.duckdns.org/tenant-management/execute

Request Body
{
 "operation": "create_tenant", 
 "tenant": {
 "name": "New Company", 
 "license_info": {}
 }
}

Response Parameters

The following are the request parameters for POST/tenant-management/execute:
Field Data Type Description 
status
 String Indicates the outcome of the operation (e.g., "success", "error"). 
message
 String Descriptive message about the result of the operation. 
tenant_id
 Integer Tenant identifier (returned for tenant creation or update operations). 
tenant_name
 String Tenant name (returned for tenant operations). 
license_info
 Object License or subscription details (returned for licensing-related operations). 
user_id
 Integer User identifier (returned for user-related operations). 
role_changes
 Object Summary of roles added or removed (for role operations). 
tenants / users
 Array of Object Returned for list or query operations.
Response
{
 "status": "success",
 "message": "Tenant 'New Company' created successfully", 
 "tenant_id": 2,
 "tenant_name": "New Company", 
 "license_info": {}
}
Note:
  • The response structure varies based on the requested operation.
  • Refer to legacy backend service documentation or source code for detailed field mappings per operation.
  • This endpoint should be used only for backward compatibility with systems relying on pre-refactor APIs.
  • Errors may include invalid operation strings or missing fields required for specific actions (returns 400 Bad Request).

10. Manage Subscriptions

i. View Subscription Plans

This API, enables you to retrieve all available subscription tiers, services, and their pricing matrix for display and selection in front-end onboarding or billing interfaces.

Request Parameters

The following are the request parameters for GET/subscription-management/plans:
Field Data Type Required Description
None — — This endpoint does not require any path or query parameters.

Method: GET

URL: https://verafi.duckdns.org/subscription-management/plans

Request Body
GET/subscription-management/plans

Response Parameters

The following are the request parameters for GET/subscription-management/plans:
Field Data Type Description 
tiers
 Array<Object> List of subscription tiers with limits and availability. 
tiers[].tier_id
 Integer Unique identifier for the subscription tier. 
tiers[].tier_name
 String Name of the tier (e.g., Basic, Premium). 
tiers[].max_reports
 Integer Maximum number of verification reports allowed for this tier. 
tiers[].is_active
 Boolean Indicates if the tier is currently active and available for selection. 
services
 Array<Object> List of services that can be subscribed to under different tiers. 
services[].service_id
 Integer Unique identifier for the service. 
services[].service_name
 String Name of the service (e.g., ID Verification, Bank Statement Analysis). 
services[].is_active
 Boolean Indicates if the service is currently active. 
pricing_matrix
 Array<Object> Defines pricing by tier and service combination. 
pricing_matrix[].tier_id
 Integer Associated tier ID for this pricing record. 
pricing_matrix[].service_id
 Integer Associated service ID for this pricing record. 
pricing_matrix[].price_usd
 Number Price of the subscription plan in USD.
Response
{
"tiers": [
  {
   "tier_id": 1,
   "tier_name": "Basic", 
   "max_reports": 100, 
   "is_active": true
  },
 {
  "tier_id": 2,
  "tier_name": "Premium", 
  "max_reports": 1000,
  "is_active": true
 }
],
"services": [
 {
  "service_id": 1,
  "service_name": "ID Verification", 
  "is_active": true
 },
 {
  "service_id": 2,
  "service_name": "Bank Statement Analysis", 
  "is_active": true
 }
],
"pricing_matrix": [
  {
   "tier_id": 1,
   "service_id": 1,
   "price_usd": 29.99
  },
  {
  "tier_id": 2,
  "service_id": 1,
  "price_usd": 99.99
  }
 ]
}

ii. Retrieve Pricing Details for Plans

Using this API, you can retrieve the subscription price for a specific tier and service combination, typically used for plan comparison or checkout workflows.

Request Parameters

The following are the request parameters for GET/subscription-management/pricing/{tier_id}/{service_id}:
Field Data Type Required Description 
tier_id
 Integer Yes Unique identifier of the subscription tier. 
service_id
 Integer Yes Unique identifier of the subscription service associated with the tier.

Method: GET

URL: https://verafi.duckdns.org/subscription-management/pricing/%7Btier_i%7Bservice_id%7B

Request Body
GET/subscription-management/pricing/{tier_id}/{service_id}

Response Parameters

The following are the response parameters for GET/subscription-management/pricing/{tier_id}/{service_id}:
Field Data Type Required Description 
tier_id
 Integer Yes Unique identifier of the subscription tier (e.g., Basic, Premium). 
service_id
 Integer Yes Unique identifier of the service (e.g., ID Verification, Bank Statement Analysis).
Response
{
 "price": 29.99
}
Note:
  • Returns 404 Not Found if the specified tier_id or service_id combination does not exist in the pricing matrix.
  • Prices are expressed in USD by default, but the system can be extended for multi-currency support.
  • Used by frontend applications to display accurate pricing before tenant onboarding or plan upgrades.

iii. Subscription Tiers Management

a. You can retrieve all available subscription tiers with pagination, including their configuration, status, and creation metadata.

Request Parameters

The following are the request parameters for GET/subscription-management/tiers?skip=0&limit=100 :
Field Data Type Required Default Description 
skip
 Integer No 0 Number of records to skip (used for pagination). 
limit
 Integer No 100 Maximum number of records to return (max: 1000).

Method: GET

URL: https://verafi.duckdns.org/subscription-management/tiers?skip=0&limit=100

Request Body
GET/subscription-management/tiers?skip=0&limit=100

Response Parameters

The following are the response parameters for GET/subscription-management/tiers?skip=0&limit=100 :
Field Data Type Description 
tier_id
 Integer Unique identifier of the subscription tier. 
tier_name
 String Name of the subscription tier (e.g., Basic, Premium). 
max_reports
 Integer Maximum number of reports allowed under the tier. 
is_active
 Boolean Indicates whether the tier is currently active and available for subscription. 
created_on
 String (ISO 8601) Timestamp of when the tier was created in the system.
Response
[
 {
  "tier_id": 1,
  "tier_name": "Basic", 
  "max_reports": 100, 
  "is_active": true,
  "created_on": "2024-01-01T00:00:00Z"
 },
{
  "tier_id": 2,
  "tier_name": "Premium", 
  "max_reports": 1000,
  "is_active": true,
  "created_on": "2024-01-01T00:00:00Z"
 }
]

b. You can retrieve detailed information about a specific subscription tier using its unique identifier.

Request Parameters

The following are the request parameters for GET/subscription-management/tiers/{tier_id} :
Field Data Type Required Description 
tier_id
 Integer Yes Unique identifier of the subscription tier to retrieve.

Method: GET

URL: https://verafi.duckdns.org/subscription-management/tiers/%7Btier_id%7B

Request Body
GET/subscription-management/tiers/{tier_id}

Response Parameters

The following are the request parameters for GET/subscription-management/tiers/{tier_id}:
Field Data Type Description 
tier_id
 Integer Unique identifier of the subscription tier. 
tier_name
 String Name of the subscription tier (e.g., Basic, Premium). 
max_reports
 Integer Maximum number of reports permitted under this tier. 
is_active
 Boolean Indicates whether this tier is currently active. 
created_on
 String (ISO 8601) Date and time when the tier was created.
Response
{
 "tier_id": 1,
 "tier_name": "Basic", 
 "max_reports": 100, 
 "is_active": true,
 "created_on": "2024-01-01T00:00:00Z"
}

c. You can create a new subscription tier with defined report limits and activation status for system-wide availability.

Request Parameters

The following are the request parameters for POST/subscription-management/tiers :
Field Data Type Required Description 
tier_name
 String Yes Name of the new subscription tier (e.g., Enterprise, Professional). Must be unique. 
max_reports
 Integer Yes Maximum number of reports permitted for this tier. 
is_active
 Boolean Yes Determines whether the tier is active and available for subscription.

Method: POST

URL: https://verafi.duckdns.org/subscription-management/tiers

Request Body
{
"tier_name": "Enterprise", 
"max_reports": 10000,
"is_active": true
}

Response Parameters

The following are the response parameters for POST/subscription-management/tiers:
Field Data Type Description 
tier_id
 Integer Unique identifier assigned to the newly created subscription tier. 
tier_name
 String Name of the created subscription tier. 
max_reports
 Integer Report limit for this tier. 
is_active
 Boolean Indicates whether the tier is currently active. 
created_on
 String (ISO 8601) Timestamp when the tier was created.
Response
{
 "tier_id": 3,
 "tier_name": "Enterprise", 
 "max_reports": 10000,
 "is_active": true,
 "created_on": "2024-10-16T00:00:00Z"
}

d. You can update the details of an existing subscription tier, including its name, report limits, and activation status.

Table 5. Query Parameters
Field Data Type Required Description 
tier_id
 Integer Yes Unique identifier of the subscription tier to update.

Request Parameters

The following are the request parameters for PUT/subscription-management/tiers/{tier_id}:
Field Data Type Required Description 
tier_name
 String Yes Updated name of the subscription tier (must be unique). 
max_reports
 Integer Yes Updated maximum number of reports allowed for this tier. 
is_active
 Boolean Yes Indicates whether the tier should remain active and available for subscription.

Method: PUT

URL: https://verafi.duckdns.org/subscription-management/tiers/%7Btier_id%7B

Request Body
{
 "tier_name": "Enterprise Plus", 
 "max_reports": 15000,
 "is_active": true
}

Response Parameters

The following are the response parameters for PUT/subscription-management/tiers/{tier_id}:
Field Data Type Description 
tier_id
 Integer Unique identifier of the updated subscription tier. 
tier_name
 String Updated tier name. 
max_reports
 Integer Updated report limit for the tier. 
is_active
 Boolean Indicates whether the tier remains active. 
created_on
 String (ISO 8601) Original creation timestamp of the tier.
Response
{
 "tier_id": 3,
 "tier_name": "Enterprise Plus", 
 "max_reports": 15000,
 "is_active": true,
 "created_on": "2024-10-16T00:00:00Z"
}

e. You can permanently remove a subscription tier from the system.

Attention:
Once deleted, the tier will no longer be available for tenant assignment or subscription selection.

Request Parameters

The following are the request parameters for DELETE/subscription-management/tiers/{tier_id}:
Field Data Type Required Description 
tier_id
 Integer Yes Unique identifier of the subscription tier to delete.

Method: DELETE

URL: https://verafi.duckdns.org/subscription-management/tiers/%7Btier_id%7B

Request Body
DELETE/subscription-management/tiers/{tier_id}

Response Parameters

The following are the response parameters for DELETE/subscription-management/tiers/{tier_id}:
Field Data Type Description 
message
 String Confirmation message indicating that the subscription tier was deleted successfully.
Response
{
 "message": "Subscription tier deleted successfully"
}

iv. Subscription Services Management

a. You can retrieve all available subscription services offered by the platform, with support for pagination and filtering.

Request Parameters

The following are the request parameters for GET/subscription-management/tiers?skip=0&limit=100 :
Field Data Type Required Default Description 
skip
 Integer No 0 Number of records to skip (used for pagination). 
limit
 Integer No 100 Maximum number of records to return (max: 1000).

Method: GET

URL: https://verafi.duckdns.org/subscription-management/services?skip=0&limit=100

Request Body
GET/subscription-management/services?skip=0&limit=100

Response Parameters

The following are the response parameters for GET/subscription-management/services?skip=0&limit=100 :
Field Data Type Description 
service_id
 Integer Unique identifier of the subscription service. 
service_name
 String Name of the subscription service (e.g., ID Verification). 
service_description
 String Brief description of what the service provides. 
is_active
 Boolean Indicates whether the service is currently active and available for subscription. 
created_on
 String (ISO 8601) Timestamp of when the service was created in the system.
Response
[
 {
  "service_id": 1,
  "service_name": "ID Verification",
  "service_description": "Identity document verification service", 
  "is_active": true,
  "created_on": "2024-01-01T00:00:00Z"
 },
 {
  "service_id": 2,
  "service_name": "Bank Statement Analysis",
  "service_description": "Financial document analysis service", "is_active": true,
  "created_on": "2024-01-01T00:00:00Z"
 }
]

b. You can retrieve detailed information about a specific subscription service using its unique identifier.

Request Parameters

The following are the request parameters for GET/subscription-management/services/{service_id}:
Field Data Type Required Description 
service_id
 Integer Yes Unique identifier of the subscription service to retrieve.

Method: GET

URL: https://verafi.duckdns.org/subscription-management/services/%7Bservice_id%7B

Request Body
GET/subscription-management/services/{service_id}

Response Parameters

The following are the response parameters for GET/subscription-management/services/{service_id}:
Field Data Type Description 
service_id
 Integer Unique identifier of the subscription service. 
service_name
 String Name of the service (e.g., ID Verification). 
service_description
 String Detailed description of what the service provides. 
is_active
 Boolean Indicates whether the service is currently active and available for subscription. 
created_on
 String (ISO 8601) Timestamp indicating when the service was created.
Response
{
 "service_id": 1,
 "service_name": "ID Verification", 
 "service_description": "Identity document verification service", 
 "is_active": true,
 "created_on": "2024-01-01T00:00:00Z"
}
Note:
  • Commonly used for service configuration pages, plan pricing lookups, or tenant onboarding workflows.
  • To view all available services, use GET /subscription-management/services.

c. You can create a new subscription service entry in the system that can be associated with subscription tiers and offered to tenants.

Request Parameters

The following are the request parameters for POST/subscription-management/services:
Field Data Type Required Description 
service_name
 String Yes Name of the new subscription service (must be unique). 
service_description
 String Yes Description of the service functionality or purpose. 
is_active
 Boolean Yes Indicates whether the service is active and available for subscription.

Method: POST

URL: https://verafi.duckdns.org/subscription-management/services

Request Body
{
 "service_name": "Bank Statement Analysis",
 "service_description": "Financial document analysis service", 
 "is_active": true
}

Response Parameters

The following are the response parameters for POST/subscription-management/services:
Field Data Type Description 
service_id
 Integer Unique identifier assigned to the newly created subscription service. 
service_name
 String Name of the created service. 
service_description
 String Description of the service. 
is_active
 Boolean Indicates whether the service is currently active. 
created_on
 String (ISO 8601) Timestamp of when the service was created in the system.
Response
{
 "service_id": 3,
 "service_name": "Bank Statement Analysis",
 "service_description": "Financial document analysis service", 
 "is_active": true,
 "created_on": "2024-10-16T00:00:00Z"
}
Note:
  • Returns a 409 Conflict if a service with the same service_name already exists.
  • Once created, the service can be linked to tiers using the pricing matrix in /subscription-management/plans.
  • The new service becomes immediately available for configuration and assignment if is_active is set to true.

d. You can update the details of an existing subscription service, including its name, description, and activation status.

Request Parameters

The following are the request parameters for PUT/subscription-management/services/{service_id}:
Field Data Type Required Description 
service_name
 String Yes Updated name of the subscription service (must be unique). 
service_description
 String Yes Updated description explaining the service purpose or functionality. 
is_active
 Boolean Yes Indicates whether the service remains active and available for subscription.

Method: PUT

URL: https://verafi.duckdns.org/subscription-management/services/%7Bservice_id%7B

Request Body
{
 "service_name": "Advanced Bank Statement Analysis",
 "service_description": "Enhanced financial document analysis", 
 "is_active": true
}

Response Parameters

The following are the response parameters for PUT/subscription-management/services/{service_id}:
Field Data Type Description 
service_id
 Integer Unique identifier of the updated subscription service. 
service_name
 String Updated service name. 
service_description
 String Updated service description. 
is_active
 Boolean Indicates whether the service is active after update. 
created_on
 String (ISO 8601) Original creation timestamp of the service.
Response
{
 "service_id": 3,
 "service_name": "Advanced Bank Statement Analysis",
 "service_description": "Enhanced financial document analysis", 
 "is_active": true,
 "created_on": "2024-10-16T00:00:00Z"
}
Note:
  • Returns 404 Not Found if the specified service_id does not exist.
  • Returns 409 Conflict if another service with the same service_name already exists.
  • The created_on field is retained from the original record and not modified during update.

e. You can permanently delete an existing subscription service from the system.

Request Parameters

The following are the request parameters for DELETE/subscription-management/services/{service_id} :
Field Data Type Required Description 
service_id
 Integer Yes Unique identifier of the subscription service to delete.

Method: DELETE

URL: https://verafi.duckdns.org/subscription-management/services/service_id%7B

Request Body
DELETE/subscription-management/services/{service_id}

Response Parameters

The following are the response parameters for DELETE/subscription-management/services/{service_id}:
Field Data Type Description 
message
 String Confirmation message indicating the subscription service was deleted successfully.
Response
{
 "message": "Subscription service deleted successfully"
}

v. Subscription Pricing Management

a. You can retrieve all pricing records that define the cost relationship between subscription tiers and services.

Request Parameters

The following are the request parameters for GET/subscription-management/pricing:
Field Data Type Required Description
None — — This endpoint does not require any request parameters.

Method: GET

URL: https://verafi.duckdns.org/subscription-management/pricing

Request Body
GET/subscription-management/pricing

Response Parameters

The following are the response parameters for GET/subscription-management/pricing:
Field Data Type Description 
pricing_id
 Integer Unique identifier of the pricing record. 
tier_id
 Integer Identifier of the associated subscription tier. 
service_id
 Integer Identifier of the associated subscription service. 
price_usd
 Number Price of the subscription in USD for the given tier-service combination. 
is_active
 Boolean Indicates whether this pricing record is currently active. 
created_on
 String (ISO 8601) Timestamp indicating when the pricing record was created.
Response
[
{
"pricing_id": 1,
"tier_id": 1,
"service_id": 1,
"price_usd": 29.99, "is_active": true,
"created_on": "2024-01-01T00:00:00Z"
},
{
"pricing_id": 2,
"tier_id": 2,
"service_id": 1,
"price_usd": 99.99, "is_active": true,
"created_on": "2024-01-01T00:00:00Z"
}
]
Note:
  • Requires admin or product owner privileges to view full pricing data.
  • Typically used by billing systems or frontend dashboards to display available pricing tiers and combinations.
  • is_active = false
    indicates deprecated or legacy pricing not currently available for new tenants.
  • Each record represents a unique mapping between a subscription tier and a service.
  • Use POST /subscription-management/pricing to add new pricing entries or PUT/subscription-management/pricing/{pricing_id} to modify existing ones.

b. You can retrieve detailed information about a specific pricing record that defines the cost for a given subscription tier and service combination.

Request Parameters

The following are the request parameters for GETsubscription-management/pricing/{pricing_id}:
Field Data Type Required Description 
pricing_id
 Integer Yes Unique identifier of the subscription pricing record to retrieve.

Method: GET

URL: https://verafi.duckdns.org/subscription-management/pricing/%7Bpricing_id%7B

Request Body
GET/subscription-management/pricing/{pricing_id}

Response Parameters

The following are the response parameters for GET/subscription-management/pricing/{pricing_id}:
Field Data Type Description 
pricing_id
 Integer Unique identifier of the pricing record. 
tier_id
 Integer Identifier of the associated subscription tier. 
service_id
 Integer Identifier of the associated subscription service. 
price_usd
 Number Price in USD for this tier-service combination. 
is_active
 Boolean Indicates whether this pricing record is currently active. 
created_on
 String (ISO 8601) Timestamp when the pricing record was created.
Response
{
"pricing_id": 1,
"tier_id": 1,
"service_id": 1,
"price_usd": 29.99, "is_active": true,
"created_on": "2024-01-01T00:00:00Z"
}
Note:
  • Requires admin privileges or billing service access.
  • Returns a 404 Not Found error if the specified pricing_id does not exist.
  • Commonly used in plan management and pricing configuration dashboards to retrieve pricing details for editing or display.
  • Pricing data is immutable in historical billing records, but updates can be made via PUT /subscription-management/pricing/{pricing_id} for future use.

c. You can create a new pricing record defining the cost for a specific subscription tier–service combination.

Request Parameters

The following are the request parameters for POST/subscription-management/pricing:
Field Data Type Required Description 
tier_id
 Integer Yes Identifier of the subscription tier associated with this pricing record. 
service_id
 Integer Yes Identifier of the subscription service for which pricing is defined. 
price_usd
 Number Yes Price of the subscription in USD. 
is_active
 Boolean Yes Indicates whether this pricing record is active and available for new subscriptions.

Method: POST

URL: https://verafi.duckdns.org/subscription-management/pricing

Request Body
{
"tier_id": 1,
"service_id": 1,
"price_usd": 29.99, "is_active": true
}

Response Parameters

The following are the response parameters for POST/subscription-management/pricing:
Field Data Type Description 
pricing_id
 Integer Unique identifier assigned to the newly created pricing record. 
tier_id
 Integer Associated subscription tier ID. 
service_id
 Integer Associated subscription service ID. 
price_usd
 Number Price of the plan in USD. 
is_active
 Boolean Indicates whether the pricing record is currently active. 
created_on
 String (ISO 8601) Timestamp of when the pricing record was created.
Response
{
 "pricing_id": 3,
 "tier_id": 1,
 "service_id": 1,
 "price_usd": 29.99, 
 "is_active": true, 
 "created_on": "2024-10-16T00:00:00Z"
}
Note:
  • Returns 409 Conflict if a pricing record already exists for the same tier_id and service_id combination.
  • Automatically links the new pricing record to both the specified tier and service.
  • Use is_active: false to define pricing for future rollout or inactive plans.
  • To modify existing pricing, use PUT/subscription-management/pricing/{pricing_id}.

d. You can update an existing pricing record to adjust the price or activation status for a specific tier–service combination.

Request Parameters

The following are the response parameters for PUT/subscription-management/pricing/{pricing_id}:
Field Data Type Required Description 
price_usd
 Number Yes Updated price of the subscription in USD. 
is_active
 Boolean Yes Indicates whether this pricing record remains active.

Method: PUT

URL: https://verafi.duckdns.org/subscription-management/pricing/%7Bpricing_id%7B

Request Body
{
 "price_usd": 34.99, 
 "is_active": true
}

Response Parameters

The following are the response parameters for PUT/subscription-management/pricing/{pricing_id}:
Field Data Type Description 
pricing_id
 Integer Unique identifier of the updated pricing record. 
tier_id
 Integer Identifier of the associated subscription tier. 
service_id
 Integer Identifier of the associated subscription service. 
price_usd
 Number Updated price in USD. 
is_active
 Boolean Indicates whether the pricing record is active after the update. 
created_on
 String (ISO 8601) Original creation timestamp of the pricing record.
Response
{
"pricing_id": 3,
"tier_id": 1,
"service_id": 1,
"price_usd": 34.99, 
"is_active": true,
"created_on": "2024-10-16T00:00:00Z"
}
Note:
  • Returns 404 Not Found if the specified pricing_id does not exist.
  • The created_on timestamp remains unchanged to preserve audit history.
  • This operation typically affects future tenant subscriptions, not existing ones already billed under prior pricing.
  • For price rollouts or deactivations, set is_active to false to temporarily disable the plan without deleting it.

e. You can permanently remove a specific pricing record that defines the cost relationship between a subscription tier and service.

Request Parameters

The following are the request parameters for DELETE/subscription-management/pricing/{pricing_id}:
Field Data Type Required Description 
pricing_id
 Integer Yes Unique identifier of the pricing record to be permanently removed.

Method: DELETE

URL: https://verafi.duckdns.org/subscription-management/pricing/%7Bpricing_id%7D

Request Body
DELETE/subscription-management/pricing/{pricing_id}

Response Parameters

The following are the response parameters for DELETE/subscription-management/pricing/{pricing_id}:
Field Data Type Description 
message
 String Confirmation message indicating the pricing record was deleted successfully.
Response
{
"message": "Subscription pricing deleted successfully"
}
Note:
  • Returns 404 Not Found if the specified pricing_id does not exist.
  • Returns 409 Conflict if the pricing record is linked to an active tenant subscription or billing record.
  • It is generally recommended to deactivate (is_active: false) pricing records instead of deleting them to maintain historical billing integrity.
  • Deletion is permanent and irreversible; audit logs should retain the deleted pricing ID and metadata for compliance tracking.

vi. Usage Statistics

a. You can retrieve comprehensive subscription usage statistics and analytics.

Request Parameters

The following are the request parameters for GET/subscription-management/usage/statistics?days_back=30:
Field Data Type Required Default Description
days_back Integer No 30 Number of days of data to retrieve (maximum: 365).

Method: GET

URL: https://verafi.duckdns.org/subscription-management/usage/statistics?days_back=30

Request Body
GET/subscription-management/usage/statistics?days_back=30

Response Parameters

The following are the response parameters for GET/subscription-management/usage/statistics?days_back=30:
Field Data Type Description 
status
 String Indicates whether the request was successful (e.g., "success"). 
overall_stats
 Object Aggregated usage data for all tenants within the specified period. 
overall_stats.total_reports
 Integer Total number of verification or analysis reports generated. 
overall_stats.document_reports
 Integer Number of document verification reports generated. 
overall_stats.sms_reports
 Integer Number of phone/SMS-based verifications. 
overall_stats.email_reports
 Integer Number of email-based verifications. 
overall_stats.weekly_average
 Number Average number of reports generated per week during the period. 
overall_stats.period_days
 Integer Total number of days included in the statistical range. 
period
 Object Metadata about the date range covered by the statistics. 
period.start_date
 String (ISO 8601) Start date of the reporting period. 
period.end_date
 String (ISO 8601) End date of the reporting period. 
period.days_back
 Integer Number of days back from the end date represented in the data.
Response
{
 "status": "success", 
 "overall_stats": {
  "total_reports": 1500,
  "document_reports": 1000,
  "sms_reports": 300,
  "email_reports": 200,
  "weekly_average": 350,
  "period_days": 30
 },
  "period": {
  "start_date": "2024-09-10T00:00:00Z", 
  "end_date": "2024-10-10T00:00:00Z",
  "days_back": 30
 }
}
Note:
  • The API aggregates data across all active tenants and verification types.
  • If days_back exceeds 365, the system automatically clamps it to the maximum allowed value.
  • The weekly_average value is computed as (total_reports / period_days) *7.
  • Commonly used in administrative dashboards, billing overviews, and usage trend monitoring tools.

b. You can retrieve usage statistics aggregated by subscription tiers.

Request Parameters

The following are the request parameters for GET/subscription-management/usage/tiers?days_back=30:
Field Data Type Required Default Description
days_back Integer No 30 Number of days of usage data to retrieve. Must be between 1 and 365.

Method: GET

URL:

https://verafi.duckdns.org/subscription-management/usage/tiers?days_back=30

Request Body
GET/subscription-management/usage/tiers?days_back=30

Response Parameters

The following are the response parameters for GET/subscription-management/usage/tiers?days_back=30:
Field Data Type Description 
status
 String Indicates whether the request was successful (e.g., "success"). 
tier_statistics
 Array List of aggregated usage data per subscription tier. 
tier_statistics[].tier_id
 Integer Unique identifier of the subscription tier. 
tier_statistics[].tier_name
 String Name of the subscription tier (e.g., Basic, Premium). 
tier_statistics[].total_reports
 Integer Total number of verification or analysis reports generated by tenants under this tier during the period. 
tier_statistics[].active_tenants
 Integer Count of active tenants using this subscription tier. 
tier_statistics[].this_month_reports
 Integer Number of reports generated in the current month by this tier. 
period
 Object Metadata defining the timeframe of the reported statistics. 
period.start_date
 String (ISO 8601) Start date of the reporting period. 
period.end_date
 String (ISO 8601) End date of the reporting period. 
period.days_back
 Integer Number of days represented in the dataset.
Response
{
 "status": "success", 
 "tier_statistics": [
  {
   "tier_id": 1,
   "tier_name": "Basic", 
   "total_reports": 500,
   "active_tenants": 10,
   "this_month_reports": 100
  }
 ],
 "period": {
  "start_date": "2024-09-10T00:00:00Z", 
  "end_date": "2024-10-10T00:00:00Z",
  "days_back": 30
 }
}
Note:
  • Aggregates statistics across all tenants within each subscription tier.
  • Useful for performance tracking, tier utilization analysis, and capacity planning.
  • The field this_month_reports resets automatically at the start of each billing cycle.
  • If days_back exceeds 365, it defaults to the maximum limit of 365 days.

c. You can retrieve usage statistics aggregated by subscription services.

Request Parameters

The following are the request parameters for GET/subscription-management/usage/services?days_back=30:
Field Data Type Required Default Description 
days_back
 Integer No 30 Number of days of usage data to retrieve. Must be between 1 and 365.

Method: GET

URL: https://verafi.duckdns.org/subscription-management/usage/services?days_back=30

Request Body
GET/subscription-management/usage/services?days_back=30

Response Parameters

The following are the response parameters for GET/subscription-management/usage/services?days_back=30:
Field Data Type Description 
status
 String Indicates the success of the request (e.g., "success"). 
service_statistics
 Array Collection of usage analytics for each subscription service. 
service_statistics[].service_id
 Integer Unique identifier of the subscription service. 
service_statistics[].service_name
 String Name of the subscription service (e.g., ID Verification). 
service_statistics[].total_reports
 Integer Total number of verification or analysis reports generated for this service within the specified period. 
service_statistics[].active_tenants
 Integer Number of active tenants currently subscribed to this service. 
service_statistics[].this_month_reports
 Integer Number of reports generated in the current month for this service. 
period
 Object Metadata describing the time range of the retrieved statistics. 
period.start_date
 String (ISO 8601) Start date of the reporting window. 
period.end_date
 String (ISO 8601) End date of the reporting window. 
period.days_back
 Integer Total number of days covered in the report.
Response
{
 "status": "success",
 "service_statistics": [
  {
   "service_id": 1,
   "service_name": "ID Verification", 
   "total_reports": 1200,
   "active_tenants": 15,
   "this_month_reports": 250
  }
 ],
 "period": {
  "start_date": "2024-09-10T00:00:00Z", 
  "end_date": "2024-10-10T00:00:00Z",
  "days_back": 30
 }
}
Note:
  • Provides a breakdown of platform activity per service to identify high-usage areas or underutilized features.
  • Data is aggregated across all tenants subscribed to the given service.
  • this_month_reports resets at the start of each calendar or billing month.
  • If days_back exceeds 365, the system defaults to the maximum allowable value of 365 days.

11. Process Documents using Microservice Proxy

i. Upload a Document

Using this API, you can upload an identity document image (DL/Passport/ID), proxies it to the OCR microservice, and returns enriched extraction with face snapshots and a live-phrase prompt.

Request Parameters

The following are the request parameters for POST/upload:
Field Data Type Required Notes 
file
 File (PNG/JPG/JPEG) Yes Single image of the ID document. 
session_id
 String (UUID) No If omitted, a new session is auto-generated and returned.

Method: POST

URL: https://verafi.duckdns.org/upload

Request Body
POST/upload
Request Body
{
  "file": "driver_license.jpg",
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response Parameters

he following are the response parameters for POST/upload:
Field Type Description 
type
 String Fixed: "id_document". 
documentType
 String Detected document class (e.g., Driver License, Passport). 
analyzeResult
 Object OCR and face extraction output. 
analyzeResult.documents
 Array One or more parsed documents. 
...fields.*.value
 String Extracted field value (e.g., name, number, DOB, expiry). 
...fields.*.confidence
 Number Confidence score (0–1). 
analyzeResult.faces
 Array<String> Base64-encoded face images (if captured). 
phrase
 String Live phrase generated for liveness/voice prompt (name-aware). 
session_id
 String Session identifier (existing or newly created).
Response
{
 "type": "id_document",
 "documentType": "Driver License", 
 "analyzeResult": {
 "documents": [
  {
   "fields": {
    "name": {
     "value": "John Doe", 
     "confidence": 0.95
    },
    "documentNumber": {
     "value": "D123456789",
     "confidence": 0.98
     },
   "dateOfBirth": {
    "value": "1990-01-01",
    "confidence": 0.97
   },
   "expirationDate": {
    "value": "2025-12-31",
    "confidence": 0.96
    }
   }
  }
 ],
 "faces": ["base64-encoded-face-image"]
 },
 "phrase": "Please say: Blue sky with clouds", 
 "session_id": "uuid-session-id"
}
Important:
Processing Flow
  1. Save and encrypt the uploaded image if STORE_ID_AND_LICENSE_PHOTO is enabled.
  2. Forward image to the OCR microservice for text/field extraction.
  3. Save extracted face snapshots if STORE_EXTRACTED_FACES is enabled.
  4. Parse OCR to get user name.
  5. Generate a verification phrase that includes the extracted name context.
  6. Return a combined payload to the frontend (fields + faces + phrase + session_id).

ii. Process Facial Image and Video Identification

This API enables you to upload and analyze a facial image or video for identity verification. The API proxies the content to the face recognition microservice, performs detection and quality scoring, and stores data securely if enabled.

Request Parameters

The following are the request parameters for POST/face:
Field Data Type Required Description 
file
 File (JPG, PNG, MP4, MOV) Yes Image or video file containing a person’s face. 
session_id
 String (UUID) No Identifier linking the upload to an existing verification session. Auto-generated if not provided.

Method: POST

URL: https://verafi.duckdns.org/face

Request Body
{
  "file": "face_capture.jpg",
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response Parameters

The following are the response parameters for POST/face:
Field Data Type Description 
face_filename
 String Base64-encoded image of the detected face (preview-ready). 
analysis_result
 Object Contains face detection and quality analysis results. 
analysis_result.face_detected
 Boolean Whether a face was detected in the input image/video. 
analysis_result.face_quality
 Number Confidence score (0–1) of face clarity and usability. 
session_id
 String Session identifier for tracking verification sequence.
Response
{
 "face_filename": "data:image/jpeg;base64,encoded-face", 
 "analysis_result": {
  "face_detected": true, 
  "face_quality": 0.95
 },
 "session_id": "uuid-session-id"
}
Note:
  • File is saved and encrypted if storage configuration is enabled (STORE_VIDEO, STORE_EXTRACTED_FACES).
  • Automatically extracts faces from video frames before analysis.
  • Supports both static images and short video clips for liveness detection.
  • Recommended image resolution: ≥ 640×480.
  • Maximum file size: 20 MB.
  • Common error codes:
    • 400 Bad Request – Missing or invalid file input.
    • 415 Unsupported Media Type– Unsupported file type.
    • 502 Bad Gateway – Face analysis microservice unavailable.

iii. Enable Voice Phrase Verification

This API enables you to generate or validate an authentication phrase used for voice-based identity verification. The phrase can include the user’s name (if provided) and is tied to the verification session.

Request Parameters

The following are the request parameters for POST/verify_phrase:
Field Data Type Required Description 
session_id
 String (UUID) Yes Identifier linking this request to the user’s current verification session. 
name
 String No User’s name to personalize the generated phrase (optional).

Method: POST

URL: https://verafi.duckdns.org/verify_phrase

Request Body
{
 "session_id": "uuid-session-id", 
 "name": "John Doe (optional)"
}

Response Parameters

The following are the response parameters for POST/verify_phrase:
Field Data Type Description 
phrase
 String Generated or validated phrase used for voice verification. 
session_id
 String Unique identifier of the verification session.
Response
{
 "phrase": "Please say: Blue sky with clouds", 
 "session_id": "uuid-session-id"
}
Note:
  • If the name parameter is provided, the system may generate a contextual phrase that incorporates the name for more natural speech verification.
  • If called multiple times with the same session, the same phrase is returned to ensure consistency in voice matching.
  • Used in conjunction with liveness and voice verification microservices.
  • The phrase structure (e.g., “Please say: …”) may vary based on locale or tenant configuration.
  • Common errors:
    • 400 Bad Request – Missing session_id.
    • 404 Not Found – Session ID not found or expired.
    • 500 Internal Server Error – Phrase generation service unavailable.

iv. Enable Face Match Verification

Using this API, you can perform facial comparison between the face extracted from an uploaded identity document and a corresponding live image or video to verify the user identity.

Request Parameters

The following are the request parameters for POST/verify_face:
Field Data Type Required Description 
session_id
 String (UUID) Yes Identifier linking to the verification session that contains both the document and face data.

Method: POST

URL: https://verafi.duckdns.org/verify_face

Request Body
{
 "session_id": "uuid-session-id"
}

Response Parameters

The following are the response parameters for POST/verify_face:
Field Data Type Description 
match_result
 Object Contains the outcome of the facial comparison. 
match_result.is_match
 Boolean Indicates whether the document and live face are considered a match. 
match_result.confidence
 Number Confidence score (0–1) of the similarity between both faces. 
match_result.threshold
 Number Minimum confidence threshold required for a valid match. 
session_id
 String The same session identifier provided in the request.
Response
{
  "match_result": { 
   "is_match": true,
   "confidence": 0.92,
   "threshold": 0.85
  },
 "session_id": "uuid-session-id"
}
Note:
  • Compares face embeddings between OCR-extracted document face and uploaded live image/video.
  • The confidence score must exceed the defined threshold (tenant or system-configured) for a successful match.
  • If ENABLE_FACE_MATCH is disabled in configuration, this endpoint returns a simulated response for testing purposes.
  • Results are logged under the session for audit and compliance tracking.
  • Common errors:
    • 400 Bad Request – Missing or invalid session_id.
    • 404 Not Found – Session or image data not available.
    • 502 Bad Gateway – Face match microservice unavailable.

v. Process Video for Liveness Detection

This API enables you to process video content to perform advanced liveness detection and anti-spoofing analysis. The endpoint determines whether the subject in the video is a real, live person rather than a photo, replay, or synthetic source.

Request Parameters

The following are the request parameters for POST/api/liveness:
Field Data Type Required Description 
video
 File (WEBM) Yes Short video clip containing the user’s live face movements or phrase recitation. 
session_id
 String (UUID) No Identifier linking the request to an existing verification session. Automatically generated if not provided.

Method: POST

URL: https://verafi.duckdns.org/api/liveness

Request Body
{
  "video": "liveness_check.webm",
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response Parameters

The following are the response parameters for POST/api/liveness:
Field Data Type Description 
liveness_result
 Object Contains the result of the liveness detection process. 
liveness_result.is_live
 Boolean Indicates if the detected subject is a real person. 
liveness_result.confidence
 Number Confidence score (0–1) of liveness detection. 
liveness_result.analysis
 String Summary or textual explanation of the detection outcome. 
session_id
 String Identifier of the associated verification session.
Response
{
 "liveness_result": { 
  "is_live": true,
  "confidence": 0.94,
  "analysis": "Real person detected"
 },
"session_id": "uuid-session-id"
}
Note:
  • Video is saved and encrypted as liveness.webm if STORE_VIDEO is enabled.
  • Maximum processing time: 300 seconds (5 minutes).
  • Designed for anti-spoofing checks using motion, texture, and micro-expression analysis.
  • Typically executed after face and document uploads to confirm user authenticity.
  • Supported format: WEBM (preferred for web and mobile clients).
  • Common errors:
    • 400 Bad Request – Missing or corrupted video file.
    • 415 Unsupported Media Type – Unsupported file format.
    • 504 Gateway Timeout – Processing exceeded 300-second limit
    • 502 Bad Gateway – Liveness microservice unavailable.

vi. Process Bank Statement

This API enables you to upload a bank statement PDF for automated transaction extraction, fraud analysis, and verification checks using integrated AI-based financial document processors.

Request Parameters

The following are the request parameters for POST/bank_statement:
Field Data Type Required Description 
file
 File (PDF) Yes PDF file containing the user’s bank statement. 
session_id
 String (UUID) No Identifier for linking this upload to an existing verification session. Auto-generated if not provided.

Method: POST

URL: https://verafi.duckdns.org/bank_statement

Request Body
{
  "file": "bank_statement.pdf",
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response Parameters

The following are the response parameters for POST/bank_statement:
Field Data Type Description 
status
 String Status of processing (e.g., "succeeded"). 
documentType
 String Identifies the processed document as Bank Statement. 
bankName
 String Detected financial institution name. 
accountNumber
 String Masked account number extracted from the document. 
statementPeriod
 Object Date range of the statement. 
transactions
 Array List of extracted transactions with confidence values. 
verificationFlags
 Object Indicates which verification checks were executed. 
verificationSummary
 Object Summarized result of integrity, OFAC, and fraud checks. 
flaggedTransactionDetails
 Object Contains transactions flagged during analysis with severity and reasons. 
flaggingSummary
 Object Summary count of red and yellow flagged transactions. 
fileInfo
 Object Metadata on processed files and storage timestamps.
Response
{
 "status": "succeeded",
 "documentType": "Bank Statement", 
 "bankName": "ABC Bank",
 "accountNumber": "****1234", 
 "statementPeriod": {
  "startDate": "2024-01-01",
  "endDate": "2024-01-31"
 },
 "transactions": [
    {
     "transactionIndex": 0,
     "date": {"value": "2024-01-05", "confidence": 0.98},
     "description": {"value": "ACH Payment", "confidence": 0.95}, "depositAmount": {"value": 1000.00, "confidence": 0.99},
     "withdrawalAmount": {"value": 0, "confidence": 0.99},
     "balance": {"value": 5000.00, "confidence": 0.97}, "flagged": false,
     "flaggedSeverity": null, 
     "flaggedReasons": [],
     "flaggedModules": []
     }
    ],
 "verificationFlags": { 
  "scanned": true,
  "ofacCheck": true,
  "integrityCheck": true, 
  "fraudEngineCheck": true
 },
 "verificationSummary": { 
   "ofac_check": {
    "passed": true,
    "confidence": 0.95,
    "processing_time": 1.23
   },
 "pdf_integrity": { 
  "passed": true,
  "confidence": 0.98,
  "processing_time": 0.45
 },
"fraud_detection": { 
  "passed": true,
  "confidence": 0.92,
  "processing_time": 2.15
 }
},
"flaggedTransactionDetails": { 
  "0": {
   "severity": "yellow",
   "reasons": ["High-value transaction detected"], "modules": ["Fraud Detection"]
  }
 },
 "flaggingSummary": { 
  "total_flagged": 1,
  "red_flagged": 0,
  "yellow_flagged": 1
 },
"fileInfo": {
  "pdfFile": "bank_statement.pdf",
  "jsonFile": "bank_statement_analysis.json", 
  "sessionId": "uuid-session-id",
  "storedAt": "2024-10-10T12:00:00Z"
 }
}
Verification Checks Performed
Check Purpose
PDF Integrity Check Validates PDF structure and detects potential tampering.
OFAC Check Screens transaction parties against the Office of Foreign Assets Control (OFAC) sanctions list.
Fraud Detection Analyzes transaction patterns for anomalies or risk behaviors.
Transaction Flagging
  • Red Severity → Critical (e.g., OFAC match, confirmed fraud).
  • Yellow Severity → Warning (e.g., suspicious transaction patterns).
  • Each flagged transaction includes reasons and modules responsible for flagging.
File Storage

  • Files are stored as:

    • bank_statement.pdf
    • bank_statement_analysis.json

  • Both encrypted if STORE_ID_AND_LICENSE_PHOTO is enabled.

Note:
  • The maximum file size is 25 MB.
  • The supported format is PDF only.
  • The Processing time varies based on statement size and transaction volume.
  • The Typical latency is 5–20 seconds per document.

  • Common errors:

    • 400 Bad Request – Invalid or missing file.
    • 415 Unsupported Media Type – Non-PDF file uploaded.
    • 502 Bad Gateway– Bank statement analysis microservice unavailable.

12. Manage Bank Statement/Transaction Verification

i. Verify Bank Statement

Using this API, you can run end-to-end verification checks on a bank-statement PDF (OFAC, PDF integrity, fraud/anomaly rules). You can also accept the PDF and/or precomputed analysis JSON.

Request Parameters

The following are the request parameters for POST/verification/verify-bank-statement:
Field Data Type Required Description 
file
 File (PDF) No* The bank-statement PDF to verify. Required if analysis_data not provided. 
session_id
 String (UUID) No Associates the verification with an existing session. 
analysis_data
 String (JSON) No* JSON string of prior analysis (e.g., output from /bank_statement). Required if file not provided.

Method: POST

URL: https://verafi.duckdns.org/bank_statement

Request Body
{
  "file": "bank_statement.pdf",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "analysis_data": "
}

Response Parameters

The following are the response parameters for POST/verification/verify-bank-statement:

Response
{
 "status": "success",
 "message": "Verification completed", 
 "data": {
  "verification_flags": { 
   "scanned": true,
   "ofacCheck": true,
   "integrityCheck": true, 
   "fraudEngineCheck": true
  },
  "verification_summary": { 
   "ofac_check": {
    "check_name": "OFAC Sanctions Screening", 
    "passed": true,
    "confidence": 0.95, 
    "details": {},
    "issues": [],
    "processing_time": 1.23
   }
  },
  "flagged_transactions": {}, 
  "flagging_summary": {
   "total_flagged": 0,
   "red_flagged": 0,
   "yellow_flagged": 0
  }
 }
}

ii. Verify PDF Integrity

Using this API, you can verify the integrity of a PDF file.

Request Parameters

The following are the request parameters for POST/verification/verify-pdf-integrity:
Table 6. Body (multipart/form-data)
Field Data Type Required Description
file File (PDF) Yes The PDF to verify.

Method: POST

URL: https://verafi.duckdns.org/verification/verify-pdf-integrity

Request Body
POST /verification/verify-pdf-integrity
Content-Type: multipart/form-data; boundary=----PDFBoundary

------PDFBoundary
Content-Disposition: form-data; name="file"; filename="document.pdf"
Content-Type: application/pdf

<binary PDF content here>
------PDFBoundary--

Response Parameters

The following are the response parameters for POST/verification/verify-pdf-integrity:
Table 7. Top-level fields:
Field Data Type Description 
status
 string Operation result indicator. 
message
 string Human-readable result. 
data
 object Verification payload.
Table 8. data object
Field Data Type Description 
check_name
 string Name of the check performed. 
passed
 boolean True if integrity checks passed. 
confidence
 number (0–1) Confidence score for the result. 
details
 object File-level metadata discovered. 
issues
 array<string> List of detected issues (empty if none). 
processing_time
 number (seconds) Time taken to process. 
timestamp
 string (ISO-8601 UTC) Time the check completed.
Table 9. data.details object
Field Data Type Description 
file_size
 integer (bytes) Size of the uploaded file. 
page_count
 integer Number of pages detected. 
encryption_detected
 boolean Whether the PDF is encrypted. 
signatures_found
 boolean Whether digital signatures are present.
Response
{
 "status": "success",
 "message": "PDF integrity verification completed", 
 "data": {
  "check_name": "PDF Integrity Check", 
  "passed": true,
  "confidence": 0.98, 
  "details": {
   "file_size": 1024000,
   "page_count": 3,
   "encryption_detected": false, 
   "signatures_found": false
  },
  "issues": [],
  "processing_time": 0.45,
  "timestamp": "2024-10-10T12:00:00Z"
 }
}

iii. Verify OFAC Sanctions List

Using this API, you can verify one or more transactions against the OFAC (Office of Foreign Assets Control) sanctions list.

Request Parameters

The following are the request parameters for POST/verification/verify-ofac:
Table 10. Body (multipart/form-data)
Field Data Type Required Description
transactions JSON string Yes JSON-encoded list of transactions to verify against OFAC sanctions list.

Method: POST

URL: https://verafi.duckdns.org/POST/verification/verify-ofac

Request Body
POST /verification/verify-ofac
Content-Type: multipart/form-data; boundary=----OFACBoundary

------OFACBoundary
Content-Disposition: form-data; name="transactions"
Content-Type: application/json

[
  {
    "transaction_id": "TXN001",
    "sender_name": "John Doe",
    "receiver_name": "Acme Corp",
    "amount": 2500,
    "currency": "USD",
    "date": "2024-01-05T10:30:00Z"
  },
  {
    "transaction_id": "TXN002",
    "sender_name": "Maria Alvarez",
    "receiver_name": "Global Trade LLC",
    "amount": 7800,
    "currency": "EUR",
    "date": "2024-01-06T14:10:00Z"
  }
]
------OFACBoundary--

Response Parameters

The following are the request parameters for POST/verification/verify-ofac:
Field Data Type Description 
status
 string API operation result. 
message
 string Summary of verification result. 
data.check_name
 string Name of the check performed. 
data.passed
 boolean Indicates if all transactions passed screening. 
data.confidence
 number Confidence score for verification (0–1). 
data.details.total_checked
 integer Total number of transactions checked. 
data.details.matches_found
 integer Count of matched sanctions. 
data.details.matches
 array List of any matches found. 
processing_time
 number Time taken to process (in seconds). 
timestamp
 string ISO 8601 UTC timestamp.
Response
{
 "status": "success",
 "message": "OFAC verification completed", 
 "data": {
  "check_name": "OFAC Sanctions Screening", 
  "passed": true,
  "confidence": 0.95, 
  "details": {
   "total_checked": 50,
   "matches_found": 0, 
   "matches": []
  },
  "issues": [],
  "processing_time": 1.23,
  "timestamp": "2024-10-10T12:00:00Z"
 }
}

iv. Verify Fraud Detections

This API enables you to run fraud detection analysis on transaction data to identify suspicious or high-risk activities.

Request Parameters

The following are the request parameters for POST/verification/verify-fraud :
Table 11. Body (multipart/form-data)
Field Data Type Required Description
transactions JSON string Yes JSON-formatted array of transaction records to be analyzed for potential fraud.

Method: POST

URL: https://verafi.duckdns.org/verification/verify-fraud

Request Body
POST /verification/verify-fraud
Content-Type: multipart/form-data; boundary=----FraudBoundary

------FraudBoundary
Content-Disposition: form-data; name="transactions"
Content-Type: application/json

[
  {
    "transaction_id": "TXN1001",
    "account_id": "ACC123",
    "amount": 5000,
    "currency": "USD",
    "timestamp": "2024-01-12T09:45:00Z",
    "location": "New York, USA",
    "merchant": "ElectroMart",
    "channel": "Online"
  },
  {
    "transaction_id": "TXN1002",
    "account_id": "ACC123",
    "amount": 9000,
    "currency": "USD",
    "timestamp": "2024-01-12T09:47:00Z",
    "location": "California, USA",
    "merchant": "GadgetHub",
    "channel": "Mobile"
  }
]
------FraudBoundary--

Response Parameters

The following are the response parameters for POST/verification/verify-fraud:
Field Data Type Description 
status
 string API operation status. 
message
 string Human-readable result summary. 
data.check_name
 string Type of verification performed. 
data.passed
 boolean Whether all transactions passed fraud checks. 
data.confidence
 number Confidence score for fraud analysis (0–1). 
data.details.total_analyzed
 integer Total number of transactions analyzed. 
data.details.flagged_count
 integer Number of suspicious transactions detected. 
data.details.flagged_transactions
 array List of flagged transactions with fraud scores and reasons. 
processing_time
 number Time taken to complete processing (seconds). 
timestamp
 string ISO 8601 UTC timestamp for the result.
Response
{
 "status": "success",
 "message": "Fraud detection completed", 
 "data": {
  "check_name": "Fraud Detection", 
  "passed": true,
  "confidence": 0.92, 
  "details": {
   "total_analyzed": 50,
   "flagged_count": 2,
   "flagged_transactions": [
    {
     "transactionIndex": 5,
     "fraud_score": 0.35,
     "reasons": ["Unusual transaction amount", "Off-hours transaction"]
    }
   ]
  },
  "issues": [],
  "processing_time": 2.15,
  "timestamp": "2024-10-10T12:00:00Z"
 }
}

v. Retrieve Verification Status

This API enables you to retrieve the list of available verification checks and their current operational status. For this API, authentication is required.

Request Parameters

The following are the request parameters for POST/verification/verification-status:
Field Data Type Required Description 
Authorization
 String Yes Authentication token (e.g., Bearer <token>).

Method: POST

URL: https://verafi.duckdns.org/verification/verification-status

Request Body
POST /verification/verification-status
Authorization: Bearer <your_token_here>

Response Parameters

The following are the response parameters for POST/verification/verification-status:
Field Data Type Description 
status
 string Indicates whether the request was successful. 
message
 string Describes the outcome of the request. 
data.available_checks
 array<string> List of available verification modules or checks that can be executed. 
data.total_checks
 integer Total number of checks currently available. 
data.timestamp
 string UTC timestamp when the status was generated (ISO 8601 format).
Response
{
 "status": "success",
 "message": "Verification status retrieved", 
 "data": {
  "available_checks": [ 
   "pdf_integrity",
   "ofac_check",
   "fraud_detection"
  ],
 "total_checks": 3,
 "timestamp": "2024-10-10T12:00:00Z"
 }
}

vi. Validate Verification System

This API enables you to run a simple test to confirm the verification system is operational and responding correctly using sample data.
Note:
The API internally uses predefined test data to simulate a standard verification process.

Request Parameters

The following are the request parameters for POST/verification/test-verification:
Field Data Type Required Description 
Authorization
 String Yes Authentication token (e.g., Bearer <token>).

Method: POST

URL: https://verafi.duckdns.org/verification/test-verification

Request Body
POST /verification/test-verification
Authorization: Bearer <your_token_here>

Response Parameters

The following are the response parameters for POST/verification/test-verification:
Field Data Type Description 
status
 string Indicates overall operation status. 
message
 string Describes the outcome of the test verification. 
results.verification_flags
 object Placeholder for test result flags (empty in test mode). 
results.verification_summary
 object Placeholder summarizing the simulated verification (empty in test mode).
Response
{
 "status": "success",
 " message": "Verification test completed", 
 "results": {
  "verification_flags": {}, 
  "verification_summary": {}
 }
}

13. Manage OTP Services

i. Send OTP Via SMS Messaging Service

Using this API, you can transmit a One-Time Password (OTP) to a specified phone number via an integrated SMS messaging service.

Request Parameters

The following are the request parameters for POST/send-otp:
Field Data Type Required Description Example 
phone_number
 string Yes Recipient’s phone number without the country code. "9876543210" 
country_code
 string Yes Country calling code in E.164 format (includes “+”). "+91"

Method: POST

URL: https://verafi.duckdns.org/send-otp

Request Body
{
 "phone_number": "1234567890",
 "country_code": "+1"
}

Response Parameters

The following are the response parameters for POST/send-otp:
Field Data Type Required Description Example 
success
 boolean Yes Indicates if the OTP request succeeded. true 
message
 string Yes Describes the operation outcome. "OTP sent successfully" 
data.phone_number
 string Yes Full recipient number with country code. "+919876543210" 
data.expires_in
 string Yes Time window during which OTP remains valid. "5 minutes"
Response
{
 "success": true,
 "message": "OTP sent successfully", 
 "data": {
  "phone_number": "+11234567890",
  "expires_in": "5 minutes"
 }
}
Note:
  • Delivery Service:
    • Powered by Twilio SMS gateway.
    • Message content is templated and localized by region (if configured).
  • Expiry Duration:
    • Each OTP expires after 5 minutes.
    • Expired OTPs must be re-requested.
  • Rate Limiting:
    • 1 request every 2 minutes per phone number.
    • 3 maximum verification attempts allowed per OTP.
  • Use Cases:

    Ideal for account verification, password reset, or two-factor authentication (2FA).

  • Error Handling:
    • 400 Bad Request: Invalid number or missing parameters.
    • 429 Too Many Requests: Rate limit exceeded.
    • 500 Internal Server Error: SMS gateway (Twilio) failure or system issue.

ii. Verify SMS OTP

Using this API, you can validate an SMS One-Time Password (OTP) submitted by the user for authentication or verification. This API also supports retry limits and returns remaining attempts on failure.

Request Parameter

The following are the request parameters for POST/verify-otp:
Field Data Type Required Description 
phone_number
 String Yes User’s phone number (without country code). 
country_code
 String Yes Country code prefix (e.g., +1 for the USA). 
otp
 String Yes The 6-digit One-Time Password received via SMS.

Method: POST

URL: https://verafi.duckdns.org/verify-otp

Request Body
{
 "phone_number": "1234567890",
 "country_code": "+1",
 "otp": "123456"
}

Response Parameters

The following are the response parameters for POST/verify-otp:
Field Data Type Description 
success
 Boolean Indicates whether OTP validation was successful. 
message
 String Descriptive success message. 
data
 Object Additional verification metadata. 
data.phone_number
 String Fully qualified phone number including country code. 
data.verified_at
 String (ISO 8601) Timestamp of OTP verification.

Response

When it's a success:
{
 "success": true,
 "message": "OTP verified successfully", 
 "data": {
  "phone_number": "+11234567890",
  "verified_at": "2024-01-01T12:00:00Z"
 }
}
When it's an error:
{
 "detail": "Invalid OTP. 2 attempts remaining."
}

iii. Send OTP Via Email.

This API enables you to send a One-Time Password (OTP) to the specified email address for user authentication, login, or verification purposes.

Request Parameters

The following are the request parameters for POST/send-email-otp:
Field Data Type Required Description 
email
 String Yes The recipient’s email address to which the OTP will be sent.

Method: POST

URL: https://verafi.duckdns.org/send-email-otp

Request Body
{
 "email": "user@example.com"
}

Response Parameters

The following are the response parameters for POST/send-email-otp:
Field Data Type Description 
success
 Boolean Indicates whether the OTP was sent successfully. 
message
 String Descriptive message confirming OTP delivery. 
data
 Object Contains additional delivery information. 
data.email
 String The recipient email address. 
data.expires_in
 String Duration after which the OTP expires (default: 5 minutes).
Response
{
 "success": true,
 "message": "Email OTP sent successfully", 
 "data": {
  "email": "user@example.com", 
  "expires_in": "5 minutes"
 }
}
Note:
  • Uses Gmail sender configuration for outbound email delivery.
  • Rate limiting: 1 OTP request per 2 minutes per user/email.
  • Expiry: OTPs expire automatically after 5 minutes.
  • OTPs are securely hashed and validated server-side (never stored in plain text).
  • Common errors:
    • 400 Bad Request – Invalid or missing email address.
    • 429 Too Many Requests – Rate limit exceeded.
    • 500 Internal Server Error – Email service or mail gateway unavailable.

iv. Verify Email OTP

Using this API, you can validate the email-based One-Time Password (OTP) submitted by the user for authentication or verification workflows such as login, password reset, or email confirmation.

Request Parameters

The following are the request parameters for POST/verify-email-otp:
Field Data Type Required Description 
email
 String Yes The user’s email address used to receive the OTP. 
otp
 String Yes The 6-digit OTP code sent to the user’s email.

Method: POST

URL: https://verafi.duckdns.org/verify-email-otp

Request Body
{
 "email": "user@example.com", 
 "otp": "123456"
}

Response Parameters

The following are the response parameters for POST/verify-email-otp:
Field Data Type Description 
success
 Boolean Indicates whether the OTP verification was successful. 
message
 String Confirmation message indicating successful validation. 
data
 Object Contains additional verification details. 
data.email
 String The verified email address. 
data.verified_at
 String (ISO 8601) Timestamp of OTP verification completion.
Response
{
 "success": true,
 "message": "Email OTP verified successfully", 
 "data": {
  "email": "user@example.com",
  "verified_at": "2024-01-01T12:00:00Z"
 }
}

v. Retrieve OTP Resend Time Duration (SMS)

This API enables you to retrieve the remaining cooldown time before a new OTP (One-Time Password) can be resent to the specified phone number.

Request Parameters

The following are the request parameters for GET/resend-timer/{phone_number}?country_code=+1:
Field Data Type Required Description 
phone_number
 String Yes User’s phone number (without country code). 
country_code
 String Yes Country code prefix (e.g., +1 for USA).

Method: GET

URL: https://verafi.duckdns.org/resend-timer/%7Bphone_number/country_code=+1

Request Body
GET /resend-timer/{phone_number}?country_code=+1

Response Parameters

The following are the response parameters for GET/resend-timer/{phone_number}?country_code=+1:
Field Data Type Description 
success
 Boolean Indicates whether the query was successful. 
data
 Object Contains resend eligibility and timer details. 
data.can_resend
 Boolean Specifies if a new OTP can be sent (true = allowed, false = cooldown active). 
data.remaining_seconds
 Integer Number of seconds remaining before another OTP can be requested. 
data.remaining_time
 String Formatted time (minutes:seconds) until resend is available.
Response
{
 "success": true, 
 "data": {
  "can_resend": false, 
  "remaining_seconds": 90,
  "remaining_time": "1:30"
 }
}

vi. Retrieve OTP Resend Time Duration (Email)

This API enables you to retrieve the remaining cooldown duration before a new email-based One-Time Password (OTP) can be resent to the specified email address.

Request Parameters

The following are the request parameters for GET/email-resend-timer/{email}:
Field Data Type Required Description
email String Yes The user’s email address used for OTP delivery.

Method: GET

URL: https://verafi.duckdns.org/email-resend-timer/%7Bemail%7D

Request Body
GET/email-resend-timer/{email}

Response Parameters

The following are the response parameters for GET/email-resend-timer/{email}:
Field Data Type Description 
success
 Boolean Indicates whether the request was successfully processed. 
data
 Object Contains resend timer details. 
data.can_resend
 Boolean Specifies if a new OTP can be resent (true = allowed, false = cooldown active). 
data.remaining_seconds
 Integer Number of seconds left before another OTP can be requested. 
data.remaining_time
 String Formatted time (minutes:seconds) until resend is available.
Response
{
 "success": true, 
 "data": {
  "can_resend": false,
  "remaining_seconds": 90,
  "remaining_time": "1:30"
 }
}

vii. Validate SMS OTPs for Development/Testing

Warning:
These endpoints are intended strictly for internal development and QA environments. They expose sensitive OTP information and must never be enabled in production.

a. Using Phone Number

This API retrieves currently stored SMS OTPs and their associated metadata for debugging and testing.

Request Parameters

The following are the request parameters for GET/debug/otp-storage:
Field Data Type Required Description 
phone_number
 String No Filter OTP records by phone number. If not provided, all stored OTP entries are returned. 
country_code
 String No Country code prefix (e.g., +1). Used together with phone_number when filtering.

Method: GET

URL: https://verafi.duckdns.org/debug/otp-storage

Request Body
GET/debug/otp-storage

Response Parameters

The following are the response parameters for GET/debug/otp-storage:
Field Data Type Description 
<phone_number>
 String Phone number (E.164 format) used to send the OTP. 
otp
 String The stored OTP value (visible for debugging only). 
expires_at
 String (ISO 8601) Expiration timestamp for the OTP. 
attempts
 Integer Number of verification attempts made against this OTP.
Response
{
 "+11234567890": {
  "otp": "123456",
  "expires_at": "2024-10-16T10:05:00Z",
  "attempts": 0
 }
}

b. Using email Id

This API retrieves currently stored email OTPs and their associated metadata for debugging or testing.

Request Parameters

The following are the request parameters for GET/debug/email-otp-stora:
Field Data Type Required Description 
email
 String No Filter OTP records by email address. If not provided, all stored email OTP entries are returned.

Method: GET

URL: https://verafi.duckdns.org/debug/email-otp-storage

Request Body
GET/debug/email-otp-storage

Response Parameters

The following are the response parameters for GET/debug/email-otp-storage:
Field Data Type Description 
<email>
 String Email address used to send the OTP. 
otp
 String The stored OTP value (visible for debugging only). 
expires_at
 String (ISO 8601) Expiration timestamp for the OTP. 
attempts
 Integer Number of verification attempts made against this OTP.
Response
{
 "user@example.com": { 
  "otp": "654321",
  "expires_at": "2024-10-16T10:05:00Z",
  "attempts": 0
 }
}

14. Manage Features

i. Retrieve All Available Features

Using this API, you can retrieve a complete list of all available system features and capabilities, including their identifiers, keys, and activation status. This endpoint is typically used by admin dashboards and subscription management modules to configure feature availability across tiers or tenants.

Request Parameters

The following are the request parameters for GET/subscription-management/features:
Field Data Type Required Description
None — — No request parameters for this API.

Method: GET

URL: https://verafi.duckdns.org/subscription-management/features

Request Body
GET/subscription-management/features

Response Parameters

The following are the response parameters for GET/subscription-management/features:
Field Data Type Description 
status
 String Indicates whether the request was successful (e.g., "success"). 
data
 Array Collection of available features. 
data[].feature_id
 Integer Unique identifier for the feature. 
data[].feature_name
 String Descriptive name of the feature. 
data[].feature_key
 String Unique system key used to reference this feature programmatically. 
data[].is_active
 Boolean Indicates whether the feature is currently active and available for use.
Response
{
 "status": "success", 
 "data": [
  {
   "feature_id": 1,
   "feature_name": "Document Upload", 
   "feature_key": "DOCUMENT_UPLOAD",
   "is_active": true
  }
 ]
}

ii. Retrieve the Parent Features

This API enables you to retrieve the parent-level feature categories that define the overall feature hierarchy in the system. These main features act as the top-level groupings for child features (e.g., verification services, analytics modules, configuration modules).

Request Parameters

The following are the request parameters for GET/subscription-management/features/main:
Field Data Type Required Description
None — — No request parameters for this API.

Method: GET

URL: https://verafi.duckdns.org/subscription-management/features/main

Request Body
GET/subscription-management/features/main

Response Parameters

The following are the response parameters for GET/subscription-management/features/main:
Field Data Type Description 
status
 String Indicates whether the request was successful. 
data
 Array A list of main (parent-level) features. 
data[].main_feature_id
 Integer Unique ID for the main feature. 
data[].feature_key
 String System identifier for the feature group. 
data[].feature_name
 String Display name of the main feature. 
data[].description
 String Description of the feature group. 
data[].is_active
 Boolean Indicates if this feature group is active in the system.
Response
{
 "status": "success", 
 "data": [
  {
   "main_feature_id": 1,
   "feature_key": "VERIFICATION_SERVICES", 
   "feature_name": "Verification Services",
   "description": "Document and identity verification services", 
   "is_active": true
  }
 ]
}
Note:
  • Main features serve as parent categories for all other feature keys.
  • Useful when building subscription tier management dashboards.
  • Often used together with:
    • GET/subscription-management/features
    • GET/subscription-management/features/sub

iii. Retrieve the Child Features

This API enables you to retrieve all the child features associated with a specific main feature category. This allows subscription plans, feature toggles, and UI modules to dynamically load related capabilities.

Request Parameters

The following are the request parameters for GET/subscription-management/features/sub/{main_feature_key}:
Field Data Type Required Description 
main_feature_key
 String Yes The unique key of the parent feature category for which child features must be retrieved.

Method: GET

URL: https://verafi.duckdns.org/subscription-management/features/sub/%7Bmain_feature_key%7D

Request Body
GET/subscription-management/features/sub/{main_feature_key}

Response Parameters

The following are the response parameters for GET/subscription-management/features/sub/{main_feature_key}:
Field Data Type Description 
status
 String Indicates success or failure. 
main_feature
 String Main feature key provided in the request. 
data
 Array List of all child sub-features under this category. 
data[].sub_feature_id
 Integer Unique ID of the sub-feature. 
data[].feature_key
 String System-defined feature key. 
data[].feature_name
 String Human-readable name of the feature. 
data[].description
 String Description of what the sub-feature does. 
data[].is_active
 Boolean Indicates whether the sub-feature is active.
Response
{
 "status": "success",
 "main_feature": "VERIFICATION_SERVICES", 
 "data": [
  {
   "sub_feature_id": 1,
   "feature_key": "DOCUMENT_UPLOAD", 
   "feature_name": "Document Upload",
   "description": "Upload and process identity documents", 
   "is_active": true
  },
  {
   "sub_feature_id": 2,
   "feature_key": "LIVENESS_CHECK",
   "feature_name": "Liveness Detection",
   "description": "Real-time liveness verification", 
   "is_active": true
  }
 ]
}
Note:
  • This endpoint is often used to dynamically load feature hierarchies in subscription configuration screens.
  • Works together with:
    • GET/subscription-management/features
    • GET/subscription-management/features/main

15. Monitor Health and Status

i. Retrieve API Information Basics/Metadata

Using this API, you can retrieve basic API information, confirm API availability, and return system metadata.

Response Parameters

The following are the response parameters for retrieving basic API metadata:
Field Data Type Description 
message
 String Greeting message confirming API availability. 
version
 String Current running version of the AcuFi Backend API.
Response
{
 "message": "Welcome to AcuFi Backend API", 
 "version": "1.0.0"
}
Note:
  • This endpoint is often used for health checks, readiness checks, or verifying successful deployment.
  • No authentication is required.
  • Ideal for uptime monitors like UptimeRobot, Pingdom, Azure Monitor, or GCP Health Checks.

ii. Retrieve API Health Status

Using this API, you can retrieve the operational status of the AcuFi Backend API and confirm that all core services are responsive.

Request Parameters

The following are the request parameters forGET/health:
Field Data Type Required Description
None — — This endpoint does not require any path parameters.

Method: GET

URL: https://verafi.duckdns.org/health

Request Body
GET/health

Response Parameters

The following are the response parameters for GET/health:
Field Data Type Description 
status
 String Shows overall API health state (healthy, degraded, or down). 
message
 String Human-readable description confirming system operation.
Response
{
 "status": "healthy",
 "message": "AcuFi Backend API is running"
}
Note:
  • Used for health monitoring, readiness probes, and liveness checks in deployments (Docker, Kubernetes, cloud load balancers).
  • No authentication is required.
  • This API is recommended as the primary endpoint for uptime checks.