Verification Management API

Complete verification workflows for KYC (Know Your Customer) and KYB (Know Your Business) compliance.

Base URL: https://sandbox.finhub.cloud/api/v2.1/verificationsSupported Verification Types:

Individual KYC (4 types available)
Organization KYB

Verification Workflow

Create Verification

Initiate verification request with type and level

Upload Documents

Submit required verification documents

Review Process

Admin reviews submissions and documents

Approve/Reject

Admin makes final decision

Update Customer Status

System updates customer verification level

Create Verification Request

Initiate a new verification process for a customer.

Endpoint

POST /api/v2.1/verifications

Headers

X-Tenant-ID

string

required

Tenant identifier

Authorization

string

required

Bearer token for authentication

Content-Type

string

required

Must be application/json

Request Body

customerId

string

Customer UUID identifier to verify (included when verifying a specific customer)Example: 5887c98c-b5b1-4234-b819-a4987f54aa77

requestedByTenantId

string

required

Tenant ID requesting the verificationExample: d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f

type

string

required

Verification typeValid Values:

IDENTITY_VERIFICATION - Basic identity check
DOCUMENT_VERIFICATION - Document authenticity verification
ENHANCED_DUE_DILIGENCE - Enhanced KYC/KYB checks
SANCTIONS_CHECK - Sanctions and PEP screening
CUSTOMER_DUE_DILIGENCE - Standard CDD process
BUSINESS_VERIFICATION - Organization/business verification

requestedLevel

string

required

Target verification levelValid Values:

TENANT_VERIFIED - Tenant-level verification
FINHUB_VERIFIED - Platform-level verification

requestedByUserId

string

required

User ID initiating the verificationExample: admin-user

additionalData

object

Optional metadata for the verification

Show additionalData properties

description

string

Description of the verification request

priority

string

Priority level: NORMAL, HIGH, or URGENT

Headers

X-Tenant-ID

string

required

Tenant identifier

Authorization

string

required

Bearer token for authentication

Content-Type

string

required

Must be application/json

X-Forwarded-From

string

required

Source identifier for request origin tracking

User-Agent

string

required

Client application identifier — required by the global request filter

platform

string

required

Client platform identifier (e.g., web). Also accepted as sec-ch-ua-platform

deviceId

string

required

Unique device identifier for session tracking. Also accepted as X-Device-Id or device-id

X-User-ID

string

User ID initiating the verification (used in B2B flows)

X-User-Roles

string

Comma-separated list of user roles (used in B2B flows)

Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/verifications" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Forwarded-From: e2e-test" \
  -H "User-Agent: YourApp/1.0" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "customerId": "5887c98c-b5b1-4234-b819-a4987f54aa77",
    "requestedByTenantId": "d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f",
    "type": "IDENTITY_VERIFICATION",
    "requestedLevel": "TENANT_VERIFIED",
    "requestedByUserId": "admin-user",
    "additionalData": {
      "description": "New customer onboarding",
      "priority": "NORMAL"
    }
  }'

Response

{
  "success": true,
  "code": 200,
  "timestamp": "2026-01-12T19:22:00.469602400Z",
  "message": "Verification process started",
  "data": {
    "id": "42cf474d-0914-47f1-895f-54147443d203",
    "customerId": "5887c98c-b5b1-4234-b819-a4987f54aa77",
    "type": "IDENTITY_VERIFICATION",
    "status": "IN_PROGRESS",
    "performedBy": "TENANT",
    "performedById": "d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f",
    "verificationLevel": "TENANT_VERIFIED",
    "appliesToSubtenants": false,
    "requiredDocuments": [
      "GOVERNMENT_ID"
    ],
    "startedAt": "2026-01-12T19:22:00.436424200Z",
    "initiatedBy": "admin-user",
    "additionalData": {
      "description": "New customer onboarding",
      "priority": "NORMAL"
    },
    "verified": false
  }
}

Upload Verification Document

Upload a document for an active verification process.

Endpoint

POST /api/v2.1/verifications/{verificationId}/documents

Path Parameters

verificationId

string

required

Verification UUID from the create verification responseExample: 42cf474d-0914-47f1-895f-54147443d203

Request Body

documentType

string

required

Type of document being uploadedValid Document Types:

PASSPORT - Passport document
NATIONAL_ID - National ID card
DRIVERS_LICENSE - Driver’s license
PROOF_OF_ADDRESS - Address verification
BANK_STATEMENT - Bank statement
SOURCE_OF_FUNDS - Source of funds declaration
BENEFICIAL_OWNERSHIP - Beneficial ownership declaration
PEP_DECLARATION - PEP status declaration
PROOF_OF_FUNDS - Proof of funds
INVOICE - Invoice or business document
CERTIFICATE_OF_INCORPORATION - Company registration
SHAREHOLDER_REGISTER - Shareholder registry
DIRECTOR_ID - Director identification

fileName

string

required

Original filename with extensionExample: passport.pdf

fileContent

string

required

Base64-encoded file contentSupported Formats: PDF, JPEG, PNG Max Size: 10MB

mimeType

string

required

MIME type of the fileExamples: application/pdf, image/jpeg, image/png

description

string

Optional description or notes about the document

customerId

string

Customer ID (for payment verification documents)

accountId

string

Account ID (for payment verification documents)

transactionAmount

number

Transaction amount (for payment verification)

currency

string

Currency code (for payment verification)

purpose

string

Purpose of the document upload

Code Example

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/verifications/42cf474d-0914-47f1-895f-54147443d203/documents" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Forwarded-From: e2e-test" \
  -H "User-Agent: YourApp/1.0" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "documentType": "PASSPORT",
    "fileName": "passport.pdf",
    "fileContent": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwo+PgplbmRvYmoKeHJlZgowIDAKdHJhaWxlcgo8PAovUm9vdCAxIDAgUgo+PgolJUVPRgo=",
    "mimeType": "application/pdf",
    "description": "Customer passport for identity verification"
  }'

Response

{
  "code": 200,
  "message": "Verification document uploaded successfully",
  "data": "Document uploaded for verification 42cf474d-0914-47f1-895f-54147443d203: {\"id\":\"d7379b5e-f983-4a27-b074-9a5a58cdc9da\",\"tenantId\":\"d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f\",\"customerId\":\"5887c98c-b5b1-4234-b819-a4987f54aa77\",\"fileName\":\"628dd82a-a698-4d8c-bcb2-a97e78d33397_passport.pdf\",\"fileType\":\"PASSPORT\",\"status\":\"UPLOADED\",\"contentType\":\"application/pdf\",\"contentUrl\":\".\\\\data\\\\documents\\\\d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f\\\\2026\\\\01\\\\12\\\\5887c98c-b5b1-4234-b819-a4987f54aa77\\\\628dd82a-a698-4d8c-bcb2-a97e78d33397_passport.pdf\",\"uploadDate\":1768245720542,\"uploadedBy\":\"system\",\"description\":\"Customer passport for identity verification\",\"verified\":false}"
}

Approve Verification

Approve a verification request after review.

Endpoint

POST /api/v2.1/verifications/{verificationId}/approve

Path Parameters

verificationId

string

required

Verification UUID to approve

Request Body

notes

string

Admin notes about the approval decision (used in implementation)

approvedBy

string

required

User ID or name of the approverExample: E2E_TEST_ADMIN or admin user ID

adminNotes

string

Alternative field for admin notes (legacy support)

approvalReason

string

Reason for approval

Code Example

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/verifications/42cf474d-0914-47f1-895f-54147443d203/approve" \
  -H "Accept: application/json, text/plain, */*" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "adminNotes": "All documents verified and authentic",
    "approvedBy": "admin_user_123",
    "approvalReason": "All verification criteria met"
  }'

Response

{
  "code": 200,
  "message": "Verification approved successfully",
  "data": {
    "level": "TENANT_VERIFIED",
    "approvedBy": "admin-user",
    "approvedAt": "2026-01-12T19:22:00.658560500Z",
    "verificationId": "42cf474d-0914-47f1-895f-54147443d203",
    "status": "APPROVED"
  }
}

Get Verification Status

Retrieve the current status of a verification request.

Endpoint

GET /api/v2.1/verifications/{verificationId}

Path Parameters

verificationId

string

required

Verification UUID

Response

{
  "code": 200,
  "message": "Verification status retrieved successfully",
  "data": {
    "submittedDocuments": 0,
    "completedAt": "2026-01-12T19:22:04.780839500Z",
    "level": "FINHUB_VERIFIED",
    "startedAt": "2026-01-12T19:22:02.894983800Z",
    "type": "SANCTIONS_CHECK",
    "verificationId": "90fb384c-6404-453d-9001-d15c4e0966e5",
    "status": "APPROVED"
  }
}

Verification Types Reference

Type	Purpose	Required Documents	Typical Use Case
`IDENTITY_VERIFICATION`	Basic identity check	Government ID	Individual onboarding
`DOCUMENT_VERIFICATION`	Document authenticity	Proof of address, ID	Address verification
`ENHANCED_DUE_DILIGENCE`	Enhanced KYC	Source of funds, beneficial ownership, PEP	High-risk customers
`SANCTIONS_CHECK`	PEP & sanctions screening	PEP declaration, proof of address	Compliance requirements
`CUSTOMER_DUE_DILIGENCE`	Standard CDD	Basic identification	Standard KYC
`BUSINESS_VERIFICATION`	KYB for organizations	Incorporation docs, shareholder register	Organization onboarding

Document Type Requirements

Individual Customers

IDENTITY_VERIFICATION:

PASSPORT or NATIONAL_ID or DRIVERS_LICENSE

ENHANCED_DUE_DILIGENCE:

SOURCE_OF_FUNDS
BENEFICIAL_OWNERSHIP (if applicable)
PEP_DECLARATION
PROOF_OF_ADDRESS

SANCTIONS_CHECK:

PROOF_OF_ADDRESS
SOURCE_OF_FUNDS
BENEFICIAL_OWNERSHIP
PEP_DECLARATION

Organization Customers

BUSINESS_VERIFICATION:

CERTIFICATE_OF_INCORPORATION
PROOF_OF_ADDRESS
DIRECTOR_ID
SHAREHOLDER_REGISTER

Verification Levels

Level	Description	Verification By
`TENANT_VERIFIED`	Verified by tenant	Tenant admin
`FINHUB_VERIFIED`	Verified by platform	FinHub compliance team

Common Workflows

Individual KYC Workflow

1. Create IDENTITY_VERIFICATION
   ↓
2. Upload PASSPORT document
   ↓
3. Admin reviews and approves
   ↓
4. Create DOCUMENT_VERIFICATION
   ↓
5. Upload PROOF_OF_ADDRESS
   ↓
6. Admin approves
   ↓
7. (Optional) Create ENHANCED_DUE_DILIGENCE for high-risk
   ↓
8. Customer status updated to VERIFIED

Organization KYB Workflow

1. Create BUSINESS_VERIFICATION
   ↓
2. Upload required documents:
   - CERTIFICATE_OF_INCORPORATION
   - DIRECTOR_ID
   - SHAREHOLDER_REGISTER
   - PROOF_OF_ADDRESS
   ↓
3. Admin reviews all documents
   ↓
4. Admin approves verification
   ↓
5. Organization status updated to VERIFIED

Best Practices

Verification Checklist:

✅ Create verification request first
✅ Upload all required documents
✅ Wait for admin review (don’t auto-approve)
✅ Check verification status before allowing operations
✅ Re-verify periodically (annual review recommended)

Document Quality Guidelines

Resolution: Minimum 300 DPI for scanned documents
Format: PDF preferred, JPEG/PNG acceptable
Size: Maximum 10MB per file
Clarity: All text must be clearly readable
Completeness: Full document visible, no cropping

Customer Activation

Activate customer after verification

Organization Management

Add directors/shareholders for KYB

Consent Management

Required consents for verified customers

Common Types

Standard data structures

Changelog

Version	Date	Changes
v2.1	2026-01-13	Initial release

Client Categories

Product Suite

Service Models

CoreX Service Model

API Service Model

Hybrid Service Model

​Verification Management API

​Verification Workflow

​Create Verification Request

​Endpoint

​Headers

​Request Body

​Headers

​Code Examples

​Response

​Upload Verification Document

​Endpoint

​Path Parameters

​Request Body

​Code Example

​Response

​Approve Verification

​Endpoint

​Path Parameters

​Request Body

​Code Example

​Response

​Get Verification Status

​Endpoint

​Path Parameters

​Response

​Verification Types Reference

​Document Type Requirements

​Individual Customers

​Organization Customers

​Verification Levels

​Common Workflows

​Individual KYC Workflow

​Organization KYB Workflow

​Best Practices

​Document Quality Guidelines

​Related Endpoints

Customer Activation

Organization Management

Consent Management

Common Types

​Changelog

Verification Management API

Verification Workflow

Create Verification Request

Endpoint

Headers

Request Body

Headers

Code Examples

Response

Upload Verification Document

Endpoint

Path Parameters

Request Body

Code Example

Response

Approve Verification

Endpoint

Path Parameters

Request Body

Code Example

Response

Get Verification Status

Endpoint

Path Parameters

Response

Verification Types Reference

Document Type Requirements

Individual Customers

Organization Customers

Verification Levels

Common Workflows

Individual KYC Workflow

Organization KYB Workflow

Best Practices

Document Quality Guidelines

Related Endpoints

Changelog