Skip to main content
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.
Compared to our previous KYC, the following additional information is now required when onboarding an individual user:
  • 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"
}'
Response: 
{
  "id": "32051b2f-0798-55a7-9c42-b08da4192c97",
  "type": "individual",
  "email": "john.doe@example.com",
  "name": "John Doe",
  "wallets": {
    "INDIVIDUAL": {
      "POLYGON": {
        "address": "0x1b932E54e77Aeb698144550d5a493Ea99E20Daa7"
      },
      "ETHEREUM": {
        "address": "0xC1c767eaB34b3Cc2C33a354f6Ff2c20fCB98D3C9"
      }
    }
  }
}

​
Step 2: Upload KYC Information

After creating the user, you can provide the additional KYC information required for the USD rail. POST /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"
}'
Response: 
{
  "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'
Response: 
{
  "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"}'
Response: 
{
  "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:
⌘I