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