Create verification

curl --request POST \
  --url https://sandbox.finhub.cloud/api/v2.1/verifications \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: <user-agent>' \
  --header 'X-Forwarded-For: <x-forwarded-for>' \
  --header 'X-Forwarded-From: <x-forwarded-from>' \
  --header 'X-Tenant-ID: <x-tenant-id>' \
  --header 'deviceId: <deviceid>' \
  --header 'platform: <platform>' \
  --data '
{
  "customerId": "ff72a196-426a-4ab3-a2d3-e4c583a9bc88",
  "type": "IDENTITY_VERIFICATION",
  "requestedByUserId": "admin-user",
  "requestedLevel": "TENANT_VERIFIED",
  "organizationId": "b4c3d4e7-f8a9-0123-b4c5-d6e7f8a9012b",
  "verificationId": "<string>",
  "status": "PENDING",
  "verificationType": "IDENTITY_VERIFICATION",
  "userId": "87b3af37-4ac1-402b-a0ea-53cfdc695e02",
  "additionalData": {
    "verificationReason": "E2E Test - IDENTITY_VERIFICATION",
    "priority": "NORMAL"
  }
}
'

{
  "success": true,
  "code": 200,
  "timestamp": "2026-03-14T06:56:52.608Z",
  "message": "Verification process started",
  "data": {
    "id": "42cf474d-0914-47f1-895f-54147443d203",
    "type": "IDENTITY_VERIFICATION",
    "status": "IN_PROGRESS",
    "performedBy": "TENANT",
    "performedById": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
    "verificationLevel": "TENANT_VERIFIED",
    "appliesToSubtenants": false,
    "requiredDocuments": [
      "GOVERNMENT_ID"
    ],
    "startedAt": "2026-03-14T06:56:52.600Z",
    "initiatedBy": "admin-user",
    "additionalData": {
      "description": "E2E Test - IDENTITY_VERIFICATION",
      "priority": "NORMAL"
    },
    "verified": false
  }
}

POST

api

v2.1

verifications

Create verification

curl --request POST \
  --url https://sandbox.finhub.cloud/api/v2.1/verifications \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: <user-agent>' \
  --header 'X-Forwarded-For: <x-forwarded-for>' \
  --header 'X-Forwarded-From: <x-forwarded-from>' \
  --header 'X-Tenant-ID: <x-tenant-id>' \
  --header 'deviceId: <deviceid>' \
  --header 'platform: <platform>' \
  --data '
{
  "customerId": "ff72a196-426a-4ab3-a2d3-e4c583a9bc88",
  "type": "IDENTITY_VERIFICATION",
  "requestedByUserId": "admin-user",
  "requestedLevel": "TENANT_VERIFIED",
  "organizationId": "b4c3d4e7-f8a9-0123-b4c5-d6e7f8a9012b",
  "verificationId": "<string>",
  "status": "PENDING",
  "verificationType": "IDENTITY_VERIFICATION",
  "userId": "87b3af37-4ac1-402b-a0ea-53cfdc695e02",
  "additionalData": {
    "verificationReason": "E2E Test - IDENTITY_VERIFICATION",
    "priority": "NORMAL"
  }
}
'

{
  "success": true,
  "code": 200,
  "timestamp": "2026-03-14T06:56:52.608Z",
  "message": "Verification process started",
  "data": {
    "id": "42cf474d-0914-47f1-895f-54147443d203",
    "type": "IDENTITY_VERIFICATION",
    "status": "IN_PROGRESS",
    "performedBy": "TENANT",
    "performedById": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
    "verificationLevel": "TENANT_VERIFIED",
    "appliesToSubtenants": false,
    "requiredDocuments": [
      "GOVERNMENT_ID"
    ],
    "startedAt": "2026-03-14T06:56:52.600Z",
    "initiatedBy": "admin-user",
    "additionalData": {
      "description": "E2E Test - IDENTITY_VERIFICATION",
      "priority": "NORMAL"
    },
    "verified": false
  }
}

Verification Initiation

Initiate a KYC (Know Your Customer) identity verification process for an individual customer.

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

Create Verification Request

Start a new identity verification process.

Endpoint

POST /api/v2.1/verifications

Headers

X-Tenant-ID

string

required

Tenant identifierExample: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd

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 trackingExample: e2e-test

platform

string

required

Client platform identifier. Also accepted as sec-ch-ua-platformExample: web

deviceId

string

required

Unique device identifier. Also accepted as X-Device-Id or device-idExample: e2e-test-device

Request Body

requestedByTenantId

string

required

Tenant ID requesting the verificationExample: "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd"

type

string

required

Verification typeValid Values:

IDENTITY_VERIFICATION — Basic identity check
DOCUMENT_VERIFICATION — Document authenticity verification
ENHANCED_DUE_DILIGENCE — Enhanced KYC checks
SANCTIONS_CHECK — Sanctions and PEP screening
CUSTOMER_DUE_DILIGENCE — Standard CDD process

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 requestExample: "E2E Test - IDENTITY_VERIFICATION"

priority

string

Priority level: NORMAL, HIGH, or URGENTExample: "NORMAL"

Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/verifications" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: e2e-test-device" \
  -d '{
  "requestedByTenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
  "type": "IDENTITY_VERIFICATION",
  "requestedLevel": "TENANT_VERIFIED",
  "requestedByUserId": "admin-user",
  "additionalData": {
    "description": "E2E Test - IDENTITY_VERIFICATION",
    "priority": "NORMAL"
  }
}'

Response

{
  "success": true,
  "code": 200,
  "timestamp": "2026-03-14T06:56:52.608Z",
  "message": "Verification process started",
  "data": {
    "id": "42cf474d-0914-47f1-895f-54147443d203",
    "type": "IDENTITY_VERIFICATION",
    "status": "IN_PROGRESS",
    "performedBy": "TENANT",
    "performedById": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
    "verificationLevel": "TENANT_VERIFIED",
    "appliesToSubtenants": false,
    "requiredDocuments": [
      "GOVERNMENT_ID"
    ],
    "startedAt": "2026-03-14T06:56:52.600Z",
    "initiatedBy": "admin-user",
    "additionalData": {
      "description": "E2E Test - IDENTITY_VERIFICATION",
      "priority": "NORMAL"
    },
    "verified": false
  }
}

Verification Types for Individual Customers

Type	Purpose	Required Documents
`IDENTITY_VERIFICATION`	Basic identity check	Government ID (passport, national ID)
`DOCUMENT_VERIFICATION`	Document authenticity	Proof of address, ID
`ENHANCED_DUE_DILIGENCE`	Enhanced KYC	Source of funds, beneficial ownership, PEP declaration
`SANCTIONS_CHECK`	PEP & sanctions screening	PEP declaration, proof of address
`CUSTOMER_DUE_DILIGENCE`	Standard CDD	Basic identification

Next Steps

Upload Documents

Upload required verification documents

Approve Verification

Admin approval after document review

Accept Consents

Accept required consents after verification

Headers

User-Agent

string

required

Browser user agent

Example:

"Mozilla/5.0"

X-Forwarded-For

string

required

Client/application Ip address

Example:

"192.168.0.1"

X-Forwarded-From

string

required

Client/application identifier for request source tracking

Example:

"playground"

X-Tenant-ID

string

required

Tenant identifier

Example:

"97e7ff29-15f3-49ef-9681-3bbfcce4f6cd"

X-User-ID

string

Authenticated user identifier

Example:

"87b3af37-4ac1-402b-a0ea-53cfdc695e02"

platform

string

required

Client platform identifier. Also accepted as sec-ch-ua-platform

Example:

"web"

deviceId

string

required

Device identifier

Example:

"e2e-test-device"

Authorization

string

required

Bearer token from admin or customer session creation

Example:

"Bearer <token>"

Body

application/json

customerId

string

required

Example:

"ff72a196-426a-4ab3-a2d3-e4c583a9bc88"

type

enum<string>

required

Available options:

IDENTITY_VERIFICATION,

DOCUMENT_VERIFICATION,

BUSINESS_VERIFICATION

Example:

"IDENTITY_VERIFICATION"

requestedByUserId

string

required

Example:

"admin-user"

requestedLevel

string

required

Example:

"TENANT_VERIFIED"

organizationId

string

Example:

"b4c3d4e7-f8a9-0123-b4c5-d6e7f8a9012b"

verificationId

string

status

string

Example:

"PENDING"

verificationType

string

Example:

"IDENTITY_VERIFICATION"

userId

string

Example:

"87b3af37-4ac1-402b-a0ea-53cfdc695e02"

additionalData

object

Show child attributes

Example:

{
  "verificationReason": "E2E Test - IDENTITY_VERIFICATION",
  "priority": "NORMAL"
}

Response

Verification created successfully

Standard API response wrapper used by all endpoints

code

integer

HTTP status code

Example:

200

data

object

Response from verification endpoints

Show child attributes

message

string

Human-readable status message

Example:

"Success"

Verification & Compliance Document Upload

⌘I

Client Categories

Product Suite

Service Models

CoreX Service Model

API Service Model

Hybrid Service Model

Verification Initiation

Verification Initiation

Create Verification Request

Endpoint

Headers

Request Body

Code Examples

Response

Verification Types for Individual Customers

Next Steps

Upload Documents

Approve Verification

Accept Consents

Headers

Body

Response

Client Categories

Product Suite

Service Models

CoreX Service Model

API Service Model

Hybrid Service Model

​Verification Initiation

​Create Verification Request

​Endpoint

​Headers

​Request Body

​Code Examples

​Response

​Verification Types for Individual Customers

​Next Steps

Upload Documents

Approve Verification

Accept Consents

Headers

Body

Response

Verification Initiation

Create Verification Request

Endpoint

Headers

Request Body

Code Examples

Response

Verification Types for Individual Customers

Next Steps