This guide covers the key steps for implementing KYC on the new USD rail for individual users.
Overview
As part of the new USD rail release, we have upgraded our KYC endpoints to be more flexible and easier to implement. This includes endpoints for uploading documentation and a new response schema.
The new USD rail requires using the updated flow. You must use the new
documentation endpoint to upload user documents. Failing to do so will result
in a 400 error when submitting the application.
- nationality (string): Three-letter alpha-3 country code as defined in the ISO 3166-1 spec
Step 1: Create an Individual User
Before providing additional details, you must first create an individual user. This step is consistent with the previous KYC flow, requiring basic user information at creation. Wallet addresses will be automatically assigned to the user by default.
POST /v2/users
curl --request POST \
--url https://sandbox.hifibridge.com/v2/users \
--header 'accept: application/json' \
--header 'authorization: Bearer YOUR-API-KEY' \
--header 'content-type: application/json' \
--data '{
"type": "individual",
"address": {
"addressLine1": "123 Main st",
"city": "New York",
"stateProvinceRegion": "NY",
"postalCode": "10010",
"country": "USA"
},
"requestId": "705f1f8b-a080-467c-b683-174eca409928",
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@example.com",
"dateOfBirth": "1999-01-01",
"signedAgreementId": "2415fed7-ce1c-4752-a67e-8ed1bb4a1a0d"
}'
{
"id": "32051b2f-0798-55a7-9c42-b08da4192c97",
"type": "individual",
"email": "john.doe@example.com",
"name": "John Doe",
"wallets": {
"INDIVIDUAL": {
"POLYGON": {
"address": "0x1b932E54e77Aeb698144550d5a493Ea99E20Daa7"
},
"ETHEREUM": {
"address": "0xC1c767eaB34b3Cc2C33a354f6Ff2c20fCB98D3C9"
}
}
}
}
/v2/users/{userId}/kyc
curl --request POST \
--url https://sandbox.hifibridge.com/v2/users/32051b2f-0798-55a7-9c42-b08da4192c97/kyc \
--header 'accept: application/json' \
--header 'authorization: Bearer YOUR-API-KEY' \
--header 'content-type: application/json' \
--data '{
"phone": "+8573491112",
"taxIdentificationNumber": "725569852",
"nationality": "USA"
}'
{
"userId": "32051b2f-0798-55a7-9c42-b08da4192c97",
"kycInfo": {
"type": "individual",
"firstName": "John",
"lastName": "Doe",
"nationality": "USA",
"email": "john.doe@example.com",
"phone": "+8573491112",
"address": {
"city": "New York",
"country": "USA",
"postalCode": "10010",
"addressLine1": "123 Main st",
"stateProvinceRegion": "NY"
},
"dateOfBirth": "1999-01-01T00:00:00+00:00",
"taxIdentificationNumber": "725569852",
"documents": []
}
}
Step 3: Upload Documentation
Users can now upload raw documentation directly. HIFI will return a file ID, which can later be used to attach the document to the user.
Upload Documentation
POST /v2/files
curl --request POST \
--url https://sandbox.hifibridge.com/v2/files \
--header 'accept: application/json' \
--header 'authorization: Bearer YOUR-API-KEY' \
--header 'content-type: multipart/form-data' \
--form file='@document.png'
{
"id": "file_JzALYV2L1-4LBmaxZ6GCm",
"createdAt": "2025-09-25T22:05:16.764Z",
"fileName": "document.png",
"size": 17834,
"mimeType": "image/png"
}
Add Documentation to User
After receiving the fileId, you can attach the documentation to the user. For the documentation required for the USD rail, please refer to Individual Documents.
POST /v2/users/{userId}/kyc/documents
curl --request POST \
--url https://sandbox.hifibridge.com/v2/users/32051b2f-0798-55a7-9c42-b08da4192c97/kyc/documents \
--header 'accept: application/json' \
--header 'authorization: Bearer YOUR-API-KEY' \
--header 'content-type: application/json' \
--data '[
{
"type": "DRIVERS",
"subType": "FRONT_SIDE",
"issuedCountry": "USA",
"fileId": "file_JzALYV2L1-4LBmaxZ6GCm"
},
{
"type": "DRIVERS",
"subType": "BACK_SIDE",
"issuedCountry": "USA",
"fileId": "file_JzALYV2L1-4LBmaxZ6GCm"
}
]'
Step 4: Check KYC Requirements (Optional)
You can use the “Check KYC Requirements” endpoint to verify any missing or invalid information before submitting the KYC application.
GET /v2/users/{userId}/kyc/requirements
curl --request GET \
--url 'https://sandbox.hifibridge.com/v2/users/32051b2f-0798-55a7-9c42-b08da4192c97/kyc/requirements?rails=USD' \
--header 'accept: application/json' \
--header 'authorization: Bearer YOUR-API-KEY'
Step 5: Submit KYC
Once all required information has been submitted, you can now submit the KYC application to our new USD rail!
POST /v2/users/{userId}/kyc/submissions
curl --request POST \
--url https://sandbox.hifibridge.com/v2/users/32051b2f-0798-55a7-9c42-b08da4192c97/kyc/submissions \
--header 'accept: application/json' \
--header 'authorization: Bearer YOUR-API-KEY' \
--header 'content-type: application/json' \
--data '{"rails":"USD"}'
{
"USD": {
"status": "CREATED",
"message": "Your KYC application has been successfully created. We will review it shortly."
}
}
Step 6: Retrieve KYC Status
After submitting the KYC application, you can retrieve the latest screening result.
GET /v2/users/{userId}/kyc/status
curl --request GET \
--url 'https://sandbox.hifibridge.com/v2/users/32051b2f-0798-55a7-9c42-b08da4192c97/kyc/status?rails=USD' \
--header 'accept: application/json' \
--header 'authorization: Bearer YOUR-API-KEY'
Next Steps
🎉 Congratulations! The individual user has been successfully onboarded. You can now proceed to:
Remember that the USD Rail has minimum transaction amounts: 10USDforUSDTand1 USD for USDC for both pay-ins and payouts. See the USD Rail Overview for more details. 
