URL: /baas/api/reference/verification-compliance/verification-management

---
title: 'Verification Management API'
description: 'KYC/KYB verification workflows, document uploads, and approvals'
---

# Verification Management API

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

<Info>
  **Base URL:** `https://sandbox.finhub.cloud/api/v2.1/verifications`
  
  **Supported Verification Types:**
  - Individual KYC (4 types available)
  - Organization KYB
</Info>

---

## Verification Workflow

<Steps>
  <Step title="Create Verification">
    Initiate verification request with type and level
  </Step>
  <Step title="Upload Documents">
    Submit required verification documents
  </Step>
  <Step title="Review Process">
    Admin reviews submissions and documents
  </Step>
  <Step title="Approve/Reject">
    Admin makes final decision
  </Step>
  <Step title="Update Customer Status">
    System updates customer verification level
  </Step>
</Steps>

---

## Create Verification Request

Initiate a new verification process for a customer.

### Endpoint

```
POST /api/v2.1/verifications
```

### Headers

<ParamField header="X-Tenant-ID" type="string" required>
  Tenant identifier
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

### Request Body

<ParamField body="customerId" type="string">
  Customer UUID identifier to verify (included when verifying a specific customer)
  
  Example: `5887c98c-b5b1-4234-b819-a4987f54aa77`
</ParamField>

<ParamField body="requestedByTenantId" type="string" required>
  Tenant ID requesting the verification
  
  Example: `d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f`
</ParamField>

<ParamField body="type" type="string" required>
  Verification type
  
  **Valid 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
</ParamField>

<ParamField body="requestedLevel" type="string" required>
  Target verification level
  
  **Valid Values:**
  - `TENANT_VERIFIED` - Tenant-level verification
  - `FINHUB_VERIFIED` - Platform-level verification
</ParamField>

<ParamField body="requestedByUserId" type="string" required>
  User ID initiating the verification
  
  Example: `admin-user`
</ParamField>

<ParamField body="additionalData" type="object">
  Optional metadata for the verification
  
  <Expandable title="additionalData properties">
    <ParamField body="description" type="string">
      Description of the verification request
    </ParamField>
    
    <ParamField body="priority" type="string">
      Priority level: `NORMAL`, `HIGH`, or `URGENT`
    </ParamField>
  </Expandable>
</ParamField>

### Headers

<ParamField header="X-Tenant-ID" type="string" required>
  Tenant identifier
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

<ParamField header="X-Forwarded-From" type="string" required>
  Source identifier for request origin tracking
</ParamField>

<ParamField header="User-Agent" type="string" required>
  Client application identifier — required by the global request filter
</ParamField>

<ParamField header="platform" type="string" required>
  Client platform identifier (e.g., `web`). Also accepted as `sec-ch-ua-platform`
</ParamField>

<ParamField header="deviceId" type="string" required>
  Unique device identifier for session tracking. Also accepted as `X-Device-Id` or `device-id`
</ParamField>

<ParamField header="X-User-ID" type="string">
  User ID initiating the verification (used in B2B flows)
</ParamField>

<ParamField header="X-User-Roles" type="string">
  Comma-separated list of user roles (used in B2B flows)
</ParamField>

### Code Examples

<CodeGroup>
```bash cURL - Identity Verification
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"
    }
  }'
```

```bash cURL - Business Verification
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": "2f6ddd86-9ef1-45b6-a16d-058b3ccf29e4",
    "requestedByTenantId": "d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f",
    "type": "BUSINESS_VERIFICATION",
    "requestedLevel": "TENANT_VERIFIED",
    "requestedByUserId": "admin-user",
    "additionalData": {
      "description": "KYB compliance check",
      "priority": "HIGH"
    }
  }'
```

```javascript JavaScript
const createVerification = async (customerId, type) => {
  const response = await fetch(
    'https://sandbox.finhub.cloud/api/v2.1/verifications',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
        'Authorization': `Bearer ${token}`,
        'X-Forwarded-From': 'e2e-test',
        'User-Agent': 'YourApp/1.0',
        'platform': 'web',
        'deviceId': '356938035643809'
      },
      body: JSON.stringify({
        customerId,
        requestedByTenantId: 'd1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f',
        type,
        requestedLevel: 'TENANT_VERIFIED',
        requestedByUserId: 'admin-user',
        additionalData: {
          description: `${type} check`,
          priority: 'NORMAL'
        }
      })
    }
  );

  return response.json();
};
```

```python Python
def create_verification(customer_id, verification_type):
    url = 'https://sandbox.finhub.cloud/api/v2.1/verifications'
    
    payload = {
        'customerId': customer_id,
        'requestedByTenantId': 'd1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f',
        'type': verification_type,
        'requestedLevel': 'TENANT_VERIFIED',
        'requestedByUserId': 'admin-user',
        'additionalData': {
            'description': f'{verification_type} compliance check',
            'priority': 'NORMAL'
        }
    }
    
    response = requests.post(
        url,
        headers={
            'Content-Type': 'application/json',
            'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
            'Authorization': f'Bearer {token}',
                'X-Forwarded-From': 'e2e-test',
            'User-Agent': 'YourApp/1.0',
            'platform': 'web',
            'deviceId': '356938035643809'
        },
        json=payload
    )
    
    return response.json()
```
</CodeGroup>

### Response

<ResponseExample>
```json 201 - Created
{
  "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
  }
}
```
</ResponseExample>

---

## Upload Verification Document

Upload a document for an active verification process.

### Endpoint

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

### Path Parameters

<ParamField path="verificationId" type="string" required>
  Verification UUID from the create verification response
  
  Example: `42cf474d-0914-47f1-895f-54147443d203`
</ParamField>

### Request Body

<ParamField body="documentType" type="string" required>
  Type of document being uploaded
  
  **Valid 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
</ParamField>

<ParamField body="fileName" type="string" required>
  Original filename with extension
  
  Example: `passport.pdf`
</ParamField>

<ParamField body="fileContent" type="string" required>
  Base64-encoded file content
  
  **Supported Formats:** PDF, JPEG, PNG
  **Max Size:** 10MB
</ParamField>

<ParamField body="mimeType" type="string" required>
  MIME type of the file
  
  Examples: `application/pdf`, `image/jpeg`, `image/png`
</ParamField>

<ParamField body="description" type="string">
  Optional description or notes about the document
</ParamField>

<ParamField body="customerId" type="string">
  Customer ID (for payment verification documents)
</ParamField>

<ParamField body="accountId" type="string">
  Account ID (for payment verification documents)
</ParamField>

<ParamField body="transactionAmount" type="number">
  Transaction amount (for payment verification)
</ParamField>

<ParamField body="currency" type="string">
  Currency code (for payment verification)
</ParamField>

<ParamField body="purpose" type="string">
  Purpose of the document upload
</ParamField>

### Code Example

<CodeGroup>
```bash cURL
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"
  }'
```

```javascript JavaScript
const uploadDocument = async (verificationId, file) => {
  // Convert file to base64
  const base64Content = await fileToBase64(file);
  
  const response = await fetch(
    `https://sandbox.finhub.cloud/api/v2.1/verifications/${verificationId}/documents`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
        'Authorization': `Bearer ${token}`,
        'X-Forwarded-From': 'e2e-test',
        'User-Agent': 'YourApp/1.0',
        'platform': 'web',
        'deviceId': '356938035643809'
      },
      body: JSON.stringify({
        documentType: 'PASSPORT',
        fileName: file.name,
        fileContent: base64Content,
        mimeType: file.type,
        description: 'Customer passport for identity verification'
      })
    }
  );

  return response.json();
};

// Helper function
const fileToBase64 = (file) => {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.readAsDataURL(file);
    reader.onload = () => resolve(reader.result.split(',')[1]);
    reader.onerror = error => reject(error);
  });
};
```
</CodeGroup>

### Response

<ResponseExample>
```json 201 - Created
{
  "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}"
}
```
</ResponseExample>

---

## Approve Verification

Approve a verification request after review.

### Endpoint

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

### Path Parameters

<ParamField path="verificationId" type="string" required>
  Verification UUID to approve
</ParamField>

### Request Body

<ParamField body="notes" type="string">
  Admin notes about the approval decision (used in implementation)
</ParamField>

<ParamField body="approvedBy" type="string" required>
  User ID or name of the approver
  
  Example: `E2E_TEST_ADMIN` or admin user ID
</ParamField>

<ParamField body="adminNotes" type="string">
  Alternative field for admin notes (legacy support)
</ParamField>

<ParamField body="approvalReason" type="string">
  Reason for approval
</ParamField>

### Code Example

<CodeGroup>
```bash cURL
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"
  }'
```

```javascript JavaScript
const approveVerification = async (verificationId) => {
  const response = await fetch(
    `https://sandbox.finhub.cloud/api/v2.1/verifications/${verificationId}/approve`,
    {
      method: 'POST',
      headers: {
        'Accept': 'application/json, text/plain, */*',
        'Content-Type': 'application/json',
        'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
        'Authorization': `Bearer ${token}`,
        'X-Forwarded-From': 'e2e-test',
        'platform': 'web',
        'deviceId': '356938035643809'
      },
      body: JSON.stringify({
        adminNotes: 'All documents verified and authentic',
        approvedBy: 'admin_user_123',
        approvalReason: 'All verification criteria met'
      })
    }
  );

  return response.json();
};
```
</CodeGroup>

### Response

<ResponseExample>
```json 200 - Success
{
  "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"
  }
}
```
</ResponseExample>

---

## Get Verification Status

Retrieve the current status of a verification request.

### Endpoint

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

### Path Parameters

<ParamField path="verificationId" type="string" required>
  Verification UUID
</ParamField>

### Response

<ResponseExample>
```json 200 - Success
{
  "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"
  }
}
```
</ResponseExample>

---

## 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

<Note>
  **Verification Checklist:**
  
  1. ✅ Create verification request first
  2. ✅ Upload all required documents
  3. ✅ Wait for admin review (don't auto-approve)
  4. ✅ Check verification status before allowing operations
  5. ✅ Re-verify periodically (annual review recommended)
</Note>

### 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

---

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Customer Activation" icon="check-circle" href="../customer-apis/individual/activation">
    Activate customer after verification
  </Card>
  
  <Card title="Organization Management" icon="users-round" href="../customer-apis/organization/management">
    Add directors/shareholders for KYB
  </Card>
  
  <Card title="Consent Management" icon="file-text" href="../customer-apis/individual/activation">
    Required consents for verified customers
  </Card>
  
  <Card title="Common Types" icon="book" href="../schemas/common-types">
    Standard data structures
  </Card>
</CardGroup>

---

## Changelog

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