Skip to main content
KYC Token Import is a gated feature. Contact your HIFI account manager to have it enabled for your profile.

​
How KYC Token Import Works

1

User completes KYC on your platform

Your user finishes identity verification through Sumsub on your own application. Their applicant data is stored in your Sumsub account and approved.
2

Generate a share token

Using Sumsub’s API, generate a reusable identity share token for the applicant. This token authorizes HIFI to access the user’s existing KYC data.
3

Import the token into HIFI

Call the Import KYC Token endpoint with the user’s HIFI userId and the Sumsub share token. HIFI imports the applicant record and queues an async document sync.
4

Monitor KYC status

After import, the user’s KYC status reflects their Sumsub review result. Use the Retrieve KYC Status endpoint to poll for updates.

​
Importing a KYC Token

Import a user’s existing Sumsub verification using the Import KYC Token endpoint.

​
Request

curl -X POST "https://sandbox.hifibridge.com/v2/users/{userId}/kyc/import-token" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenProvider": "SUMSUB",
    "token": "your-sumsub-share-token"
  }'
​
tokenProvider
string
required
The KYC provider the token was issued by. Currently only SUMSUB is supported.
​
token
string
required
The reusable identity share token obtained from Sumsub. Used to authorize HIFI to import the applicant’s existing KYC data.

​
Response

{
  "rails": "USD",
  "status": "PENDING",
  "message": "Your KYC application has been successfully created. We will review it shortly.",
}
​
rails
string
The rail the KYC submission applies to. Token import currently supports the USD rail.
​
status
string
The KYC review status after import. Common values are PENDING, ACTIVE, INCOMPLETE, and INACTIVE.
​
message
string
A human-readable description of the current status or any error encountered during import.

​
Behavior

If the user already has submitted their KYC application, the endpoint returns a 400 with an error message indicating the user is not allowed for token sharing.
If Sumsub rejects the token (e.g., it has expired or was already used), the endpoint returns a 400 with an error message indicating the token is invalid. Generate a fresh share token from Sumsub and retry.
After a successful import, HIFI queues a background job to pull the applicant’s documents from Sumsub. The import response does not wait for documents to be synced — use the  Retrieve KYC Status endpoint to check completion.

​
Managing KYC After Import

Once a token is imported, the user’s KYC data is fully managed through HIFI’s standard KYC endpoints — no special handling is required.

​
Updating KYC Information

If the imported data is incomplete or needs correction, use the Update KYC endpoint to modify individual fields. 
curl -X POST "https://sandbox.hifibridge.com/v2/users/{userId}/kyc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe"
  }'

​
Resubmitting KYC

If the imported KYC is reviewed and comes back INCOMPLETE, update the flagged fields and resubmit using the Submit KYC endpoint. 
curl -X POST "https://sandbox.hifibridge.com/v2/users/{userId}/kyc/submissions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rails": "USD"
  }'
Use the Retrieve KYC Requirements endpoint beforehand to identify exactly which fields are missing or invalid before resubmitting.

​
Notes for Token Sharing

  • Individuals only — no business/entity
  • Applicant must already be approved on the token donor side
  • Customer must have a specific agreement setting activated with HIFI in Sumsub
  • Applicant’s Sumsub profile must contain all fields required by HIFI’s KYC standard
  • A given user can only import token once

​
Getting Help

  • 📧 Email: support@hifi.com
  • 💬 Slack: Message us in our shared Slack channel