> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hifi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# KYC
> To comply with financial regulations, HIFI enforces KYC (Know Your Customer) checks before an individual User can receive funds from fiat (onramps), pay out to fiat (offramps), or access other financial products offered by HIFI.
## Information Required
Different information is required for verification, including both non-documentary and documentary checks.
### Profile
| Field | Description | Required |
| :---------------- | :------------------------------------------------------------ | :------- |
| `firstName` | Legal first name | Yes |
| `lastName` | Legal last name | Yes |
| `dateOfBirth` | Date of birth (YYYY-MM-DD) | Yes |
| `email` | Contact email address | Yes |
| `phoneNumber` | Phone number with country code | Yes |
| `physicalAddress` | Residential address (line1, city, state, postalCode, country) | Yes |
| `taxId` | Tax identification number in the user's country | Yes |
| `taxIdType` | Tax identification number (e.g. SSN, ITIN) | No |
| `taxIdCountry` | Tax identification number issuance country | No |
| `nationality` | User's nationality | Yes |
### Documentation
For more details check [Documents](/v3/core/compliance/documents)
| Document Group | Accepted Type | Required |
| :----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `identity` | `DRIVERS`, `ID_CARD`, `PASSPORT`, `RESIDENCE_PERMIT` | Yes |
| `proofOfResidence` | `UTILITY_BILL`, `BANK_STATEMENT`, `RENTAL_AGREEMENT`, `TAX_DOCUMENT`, `VOTER_REGISTRATION_CARD`, `BANK_REFERENCE_LETTER`, `LEASE_OR_TENANCY_AGREEMENT`, `PROOF_OF_ADDRESS` | Yes\* |
For US and Canadian users, proof of address is optional if a driver's license, national ID, or resident permit is submitted as the government-issued ID.
`proofOfResidence` needs to be issued within the **last 3 months**
## Questionnaire (Optional)
| Field | Description |
| :--------------------------------- | :------------------------------------------------ |
| `employmentStatus` | The user's current employment status |
| `sourceOfFunds` | The primary source of the user's funds |
| `primaryPurpose` | The user's primary purpose for using the platform |
| `expectedMonthlyTransactionVolume` | Expected monthly transaction volume in USD |
| `expectedMonthlyTransactionCount` | Expected number of transactions per month |
| `highRiskActivities` | Any high-risk activities the user engages in |
| `actsOnBehalfOfThirdParty` | Whether the user acts on behalf of a third party |
| `actsOnBehalfOfThirdPartyDetails` | Details about the third party, if applicable |
## Example: Full KYC Flow
Update user's non-documentary information
**Request**
```shellscript theme={null}
curl -X PATCH "https://sandbox.hifi.com/v3/users/usr_4o0ZDdLcfxmB6OyzUEVNq/compliance/profile" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"firstName": "Henry",
"lastName": "Wu",
"dateOfBirth": "1998-03-29",
"email": "henry@hifi.com",
"phoneNumber": "+18572719480",
"physicalAddress": {
"addressLine1": "Example St 1.",
"city": "Hoboken",
"stateProvinceRegion": "NJ",
"postalCode": "07030",
"country": "USA"
},
"taxId": "23423123",
"nationality": "USA",
}'
```
**Response**
```json theme={null}
{
"userId": "usr_4o0ZDdLcfxmB6OyzUEVNq",
"type": "INDIVIDUAL",
"firstName": "Henry",
"middleName": null,
"lastName": "Wu",
"nationality": "USA",
"email": "henry@hifi.com",
"phoneNumber": "*******9480",
"physicalAddress": {
"addressLine1": "Example St 1.",
"addressLine2": null,
"city": "Hoboken",
"stateProvinceRegion": "NJ",
"postalCode": "07030",
"country": "USA"
},
"dateOfBirth": "1998-03-29",
"gender": null,
"taxId": "****3123",
"taxIdType": null,
"taxIdCountry": null,
"createdAt": "2026-07-13T22:12:26.802Z",
"updatedAt": "2026-07-13T22:12:37.242Z"
}
```
Upload the documentation to fulfill both the ID and proof of address requirements
Use the File endpoint to upload the file first, then add the documentation to the user with the returned file ID (e.g. `file_xxxxxxxxxxxx`).
#### Government Issued ID
**Request**
```shellscript theme={null}
curl -X POST "https://sandbox.hifi.com/v3/users/usr_4o0ZDdLcfxmB6OyzUEVNq/compliance/documents" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "PASSPORT",
"subType": "SINGLE_SIDE",
"issuedCountry": "USA",
"issuedDate": "2024-05-04", // optional
"expiryDate": "2030-05-04", // optional
"fileId": "file_O8A1X7gCKoYxlb2aMYYzK"
}'
```
**Response**
```json theme={null}
{
"id": "doc_lPeFxGI2dAVFvLV2g7b33",
"userId": "usr_TpCyt0c8PeZveAsmddulu",
"associatedPartyId": null,
"type": "PASSPORT",
"subType": "SINGLE_SIDE",
"issuedCountry": "USA",
"issuedDate": "2024-05-04",
"expiryDate": "2030-05-04",
"number": null,
"fileId": "file_O8A1X7gCKoYxlb2aMYYzK",
"description": null,
"isValid": null,
"message": null,
"createdAt": "2026-07-13T22:13:44.870Z",
"updatedAt": "2026-07-13T22:13:44.870Z"
}
```
If the document has two sides, submit both, using `FRONT_SIDE` and `BACK_SIDE` for the `subType`.
#### Proof of Address
**Request**
```shellscript theme={null}
curl -X POST "https://sandbox.hifi.com/v3/users/usr_4o0ZDdLcfxmB6OyzUEVNq/compliance/documents" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "UTILITY_BILL",
"subType": "SINGLE_SIDE",
"issuedCountry": "USA",
"issuedDate": "2024-05-04", // optional
"expiryDate": "2030-05-04", // optional
"fileId": "file_ofidSSDFHS7538ffbje9"
}'
```
**Response**
```json theme={null}
{
"id": "doc_lPeFxGI2dAVFvLV2g7b33",
"userId": "usr_TpCyt0c8PeZveAsmddulu",
"associatedPartyId": null,
"type": "UTILITY_BILL",
"subType": "SINGLE_SIDE",
"issuedCountry": "USA",
"issuedDate": "2024-05-04",
"expiryDate": "2030-05-04",
"number": null,
"fileId": "file_ofidSSDFHS7538ffbje9",
"description": null,
"isValid": null,
"message": null,
"createdAt": "2026-07-13T22:13:44.870Z",
"updatedAt": "2026-07-13T22:13:44.870Z"
}
```
For US and Canadian users, if a driver's license, national ID, or resident permit has already been submitted as the government-issued ID, no additional proof of address is needed.
**Request**
```shellscript theme={null}
curl -X PATCH "https://sandbox.hifi.com/v3/users/usr_4o0ZDdLcfxmB6OyzUEVNq/compliance/questionnaire" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"employmentStatus": "employed",
"sourceOfFunds": "employment_income",
"primaryPurpose": "goods_and_services",
"expectedMonthlyTransactionVolume": "0_20000",
"expectedMonthlyTransactionCount": "10_100",
"highRiskActivities": ["none"],
"actsOnBehalfOfThirdParty": true,
"actsOnBehalfOfThirdPartyDetails": "blah blah blah"
}'
```
**Response**
```json theme={null}
{
"userId": "usr_TpCyt0c8PeZveAsmddulu",
"type": "INDIVIDUAL",
"employmentStatus": "employed",
"expectedMonthlyTransactionVolume": "0_20000",
"expectedMonthlyTransactionCount": "10_100",
"highRiskActivities": [
"none"
],
"primaryPurpose": "goods_and_services",
"primaryPurposeDetails": null,
"sourceOfFunds": "employment_income",
"sourceOfFundsDetails": null,
"actsOnBehalfOfThirdParty": true,
"actsOnBehalfOfThirdPartyDetails": "blah blah blah",
"createdAt": "2026-07-13T22:12:26.766Z",
"updatedAt": "2026-07-13T22:12:41.585Z"
}
```
Once all the required information is updated, submit the application for compliance review
**Request**
```shellscript theme={null}
curl -X POST "https://sandbox.hifi.com/v3/users/usr_4o0ZDdLcfxmB6OyzUEVNq/compliance/check" \
-H "Authorization: Bearer YOUR_API_KEY" \
```
**Response**
```json theme={null}
{
"userId": "usr_TpCyt0c8PeZveAsmddulu",
"complianceStatus": "PENDING",
"message": null,
"rfiActions": []
}
```
Listen to our webhook or polling the user's compliance status
**Request**
```shellscript theme={null}
curl -X GET "https://sandbox.hifi.com/v3/users/usr_9RJb0KUrhugQ7uMZL5UML/compliance/status" \
-H "Authorization: Bearer YOUR_API_KEY"
```
**Response**
```json theme={null}
{
"userId": "usr_TpCyt0c8PeZveAsmddulu",
"complianceStatus": "APPROVED",
"message": null,
"rfiActions": []
}
```
## Expected Behavior
After submission, the application has the following possible states:
**What's next:**
Wait for corridor functionality to be unlocked for the user. The timing may vary, and based on the customer profile, the user may not be eligible for all corridors.
?
The application is currently under review by our compliance team.
**What you can expect:**
* An RFI may be sent to your compliance mailbox requesting additional information
* The status may move to `REQUIRES_INFO` after our compliance check — use GET `/v3/users/:user_id/compliance/status` to see what additional information is required
* The status may move to `REJECTED` or `APPROVED` when a final decision is made by our compliance team
Our compliance team has determined that we cannot onboard this user. Reach out to our support team for more information.
Our compliance team has requested updates to the applicant's data before resubmission. Common reasons include: a mismatched address on the proof of address, blurry documentation, or an incorrectly formatted document.
For more details, check the `rfiActions` field after calling GET `/v3/users/:user_id/compliance/status`.
**Example**
```json theme={null}
{
"userId": "usr_CchuBDCeCm1FvoEWWl6rw",
"complianceStatus": "REQUIRES_INFO",
"onboardingStatus": "NOT_STARTED",
"message": "Enter your full name exactly as it appears on your identity document.",
"rfiActions": [
{
"type": "UPDATE_PROFILE",
"fields": [
"firstName",
"lastName"
],
"message": "Please update the full name in your profile to match the document."
},
{
"type": "UPLOAD_DOCUMENT",
"message": "Please upload the document including the expiration date page.",
"documentId": "doc_pu0aoLYYTST8xxewiyblK"
}
]
}
```
Update the information, then use POST `/v3/users/:user_id/compliance/submit `to submit the application again.
## RFI Actions
When a submitted application needs updated information, the status transitions to `REQUIRES_INFO` and the `rfiActions` field will include the actions required before resubmission.
| Type | Action |
| :------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `UPDATE_PROFILE` | Update the user's profile information before resubmission, a common reason is information that doesn't match the submitted documentation. |
| `RESUBMIT_DOCUMENT` | Update the user's documentation before resubmission, common reasons include expired, blurry, or unqualified documents. |
## Getting Help
* 📧 **Email:** [support@hifi.com](mailto:support@hifi.com)
* 💬 **Slack:** Message us in our shared Slack channel
## Related Resources
* [User Overview](/v3/core/users/overview) - User types and creation
* [KYB (Business)](/v3/core/compliance/kyb) - Business verification requirements
* Virtual Accounts - Set up fiat deposit accounts
* API Reference: Complete endpoints