Skip to main content
POST
https://sandbox.finhub.cloud
/
api
/
v2.1
/
customer
/
individual
/
{customerId}
/
documents
Individual Documents API
curl --request POST \
  --url https://sandbox.finhub.cloud/api/v2.1/customer/individual/{customerId}/documents \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --header 'User-Agent: <user-agent>' \
  --header 'X-Forwarded-For: <x-forwarded-for>' \
  --header 'X-Tenant-ID: <x-tenant-id>' \
  --data '
{
  "documentType": "<string>",
  "category": "<string>"
}
'
{
  "success": true,
  "data": {
    "documentId": "doc_12345",
    "customerId": "cust_12345",
    "documentType": "GOVERNMENT_ID",
    "status": "UPLOADED",
    "uploadedAt": "2024-01-15T10:30:00Z"
  }
}

​
Individual Documents API

APIs for uploading and managing documents for individual customers.
Base URL: https://sandbox.finhub.cloud

​
Available Operations

Get Documents

GET /customer/individual/{customerId}/documents

Upload Document

POST /customer/individual/{customerId}/documents

​
Upload Document

Uploads a document for an individual customer for KYC/AML verification purposes.
For complete details on authentication, compliance headers, and SDK implementation examples, refer to the Standard HTTP Headers reference documentation.

​
Document Requirements

File Requirements:
  • Maximum file size: 10 MB
  • Supported formats: PDF, JPG, JPEG, PNG
  • Documents must be clear and readable
  • All text must be legible
  • No alterations or modifications allowed

​
Request

​
customerId
string
required
Customer identifier
​
Authorization
string
required
Bearer token for authentication
​
X-Tenant-ID
string
required
Tenant identifier
​
Content-Type
string
required
Must be multipart/form-data for file uploads
​
X-Forwarded-For
string
required
Required for Compliance & AuditClient’s originating IP address for KYC compliance trackingExample: 192.168.1.100
​
User-Agent
string
required
Required for Compliance & AuditClient application identifier for security analysisExample: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36
​
file
file
required
Document file (multipart/form-data)
​
documentType
string
required
Type of document: GOVERNMENT_ID, PROOF_OF_ADDRESS, SOURCE_OF_FUNDS, SELFIE
​
category
string
Document category

​
Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/individual/cust_12345/documents" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "X-Forwarded-For: 192.168.1.100" \
  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" \
  -F "file=@/path/to/passport.pdf" \
  -F "documentType=GOVERNMENT_ID"

{
  "success": true,
  "data": {
    "documentId": "doc_12345",
    "customerId": "cust_12345",
    "documentType": "GOVERNMENT_ID",
    "status": "UPLOADED",
    "uploadedAt": "2024-01-15T10:30:00Z"
  }
}

​
Get Documents

Retrieves all documents for a customer.

​
Request

​
customerId
string
required
Customer identifier
​
category
string
Filter by category
​
page
integer
Page number (default: 0)
​
size
integer
Page size (default: 20)

​
Code Examples

curl -X GET "https://sandbox.finhub.cloud/api/v2.1/customer/individual/cust_12345/documents" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

​
Delete Document

Deletes a specific document.

​
Code Examples

curl -X DELETE "https://sandbox.finhub.cloud/api/v2.1/customer/individual/cust_12345/documents/doc_12345" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

​
Document Types & Requirements

​
Government ID (GOVERNMENT_ID)

Accepted Documents:
  • Passport (preferred for international customers)
  • National ID card
  • Driver’s license (with photo)
Requirements:
  • Must be government-issued
  • Must be valid (not expired)
  • Photo must be clear and readable
  • All text must be legible
  • Full document visible (all corners)

​
Proof of Address (PROOF_OF_ADDRESS)

Accepted Documents:
  • Utility bill (electricity, water, gas)
  • Bank statement
  • Government letter
  • Tax document with address
Requirements:
  • Issued within last 3 months
  • Must show full name matching customer record
  • Must show complete address
  • Issuer logo/letterhead visible

​
Source of Funds (SOURCE_OF_FUNDS)

Accepted Documents:
  • Employment contract
  • Payslips (last 3 months)
  • Tax returns
  • Bank statements showing income
Requirements:
  • Recent (within last 6 months)
  • Shows source of income
  • Amount visible (if applicable)

​
Selfie Photo (SELFIE)

Requirements:
  • Clear face photo
  • Good lighting
  • Face fills frame
  • No filters or alterations
  • Used for liveness check

​
Common Document Errors

​
Error: File Too Large

Problem: 
{
  "code": 400,
  "message": "File size exceeds maximum limit",
  "data": {
    "error": "FILE_SIZE_EXCEEDED",
    "maxSize": "10MB",
    "actualSize": "15MB"
  }
}
Solution: Compress or resize the document to under 10 MB

​
Error: Invalid File Format

Problem: 
{
  "code": 400,
  "message": "Invalid file format",
  "data": {
    "error": "INVALID_FILE_FORMAT",
    "allowedFormats": ["PDF", "JPG", "JPEG", "PNG"],
    "receivedFormat": "DOCX"
  }
}
Solution: Convert document to PDF, JPG, JPEG, or PNG

​
Error: Document Not Readable

Problem: 
{
  "code": 422,
  "message": "Document quality insufficient",
  "data": {
    "error": "DOCUMENT_NOT_READABLE",
    "reason": "Image too blurry or dark"
  }
}
Solution:
  • Take photo in good lighting
  • Ensure document is flat and fully visible
  • Use higher resolution
  • Avoid glare or shadows

​
Best Practices

1

Prepare Documents

  • Scan at 300 DPI minimum
  • Use color scanning for IDs
  • Ensure all corners visible
  • Check file size before upload
2

Verify Quality

  • Check image clarity
  • Verify all text readable
  • Ensure no glare or shadows
  • Confirm document not expired
3

Upload Correctly

  • Use correct document type
  • Include all required headers
  • Handle upload errors gracefully
  • Verify upload success
4

Track Status

  • Check document status after upload
  • Wait for verification review
  • Resubmit if rejected

​
API Schema Reference

For the complete OpenAPI schema specification of this endpoint, including all request and response structures, see the API Schema Mapping document.

​
Response Codes

CodeDescription
200Documents retrieved successfully
201Document uploaded successfully
400Invalid request data (file too large, wrong format)
403Access denied
404Document or customer not found
413Payload too large (>10MB)
422Document quality insufficient
500Internal server error

Standard Headers

Complete HTTP headers reference for compliance

Individual Verification

Initiate and manage verification process

Individual Registration

Register new individual customers

Individual Activation

Activate customer accounts after verification