HIFI Docs

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

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 Compliance Profile

Update user’s non-documentary informationRequest

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

{
    "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"
}

Add Documentation

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

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

{
    "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

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

{
    "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.

Update Questionnaire (optional)

Request

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

{
    "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"
}

Submit Compliance Information for Check

Once all the required information is updated, submit the application for compliance reviewRequest

curl -X POST "https://sandbox.hifi.com/v3/users/usr_4o0ZDdLcfxmB6OyzUEVNq/compliance/check" \
  -H "Authorization: Bearer YOUR_API_KEY" \

Response

{
    "userId": "usr_TpCyt0c8PeZveAsmddulu",
    "complianceStatus": "PENDING",
    "message": null,
    "rfiActions": []
}

Get the KYC status

Listen to our webhook or polling the user’s compliance statusRequest

curl -X GET "https://sandbox.hifi.com/v3/users/usr_9RJb0KUrhugQ7uMZL5UML/compliance/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
    "userId": "usr_TpCyt0c8PeZveAsmddulu",
    "complianceStatus": "APPROVED",
    "message": null,
    "rfiActions": []
}

Expected Behavior

After submission, the application has the following possible states:

APPROVED

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.

PENDING

IN_REVIEW

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

REJECTED

Our compliance team has determined that we cannot onboard this user. Reach out to our support team for more information.

REQUIRES_INFO

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

{
    "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
💬 Slack: Message us in our shared Slack channel

User Overview - User types and creation
KYB (Business) - Business verification requirements
Virtual Accounts - Set up fiat deposit accounts
API Reference: Complete endpoints

Introduction

Core concepts

Features

Compliance

Payments

References

KYC

Information Required

Profile

Documentation

Questionnaire (Optional)

Example: Full KYC Flow

Government Issued ID

Proof of Address

Expected Behavior

RFI Actions

Getting Help

​Information Required

​Profile

​Documentation

​Questionnaire (Optional)

​Example: Full KYC Flow

​Government Issued ID

​Proof of Address

​Expected Behavior

​RFI Actions

​Getting Help

​Related Resources

Information Required

Profile

Documentation

Questionnaire (Optional)

Example: Full KYC Flow

Government Issued ID

Proof of Address

Expected Behavior

RFI Actions

Getting Help

Related Resources