Skip to main content
POST
https://sandbox.finhub.cloud
/
api
/
v2.1
/
customer
/
individual
/
{customerId}
/
verification
Individual Verification API
curl --request POST \
  --url https://sandbox.finhub.cloud/api/v2.1/customer/individual/{customerId}/verification \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: <user-agent>' \
  --header 'X-Forwarded-For: <x-forwarded-for>' \
  --header 'X-Tenant-ID: <x-tenant-id>' \
  --data '
{
  "verificationType": "<string>",
  "verificationData": {
    "documentType": "<string>",
    "documentNumber": "<string>"
  },
  "approvedBy": "<string>",
  "approvalReason": "<string>",
  "approvalLevel": "<string>",
  "notes": "<string>",
  "adminNotes": "<string>"
}
'
{
  "success": true,
  "data": {
    "verificationId": "ver_12345",
    "status": "INITIATED",
    "requiredDocuments": [
      "GOVERNMENT_ID",
      "PROOF_OF_ADDRESS",
      "SOURCE_OF_FUNDS"
    ],
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

​
Individual Verification API

APIs for initiating and managing identity verification processes for individual customers.
Base URL: https://sandbox.finhub.cloud/api/v2.1

​
Verification Flow

1

Initiate

Start verification process and get required documents list
2

Upload Documents

Submit required identity documents
3

Review

Documents reviewed by verification team
4

Complete

Customer activated upon approval

​
Initiate Verification

Starts the verification process and returns required documents for the customer’s category.
For complete details on authentication, compliance headers, and SDK implementation examples, refer to the Standard HTTP Headers reference documentation.

​
Request

​
customerId
string
required
Customer identifier
​
Authorization
string
required
Bearer token for authentication
​
X-Tenant-ID
string
required
Tenant identifier
​
X-Forwarded-For
string
required
Required for Compliance & AuditClient’s originating IP address for KYC compliance trackingExample: 192.168.1.100
​
User-Agent
string
required
Required for Compliance & AuditClient application identifier for security analysisExample: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36

​
Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/individual/cust_12345/verification/initiate" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "X-Forwarded-For: 192.168.1.100" \
  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"

{
  "success": true,
  "data": {
    "verificationId": "ver_12345",
    "status": "INITIATED",
    "requiredDocuments": [
      "GOVERNMENT_ID",
      "PROOF_OF_ADDRESS",
      "SOURCE_OF_FUNDS"
    ],
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

​
Submit Verification

Submits verification data and documents for processing.

​
Request

​
customerId
string
required
Customer identifier
​
verificationType
string
required
Type: STANDARD, ENHANCED, SIMPLIFIED
​
verificationData
object
required
Verification details

​
Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/individual/cust_12345/verification" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "verificationType": "STANDARD",
    "verificationData": {
      "documentType": "PASSPORT",
      "documentNumber": "AB123456"
    }
  }'

{
  "success": true,
  "data": {
    "verificationId": "ver_12345",
    "status": "PENDING_REVIEW",
    "submittedAt": "2024-01-15T10:45:00Z"
  }
}

​
Get Verification Status

Check the current status of a verification process.

​
Code Examples

curl -X GET "https://sandbox.finhub.cloud/api/v2.1/verifications/ver_12345" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

{
  "success": true,
  "data": {
    "verificationId": "ver_12345",
    "status": "PENDING_REVIEW",
    "customerId": "cust_12345",
    "documentsSubmitted": 3,
    "documentsRequired": 3,
    "updatedAt": "2024-01-15T11:00:00Z"
  }
}

​
Approve Verification (Admin)

Admin Only Endpoint: This endpoint requires admin/tenant privileges and is used to approve customer verifications after document review.
After documents are submitted and reviewed, a tenant admin (or power tenant admin for high-risk customers) must approve the verification to allow customer activation.

​
Approval Authority Matrix

Customer Risk LevelRequired ApproverApproval LevelEndpoint
Low RiskAutomated / Tenant AdminTENANT_VERIFIED/verifications/{id}/approve
Medium RiskTenant AdminTENANT_VERIFIED/verifications/{id}/approve
High RiskPower Tenant AdminPOWER_TENANT_VERIFIED/verifications/{id}/approve

​
Endpoint

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

​
Path Parameters

​
verificationId
string
required
Verification ID from the initiation stepExample: ver_abc123def456

​
Headers

​
Authorization
string
required
Bearer token with admin privileges
​
X-Tenant-ID
string
required
Tenant identifier

​
Request Body

​
approvedBy
string
required
Approver identifierValid Values:
  • tenant-admin - For medium-risk customers
  • power-tenant - For high-risk customers
  • User ID - Specific admin user
Example: "tenant-admin"
​
approvalReason
string
Reason for approvalExample: "Documents verified, identity confirmed"
​
approvalLevel
string
required
Approval level grantedValid Values:
  • TENANT_VERIFIED - Standard tenant approval (medium risk)
  • POWER_TENANT_VERIFIED - Enhanced approval (high risk)
Example: "TENANT_VERIFIED"
​
notes
string
Additional notes for the approvalExample: "All documents match, address verified via utility bill"
​
adminNotes
string
Internal admin notes (not visible to customer)Example: "Approved via E2E test automation"

​
Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/verifications/ver_abc123def456/approve" \
  -H "Authorization: Bearer ADMIN_ACCESS_TOKEN" \
  -H "X-Tenant-ID: tenant_cloudvault" \
  -H "Content-Type: application/json" \
  -d '{
    "approvedBy": "tenant-admin",
    "approvalReason": "Documents verified, identity confirmed",
    "approvalLevel": "TENANT_VERIFIED",
    "notes": "All documents match, address verified",
    "adminNotes": "Standard approval - medium risk customer"
  }'

​
Response

{
  "code": 200,
  "message": "Verification approved successfully",
  "data": {
    "verificationId": "ver_abc123def456",
    "status": "APPROVED",
    "approvalLevel": "TENANT_VERIFIED",
    "approvedBy": "tenant-admin",
    "approvedAt": "2026-01-13T10:45:00Z",
    "customerId": "cust_123456",
    "customerStatus": "VERIFIED",
    "nextStep": "ACTIVATION"
  }
}

​
Approval Workflow

1

Documents Submitted

Customer submits all required verification documents via /verifications/{id}/documents
2

Admin Review

Tenant admin reviews documents in admin portal or via API
  • Verify document authenticity
  • Check identity match
  • Validate address proof
  • Confirm source of funds (if required)
3

Approval Decision

Admin makes approval decision based on risk levelMedium Risk: Tenant admin approves with TENANT_VERIFIED
High Risk: Power tenant admin approves with POWER_TENANT_VERIFIED
4

Customer Notified

Customer receives notification of approval status
  • Can proceed to consent acceptance
  • Can proceed to account activation

​
Best Practices

Approval Guidelines:
  1. Document Completeness - Ensure all required documents are uploaded before approval
  2. Identity Verification - Confirm document photos match selfie/video verification
  3. Address Validation - Verify address matches utility bills/bank statements
  4. Risk Assessment - Use appropriate approval level for customer risk profile
  5. Audit Trail - Always include detailed notes for compliance audit trail
High-Risk Customers: Never approve high-risk customers with TENANT_VERIFIED level. They must receive POWER_TENANT_VERIFIED approval from a power tenant admin, or the activation will fail.
Automation: For low-risk customers in non-regulated industries, verification approval can be automated using rule engines that check document quality scores, facial recognition confidence, and address validation results.

​
Verification Statuses

INITIATED

Verification process started

PENDING_DOCUMENTS

Awaiting document uploads

PENDING_REVIEW

Documents submitted, awaiting review

APPROVED

Verification approved - customer active

REJECTED

Verification rejected - see rejection reason

​
Response Codes

CodeDescription
200Verification processed successfully
400Invalid request
404Customer or verification not found
500Internal server error

​
API Schema Reference

For the complete OpenAPI schema specification of this endpoint, including all request and response structures, see the API Schema Mapping document.

Standard Headers

Complete HTTP headers reference for compliance

Individual Registration

Register new individual customers

Document Management

Manage customer documents

Consent Management

Manage customer consents

Individual Activation

Activate customer accounts after verification