Verification Document Management API

Upload and manage verification documents

Verification Document Management API

APIs for uploading and managing documents associated with verification processes.

Available Operations

Get Documents

GET /verifications/{id}/documents

Upload Document

POST /verifications/{id}/documents

Get Verification Documents

Request

verificationId string path required

Verification identifier

Authorization string header required

Bearer token for authentication

X-Tenant-ID string header required

Tenant identifier

X-Forwarded-From string header required

Source identifier for request origin tracking

User-Agent string header required

Client application identifier — required by the global request filter

platform string header required

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

deviceId string header required

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

Code Examples

cURL

bash

curl -X GET "https://sandbox.finhub.cloud/api/v2.1/verifications/ver_12345/documents" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "User-Agent: YourApp/1.0" \
  -H "platform: web" \
  -H "deviceId: 356938035643809"

JavaScript

javascript

const response = await fetch(
  'https://sandbox.finhub.cloud/api/v2.1/verifications/ver_12345/documents',
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
      'X-Forwarded-From': 'e2e-test',
      'User-Agent': 'YourApp/1.0',
      'platform': 'web',
      'deviceId': '356938035643809'
    }
  }
);

const { data } = await response.json();
data.documents.forEach(doc => {
  console.log(`${doc.documentType}: ${doc.status}`);
});

Python

python

import requests

response = requests.get(
    'https://sandbox.finhub.cloud/api/v2.1/verifications/ver_12345/documents',
    headers={
        'Authorization': f'Bearer {access_token}',
        'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
        'X-Forwarded-From': 'e2e-test',
        'User-Agent': 'YourApp/1.0',
        'platform': 'web',
        'deviceId': '356938035643809'
    }
)

data = response.json()['data']
for doc in data['documents']:
    print(f"{doc['documentType']}: {doc['status']}")

Response example

200

json

{
  "success": true,
  "data": {
    "documents": [
      {
        "documentId": "doc_12345",
        "documentType": "GOVERNMENT_ID",
        "status": "VERIFIED",
        "uploadedAt": "2024-01-15T10:30:00Z"
      },
      {
        "documentId": "doc_67890",
        "documentType": "PROOF_OF_ADDRESS",
        "status": "PENDING_REVIEW",
        "uploadedAt": "2024-01-15T10:35:00Z"
      }
    ]
  }
}

Upload Verification Document

Request

verificationId string path required

Verification identifier

documentType string query required

Type of document: GOVERNMENT_ID, PROOF_OF_ADDRESS, SELFIE, etc.

documentId string query

Optional document ID (for re-uploads)

Authorization string header required

Bearer token for authentication

X-Tenant-ID string header required

Tenant identifier

X-User-Id string header

Uploading user ID

file file body required

Document file (multipart/form-data)

category string body

Document category

Code Examples

cURL

bash

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/verifications/ver_12345/documents?documentType=GOVERNMENT_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "User-Agent: YourApp/1.0" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -F "file=@/path/to/passport.pdf"

JavaScript

javascript

const formData = new FormData();
formData.append('file', documentFile);

const response = await fetch(
  'https://sandbox.finhub.cloud/api/v2.1/verifications/ver_12345/documents?documentType=GOVERNMENT_ID',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
      'X-Forwarded-From': 'e2e-test',
      'User-Agent': 'YourApp/1.0',
      'platform': 'web',
      'deviceId': '356938035643809'
    },
    body: formData
  }
);

const { data } = await response.json();
console.log('Document ID:', data.documentId);
console.log('Status:', data.status);

Python

python

import requests

with open('/path/to/passport.pdf', 'rb') as f:
    response = requests.post(
        'https://sandbox.finhub.cloud/api/v2.1/verifications/ver_12345/documents',
        params={'documentType': 'GOVERNMENT_ID'},
        headers={
            'Authorization': f'Bearer {access_token}',
            'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
                'X-Forwarded-From': 'e2e-test',
            'User-Agent': 'YourApp/1.0',
            'platform': 'web',
            'deviceId': '356938035643809'
        },
        files={'file': f}
    )

data = response.json()['data']
print(f"Document ID: {data['documentId']}")

Response example

201

json

{
  "success": true,
  "data": {
    "documentId": "doc_11111",
    "verificationId": "ver_12345",
    "documentType": "GOVERNMENT_ID",
    "status": "UPLOADED",
    "uploadedAt": "2024-01-15T10:30:00Z"
  }
}

400

json

{
  "success": false,
  "error": {
    "code": "INVALID_FILE",
    "message": "File type not supported. Allowed: PDF, JPG, PNG"
  }
}

Document Types

Type	Description
`GOVERNMENT_ID`	Passport, national ID, driver’s license
`PROOF_OF_ADDRESS`	Utility bill, bank statement (< 3 months)
`SOURCE_OF_FUNDS`	Income proof, tax returns
`SELFIE`	Customer selfie for liveness check
`CERTIFICATE_OF_INCORPORATION`	Company registration
`BENEFICIAL_OWNER_DECLARATION`	UBO declaration

Document Statuses

Status	Description
`UPLOADED`	Document uploaded
`PENDING_REVIEW`	Awaiting review
`VERIFIED`	Document verified
`REJECTED`	Document rejected

Response Codes

Code	Description
`200`	Documents retrieved successfully
`201`	Document uploaded successfully
`400`	Invalid request data
`404`	Verification not found
`500`	Internal server error