POST
/
api
/
v2.1
/
verifications
{
  "data": {
    "id": "<string>",
    "customerId": "<string>",
    "type": "<string>",
    "status": "<string>",
    "requestedLevel": "<string>",
    "createdAt": "<string>"
  }
}

​
Overview

The Create Verification endpoint initiates various types of verification processes required for customer onboarding and compliance. Different risk levels require different verification types - standard verification for medium-risk clients can be approved by tenant admins, while high-risk clients require power tenant approval.

​
Headers

​
Authorization
string
required
Bearer token for authentication
​
X-Tenant-ID
string
required
Tenant identifier for multi-tenant operations
​
Content-Type
string
required
Must be application/json

​
Request Body

​
customerId
string
required
The ID of the customer to verify
​
requestedByTenantId
string
required
The tenant ID requesting the verification
​
type
string
required
The type of verification to initiate. Options:
  • IDENTITY_VERIFICATION - Basic identity verification
  • DOCUMENT_VERIFICATION - Document authenticity check
  • ENHANCED_DUE_DILIGENCE - For high-risk clients
  • SANCTIONS_CHECK - Sanctions and watchlist screening
​
requestedLevel
string
required
The verification level required:
  • TENANT_VERIFIED - Can be approved by tenant admin (medium-risk)
  • POWER_TENANT_VERIFIED - Requires power tenant approval (high-risk)
​
requestedByUserId
string
required
ID of the user requesting the verification
​
additionalData
object
Additional context for the verification

​
Response

​
data
object
Verification request details

​
Example Request - Medium Risk Client

curl --request POST \
  --url https://api.finhub.cloud/api/v2.1/verifications \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'X-Tenant-ID: fh_api_finsei_ltd_7f957f77' \
  --header 'Content-Type: application/json' \
  --data '{
    "customerId": "cust_123456789",
    "requestedByTenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
    "type": "IDENTITY_VERIFICATION",
    "requestedLevel": "TENANT_VERIFIED",
    "requestedByUserId": "admin-user",
    "additionalData": {
      "notes": "Standard verification for medium-risk client with tenant admin approval capability",
      "priority": "MEDIUM"
    }
  }'
```text`n## Example Request - High Risk Client

```bash
curl --request POST \
  --url https://api.finhub.cloud/api/v2.1/verifications \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'X-Tenant-ID: fh_api_finsei_ltd_7f957f77' \
  --header 'Content-Type: application/json' \
  --data '{
    "customerId": "cust_987654321",
    "requestedByTenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
    "type": "ENHANCED_DUE_DILIGENCE",
    "requestedLevel": "POWER_TENANT_VERIFIED",
    "requestedByUserId": "admin-user",
    "additionalData": {
      "notes": "Enhanced due diligence for high-risk client requiring power tenant approval",
      "priority": "HIGH"
    }
  }'
```text`n## Example Response

```json
{
  "data": {
    "id": "ver_abc123def456",
    "customerId": "cust_123456789",
    "type": "IDENTITY_VERIFICATION",
    "status": "PENDING_DOCUMENTS",
    "requestedLevel": "TENANT_VERIFIED",
    "createdAt": "2025-01-23T10:30:00.000Z"
  }
}
```text`n## Verification Types by Risk Level

| Risk Level | Required Verification Types | Approval Level |
|------------|---------------------------|----------------|
| Low Risk | IDENTITY_VERIFICATION | TENANT_VERIFIED |
| Medium Risk | IDENTITY_VERIFICATION, DOCUMENT_VERIFICATION | TENANT_VERIFIED |
| High Risk | IDENTITY_VERIFICATION, DOCUMENT_VERIFICATION, ENHANCED_DUE_DILIGENCE, SANCTIONS_CHECK | POWER_TENANT_VERIFIED |

## Multiple Verification Types

For comprehensive verification, you can initiate multiple verification types:

```javascript
const verificationTypes = ["IDENTITY_VERIFICATION", "DOCUMENT_VERIFICATION"];

for (const verificationType of verificationTypes) {
  const response = await createVerification({
    customerId: customerId,
    requestedByTenantId: tenantId,
    type: verificationType,
    requestedLevel: "TENANT_VERIFIED",
    requestedByUserId: "admin-user",
    additionalData: {
      notes: `Standard verification for medium-risk client`,
      priority: "MEDIUM"
    }
  });
  
  if (verificationType === "IDENTITY_VERIFICATION") {
    // Store this ID for document uploads
    verificationId = response.data.id;
  }
}
```text`n## Next Steps

After creating a verification request:

1. [Upload Verification Documents](/latest/api-reference/v2.1/verification/upload-documents) - Submit required documents
2. [Check Verification Status](/latest/api-reference/v2.1/verification/get-status) - Monitor verification progress
3. [Approve Verification](/latest/api-reference/v2.1/verification/approve) - Admin approval (if authorized)

## PowerShell Script Example

```powershell
# Initiate verification process based on customer risk level
# Medium-risk clients require standard verification
$verificationTypes = @("IDENTITY_VERIFICATION", "DOCUMENT_VERIFICATION")
$verificationId = $null

foreach ($verificationType in $verificationTypes) {
    try {
        Write-Host "Initiating $verificationType..." -ForegroundColor Cyan
        
        $verificationRequest = @{
            customerId          = $customerId
            requestedByTenantId = $tenantId
            type                = $verificationType
            requestedLevel      = "TENANT_VERIFIED"  # Can be approved by tenant admin
            requestedByUserId   = "admin-user"
            additionalData      = @{
                notes    = "Standard verification for customer with tenant admin approval"
                priority = "MEDIUM"
            }
        }
        
        $verificationUrl = "$baseUrl/api/v2.1/verifications"
        $verificationBody = $verificationRequest | ConvertTo-Json -Depth 5
        
        $verificationResponse = Invoke-RestMethod -Uri $verificationUrl -Method Post -Headers $headers -Body $verificationBody
        
        if ($verificationResponse -and $verificationResponse.data -and $verificationResponse.data.id) {
            $currentVerificationId = $verificationResponse.data.id
            
            # Store the first verification ID for document uploads
            if ($verificationType -eq "IDENTITY_VERIFICATION" -or [string]::IsNullOrEmpty($verificationId)) {
                $verificationId = $currentVerificationId
            }
            
            Write-Host "  ✅ $verificationType initiated successfully (ID: $currentVerificationId)" -ForegroundColor Green
            
            # For high-risk clients, you would also add:
            # - ENHANCED_DUE_DILIGENCE
            # - SANCTIONS_CHECK
            # And set requestedLevel to "POWER_TENANT_VERIFIED"
        }
        else {
            Write-Host "  ⚠️ $verificationType created but no ID returned" -ForegroundColor Yellow
        }
    }
    catch {
        Write-Host "  ❌ Failed to initiate ${verificationType}: $($_.Exception.Message)" -ForegroundColor Red
    }
}

# Save verification ID for document upload
if ($verificationId) {
    Write-Host "Primary verification ID for documents: $verificationId" -ForegroundColor Cyan
}
```text`n## Related Endpoints

- [Upload Verification Documents](/latest/api-reference/v2.1/verification/upload-documents) - Submit documents for verification
- [Get Verification Status](/latest/api-reference/v2.1/verification/get-status) - Check current status
- [List Verifications](/latest/api-reference/v2.1/verification/list-verifications) - View all verifications for a customer