Upload verification document

curl --request POST \
  --url https://sandbox.finhub.cloud/api/v2.1/verifications/{verificationId}/documents \
  --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 '
{
  "documentType": "PASSPORT",
  "documentCategory": "IDENTITY",
  "fileName": "identity_verification.pdf",
  "filePath": "<string>",
  "mimeType": "application/pdf",
  "fileContent": "JVBERi0xLjQK...",
  "fileSize": 102400,
  "customerId": "ff72a196-426a-4ab3-a2d3-e4c583a9bc88",
  "organizationId": "b4c3d4e7-f8a9-0123-b4c5-d6e7f8a9012b",
  "description": "E2E Test - IDENTITY_VERIFICATION",
  "verificationId": "42cf474d-0914-47f1-895f-54147443d203",
  "context": "E2E Test - IDENTITY_VERIFICATION",
  "document": {
    "fileName": "<string>",
    "mimeType": "<string>",
    "fileContent": "<string>",
    "documentType": "<string>",
    "context": "<string>"
  }
}
'

{
  "code": 200,
  "message": "Verification document uploaded successfully",
  "data": {
    "id": "d7379b5e-f983-4a27-b074-9a5a58cdc9da",
    "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
    "customerId": "ef4a8be6-602b-4b26-b81d-afa7d6d835fd",
    "fileName": "628dd82a-incorporation_cert.pdf",
    "fileType": "CERTIFICATE_OF_INCORPORATION",
    "status": "UPLOADED",
    "contentType": "application/pdf",
    "uploadDate": 1768245720542,
    "uploadedBy": "system",
    "description": "Company registration certificate",
    "verified": false
  }
}

POST

api

v2.1

verifications

{verificationId}

documents

Upload verification document

curl --request POST \
  --url https://sandbox.finhub.cloud/api/v2.1/verifications/{verificationId}/documents \
  --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 '
{
  "documentType": "PASSPORT",
  "documentCategory": "IDENTITY",
  "fileName": "identity_verification.pdf",
  "filePath": "<string>",
  "mimeType": "application/pdf",
  "fileContent": "JVBERi0xLjQK...",
  "fileSize": 102400,
  "customerId": "ff72a196-426a-4ab3-a2d3-e4c583a9bc88",
  "organizationId": "b4c3d4e7-f8a9-0123-b4c5-d6e7f8a9012b",
  "description": "E2E Test - IDENTITY_VERIFICATION",
  "verificationId": "42cf474d-0914-47f1-895f-54147443d203",
  "context": "E2E Test - IDENTITY_VERIFICATION",
  "document": {
    "fileName": "<string>",
    "mimeType": "<string>",
    "fileContent": "<string>",
    "documentType": "<string>",
    "context": "<string>"
  }
}
'

{
  "code": 200,
  "message": "Verification document uploaded successfully",
  "data": {
    "id": "d7379b5e-f983-4a27-b074-9a5a58cdc9da",
    "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
    "customerId": "ef4a8be6-602b-4b26-b81d-afa7d6d835fd",
    "fileName": "628dd82a-incorporation_cert.pdf",
    "fileType": "CERTIFICATE_OF_INCORPORATION",
    "status": "UPLOADED",
    "contentType": "application/pdf",
    "uploadDate": 1768245720542,
    "uploadedBy": "system",
    "description": "Company registration certificate",
    "verified": false
  }
}

Verification Documents

Upload and manage documents required for organization KYB (Know Your Business) verification.

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

Upload Verification Document

Upload a document for an active organization verification process.

Endpoint

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

Path Parameters

verificationId

string

required

Verification UUID from the initiation responseExample: 90fb384c-6404-453d-9001-d15c4e0966e5

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

platform

string

required

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

deviceId

string

required

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

Request Body

documentType

string

required

Type of document being uploadedValid Document Types for Organization KYB:

CERTIFICATE_OF_INCORPORATION — Company registration certificate
ARTICLES_OF_ASSOCIATION — Company bylaws/constitution
SHAREHOLDER_REGISTER — Shareholder registry
DIRECTOR_ID — Director passport/ID
PROOF_OF_ADDRESS — Registered office address proof
BANK_STATEMENT — Last 3 months business bank statements
BENEFICIAL_OWNERSHIP — Beneficial ownership declaration (25%+ ownership)
FINANCIAL_STATEMENTS — Audited accounts (revenue > €1M)
BUSINESS_LICENSE — Industry-specific licenses (regulated sectors)

fileName

string

required

Original filename with extensionExample: "incorporation_cert.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"

customerId

string

Organization customer IDExample: "ef4a8be6-602b-4b26-b81d-afa7d6d835fd"

description

string

Optional description or notes about the documentExample: "Company registration certificate"

Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/verifications/90fb384c-6404-453d-9001-d15c4e0966e5/documents" \
  -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 '{
    "documentType": "CERTIFICATE_OF_INCORPORATION",
    "fileName": "incorporation_cert.pdf",
    "fileContent": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwo+Pg...",
    "mimeType": "application/pdf",
    "customerId": "ef4a8be6-602b-4b26-b81d-afa7d6d835fd",
    "description": "Company registration certificate"
  }'

Response

{
  "code": 200,
  "message": "Verification document uploaded successfully",
  "data": {
    "id": "d7379b5e-f983-4a27-b074-9a5a58cdc9da",
    "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
    "customerId": "ef4a8be6-602b-4b26-b81d-afa7d6d835fd",
    "fileName": "628dd82a-incorporation_cert.pdf",
    "fileType": "CERTIFICATE_OF_INCORPORATION",
    "status": "UPLOADED",
    "contentType": "application/pdf",
    "uploadDate": 1768245720542,
    "uploadedBy": "system",
    "description": "Company registration certificate",
    "verified": false
  }
}

Get Verification Documents

Retrieve all documents for a specific organization verification.

Endpoint

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

Code Examples

curl -X GET "https://sandbox.finhub.cloud/api/v2.1/verifications/90fb384c-6404-453d-9001-d15c4e0966e5/documents" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: e2e-test-device"

{
  "success": true,
  "data": {
    "documents": [
      {
        "documentId": "d7379b5e-f983-4a27-b074-9a5a58cdc9da",
        "documentType": "CERTIFICATE_OF_INCORPORATION",
        "status": "UPLOADED",
        "uploadedAt": "2026-03-14T06:57:00Z"
      },
      {
        "documentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "documentType": "DIRECTOR_ID",
        "status": "VERIFIED",
        "uploadedAt": "2026-03-14T06:58:00Z"
      },
      {
        "documentId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "documentType": "SHAREHOLDER_REGISTER",
        "status": "PENDING_REVIEW",
        "uploadedAt": "2026-03-14T06:59:00Z"
      }
    ]
  }
}

Required Documents for KYB

Document Type	Required For	Description
`CERTIFICATE_OF_INCORPORATION`	All	Proof of company registration
`ARTICLES_OF_ASSOCIATION`	All	Company bylaws/constitution
`SHAREHOLDER_REGISTER`	All	Shareholder registry
`DIRECTOR_ID`	All	Passport/ID for each director
`PROOF_OF_ADDRESS`	All	Registered office address proof
`BANK_STATEMENT`	All	Last 3 months business statements
`BENEFICIAL_OWNERSHIP`	All	UBO form (25%+ ownership)
`FINANCIAL_STATEMENTS`	Large businesses	Audited accounts (revenue > €1M)
`BUSINESS_LICENSE`	Regulated sectors	Industry-specific licenses

File Requirements

Formats: PDF, JPEG, PNG
Max Size: 10MB per file
Encoding: Base64 for JSON upload
Resolution: Minimum 300 DPI for scanned documents
Clarity: All text must be clearly readable

Next Steps

Approve Verification

Admin approval after document review

Accept Consents

Accept required consents

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

Path Parameters

verificationId

string

required

Verification process identifier (UUID)

Example:

"42cf474d-0914-47f1-895f-54147443d203"

Body

application/json

documentType

string

Document type (PASSPORT, PROOF_OF_ADDRESS, CERTIFICATE_OF_INCORPORATION, PROOF_OF_REGISTERED_ADDRESS)

Example:

"PASSPORT"

documentCategory

string

Document category

Example:

"IDENTITY"

fileName

string

Original file name

Example:

"identity_verification.pdf"

filePath

string

Server-side file path (if applicable)

mimeType

string

MIME type of the uploaded file

Example:

"application/pdf"

fileContent

string

Base64-encoded file content

Example:

"JVBERi0xLjQK..."

fileSize

integer<int64>

File size in bytes

Example:

102400

customerId

string

Customer identifier

Example:

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

organizationId

string

Organization identifier (for B2B)

Example:

"b4c3d4e7-f8a9-0123-b4c5-d6e7f8a9012b"

description

string

Document description

Example:

"E2E Test - IDENTITY_VERIFICATION"

verificationId

string

Verification process identifier

Example:

"42cf474d-0914-47f1-895f-54147443d203"

context

string

Upload context or purpose

Example:

"E2E Test - IDENTITY_VERIFICATION"

document

object

Show child attributes

Response

Document uploaded successfully

Standard API response wrapper used by all endpoints

code

integer

HTTP status code

Example:

200

data

object

Response from document upload endpoints

Show child attributes

message

string

Human-readable status message

Example:

"Success"

Verification Initiation Verification Approval

⌘I

Client Categories

Product Suite

Service Models

CoreX Service Model

API Service Model

Hybrid Service Model

Document Upload

Verification Documents

Upload Verification Document

Endpoint

Path Parameters

Headers

Request Body

Code Examples

Response

Get Verification Documents

Endpoint

Code Examples

Required Documents for KYB

File Requirements

Next Steps

Approve Verification

Accept Consents

Headers

Path Parameters

Body

Response

Client Categories

Product Suite

Service Models

CoreX Service Model

API Service Model

Hybrid Service Model

​Verification Documents

​Upload Verification Document

​Endpoint

​Path Parameters

​Headers

​Request Body

​Code Examples

​Response

​Get Verification Documents

​Endpoint

​Code Examples

​Required Documents for KYB

​File Requirements

​Next Steps

Approve Verification

Accept Consents

Headers

Path Parameters

Body

Response

Verification Documents

Upload Verification Document

Endpoint

Path Parameters

Headers

Request Body

Code Examples

Response

Get Verification Documents

Endpoint

Code Examples

Required Documents for KYB

File Requirements

Next Steps