How Documents Work
1
Upload file
First, upload the document file using the Upload File endpoint to get a file ID.
2
Add document
Then, associate the file with the user by calling Add Documents with the file ID, type, subtype, and issued country.
3
KYC approval
Once all required documents are uploaded and verified, submit KYC to trigger review.
Document Attributes
Each document requires three key attributes:| Attribute | Description | Example | 
|---|---|---|
| type | Category of document being uploaded | PASSPORT | 
| subType | Side of document (for multi-sided documents) | FRONT_SIDE | 
| issuedCountry | ISO country code where document was issued | US, GB | 
Document Types
Supported document types vary by user type (individual vs business).Individual Documents
Forindividual user accounts:
| Type | Description | Document Group | 
|---|---|---|
| DRIVERS | Government-issued driver’s license | Identity | 
| ID_CARD | National ID card | Identity | 
| PASSPORT | Passport | Identity | 
| RESIDENCE_PERMIT | Residence permit or visa | Identity | 
| PROOF_OF_ADDRESS | Utility bill, bank statement, lease | Address | 
| SELFIE | Selfie photo for identity verification | Identity | 
Business Documents
Forbusiness user accounts, requirements are organized by document groups. Check your specific rail’s requirements (e.g., USD Rail).
| Type | Description | Document Group | 
|---|---|---|
| INCORPORATION_ARTICLES | Incorporation articles document | legalPresence | 
| INCORPORATION_CERT | Incorporation certificate document | legalPresence | 
| STATE_REGISTRY | State registry document | legalPresence, ownershipStructure, controlStructure | 
| SHAREHOLDER_REGISTRY | Shareholder registry document | ownershipStructure | 
| TRUST_AGREEMENT | Trust agreement document | ownershipStructure, controlStructure | 
| INFORMATION_STATEMENT | Information statement document | ownershipStructure, controlStructure | 
| DIRECTORS_REGISTRY | Directors registry document | controlStructure | 
| PROOF_OF_ADDRESS | Proof of address document | companyDetails | 
Document SubTypes
SubTypes specify which side of a document you’re uploading:| SubType | Use For | 
|---|---|
| FRONT_SIDE | Front of ID card or driver’s license | 
| BACK_SIDE | Back of ID card or driver’s license | 
| SINGLE_SIDE | All other documents (passport, bills, certificates) | 
Multi-sided documents: Only 
ID_CARD and DRIVERS require both FRONT_SIDE and BACK_SIDE. All other document types use SINGLE_SIDE only.Document Groups
Compliance requirements are organized into document groups. Users must satisfy all required groups for KYC approval.Individual Requirements
For individual users, typically required: Identity Group (satisfy with one of):- Driver’s License (front + back)
 - ID Card (front + back)
 - Passport
 - Residence Permit
 
- Utility bill
 - Bank statement
 - Lease agreement
 
Business Requirements
Business document requirements are organized by groups. Requirements vary by rail and jurisdiction. For USD Rail, typically required groups include:- legalPresence (min 1): INCORPORATION_ARTICLES, INCORPORATION_CERT, or STATE_REGISTRY
 - ownershipStructure (min 1): SHAREHOLDER_REGISTRY, TRUST_AGREEMENT, INFORMATION_STATEMENT, or STATE_REGISTRY
 - companyDetails (min 1): PROOF_OF_ADDRESS
 - controlStructure (min 1): DIRECTORS_REGISTRY, TRUST_AGREEMENT, INFORMATION_STATEMENT, or STATE_REGISTRY
 
- Same as individual identity requirements: DRIVERS, ID_CARD, PASSPORT, or RESIDENCE_PERMIT
 
Specific requirements vary by rail and jurisdiction. Check the KYC requirements for your specific use case.
Uploading Documents
Document upload is a two-step process: first upload the file, then associate it with the user.Step 1: Upload File
Upload the document file using the Upload File endpoint. Request:id from the response - you’ll need it in step 2.
Step 2: Add Document
Associate the uploaded file with the user using the Add Documents endpoint. Request:- userId (required): User ID for whom documents are being uploaded
 - type (required): Document type from the supported types list
 - subType (required): 
FRONT_SIDE,BACK_SIDE, orSINGLE_SIDE - issuedCountry (required): ISO 3166-1 alpha-2 country code
 - fileId (required): File ID from step 1
 
For detailed field documentation, see the Add Documents API reference.
File Requirements
Documents must meet these requirements:| Requirement | Specification | 
|---|---|
| File types | PDF, JPG, JPEG, PNG | 
| Max size | 10 MB per file | 
| Resolution | Minimum 300 DPI recommended | 
| Quality | Clear, legible, all corners visible | 
| Color | Color or grayscale (no black & white) | 
Document quality matters: Blurry, cropped, or illegible documents will be rejected. Ensure all text and photos are clearly visible before uploading.
Key Concepts
Satisfying Document Groups
Satisfying Document Groups
KYC approval requires satisfying all document groups:Example for Individual (USD Rail):
- Identity group: Upload ONE of (passport, driver’s license, ID card, residence permit)
 - Address group: Upload ONE of (utility bill, bank statement, lease)
 
- legalPresence group: Upload ONE of (INCORPORATION_ARTICLES, INCORPORATION_CERT, STATE_REGISTRY)
 - ownershipStructure group: Upload ONE of (SHAREHOLDER_REGISTRY, TRUST_AGREEMENT, INFORMATION_STATEMENT, STATE_REGISTRY)
 - companyDetails group: Upload ONE of (PROOF_OF_ADDRESS)
 - controlStructure group: Upload ONE of (DIRECTORS_REGISTRY, TRUST_AGREEMENT, INFORMATION_STATEMENT, STATE_REGISTRY)
 - Owner identity: Upload identity documents for EACH beneficial owner (>25% share)
 
Multi-sided Document Upload
Multi-sided Document Upload
For driver’s licenses and ID cards, upload both sides separately using the two-step process:Upload front side:Upload back side:Both uploads must complete successfully for the document to be considered complete.
Issued Country Importance
Issued Country Importance
The 
issuedCountry field is critical for compliance:- Must match the country that issued the document
 - Use ISO 3166-1 alpha-2 codes (e.g., 
US,GB,CA,DE) - Affects which documents are accepted
 - Used for sanctions screening and compliance checks
 
US- United StatesGB- United KingdomCA- CanadaMX- MexicoBR- Brazil
Document Status
Document Status
Uploaded documents progress through verification:
- PENDING_REVIEW: Document uploaded, awaiting verification
 - APPROVED: Document verified and accepted
 - REJECTED: Document rejected (see rejection reason)
 - EXPIRED: Document expired and needs replacement
 
Proof of Address Requirements
Proof of Address Requirements
Proof of address documents must meet specific criteria:Accepted documents:
- Utility bills (electric, gas, water, internet)
 - Bank statements
 - Lease agreements
 - Government correspondence
 
- Dated within last 3 months
 - Shows full name matching KYC information
 - Shows complete address
 - Issued by reputable organization
 
Sample Code
Here’s a complete document upload workflow for individual KYC:1
Upload identity document
Upload the identity document (passport):
2
Upload proof of address
Upload the proof of address document:
3
Upload driver's license (both sides)
Upload both sides of the driver’s license:
4
Complete KYC workflow
Complete the KYC workflow:
5
Handle webhook for document verification
Handle webhook events for document verification:
Getting Help
- 📧 Email: support@hifi.com
 - 💬 Slack: Message us in our shared Slack channel
 
Related Resources
- Users - Understanding user accounts and KYC status
 - KYC Link - Hosted KYC collection flow
 - Webhooks - Monitor KYC verification status
 - API Reference - Complete endpoint documentation