Skip to main content
KYC Links enable you to collect Know Your Customer (KYC) information from users through a secure, hosted flow. Use KYC links to create a user, unlock rails for a user, or submit KYC for a user.
1

Generate KYC link

Create a unique KYC link for a user, optionally specifying which rails require verification.
2

Present to user

Share the link with the user via email or redirect them to the KYC page.
3

User completes KYC

User fills out their personal information and uploads required documents.
4

Verification and redirect

HIFI verifies the information and redirects the user back to your application.

​
Use Cases

KYC links support two primary workflows:

​
Create New User with KYC

Generate a KYC link without providing a user ID. The link will:
  1. Create a new HIFI user account
  2. Collect KYC information for specified rails
  3. Return the new user ID after completion
Best for: Initial user onboarding when you don’t have a HIFI user yet.

​
Submit KYC for Existing User

Generate a KYC link with a user ID to collect or update KYC information for an existing user. Best for: Adding new rails, updating information, or re-submitting after rejection. Use the Generate KYC Link endpoint to create KYC links. Request: 
curl -X POST "https://sandbox.hifibridge.com/v2/kyc-link" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userType": "INDIVIDUAL",
    "rails": ["USD"],
    "redirectUrl": "https://yourapp.com/kyc-complete",
    "recipientEmail": "user@example.com",
    "templateId": "template_id"
  }'
Request Fields:
​
userType
string
required
Type of user account – INDIVIDUAL or BUSINESS. Required if creating a new user.
​
userId
string
Existing user ID. Required if unlocking rails for an existing user.
​
rails
array
Array of KYC rails to unlock – USD, SOUTH_AMERICA_STANDARD, AFRICA_GENERAL, AFRICA_NIGERIA
​
redirectUrl
string
URL to redirect to after KYC information is submitted (the userId will be appended as a query parameter)
​
recipientEmail
string
Email address to send the KYC link to (production only)
​
templateId
string
Template ID to use for the KYC link
Response: 
{
  "kycLinkUrl": "http://dashboard.hifibridge.com/production/kyc-link?sessionToken=768fb84ad65284cb5fffda212f5e779829318acwdab5a36efbf83c4f44369c73"
}
For detailed field documentation, see the Generate KYC Link API reference.

​
Implementation Options

​
Option 1: Redirect Flow

Redirect users to the KYC link URL for a fully hosted experience. 
// Generate KYC link
const response = await fetch("https://sandbox.hifibridge.com/v2/kyc-link", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    userType: "INDIVIDUAL",
    rails: ["USD"],
    redirectUrl: "https://yourapp.com/kyc-complete",
  }),
});

const { kycLinkUrl } = await response.json();

// Redirect user
window.location.href = kycLinkUrl;
After KYC completion, the user is redirected to your redirectUrl with the user ID appended: 
https://yourapp.com/kyc-complete?userId=usr_abc123
Have HIFI automatically email the KYC link to the user (production only). 
const response = await fetch("https://production.hifibridge.com/v2/kyc-link", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    userType: "INDIVIDUAL",
    rails: ["USD"],
    recipientEmail: "user@example.com",
    redirectUrl: "https://yourapp.com/kyc-complete",
  }),
});

const { kycLinkUrl } = await response.json();

// User receives email with KYC link
// No need to redirect - user clicks link from email
Production Only: The recipientEmail feature is only available in production environments for security reasons. In sandbox, you must manually share the link.

​
Handling KYC Completion

After users complete KYC, monitor their status and handle the redirect.

​
Redirect URL Parameters

When users complete KYC, they’re redirected to your redirectUrl with query parameters: 
https://yourapp.com/kyc-complete?userId=usr_abc123
Extract the user ID and check their KYC status: 
// On your redirect page
const urlParams = new URLSearchParams(window.location.search);
const userId = urlParams.get("userId");

// Fetch user to check KYC status
const response = await fetch(
  `https://sandbox.hifibridge.com/v2/users/${userId}`,
  {
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
    },
  }
);
const user = await response.json();
console.log("KYC Status:", user.kycStatus);

​
Monitoring KYC Status

Use webhooks to receive real-time KYC status updates: 
// Subscribe to KYC webhook events
function handleKycUpdate(event) {
  const { id, kycStatus, rails } = event.data;

  if (kycStatus === "APPROVED") {
    // Enable features requiring KYC
    enableOfframping(id);
  } else if (kycStatus === "REJECTED") {
    // Notify user to retry
    sendKycRejectionEmail(id);
  }
}
See Webhooks for webhook setup.

​
Rails and KYC Requirements

Different rails have different KYC requirements. See the Rails Overview for detailed information about each rail’s capabilities and KYC requirements.
Multiple Rails: You can request KYC for multiple rails in a single link by passing multiple rails in the rails array. The user completes one form that satisfies all requirements.

​
Custom Templates

Brand the KYC page with your company logo and colors:
  1. Contact Support: Request custom template creation
  2. Provide Branding: Share your logo and color scheme
  3. Receive Template ID: HIFI creates a template and provides the ID
  4. Use Template ID: Include templateId when generating links
curl -X POST "https://sandbox.hifibridge.com/v2/kyc-link" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userType": "INDIVIDUAL",
    "rails": ["USD"],
    "templateId": "template_id"
  }'

​
Key Concepts

Generate a KYC link with a userId to submit or update KYC for an existing user.Use cases:
  • Adding KYC for a new rail
  • Updating expired documents
  • Re-submitting after rejection
// Existing user needs USD rail KYC
const response = await fetch('https://sandbox.hifibridge.com/v2/kyc-link', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    userId: 'usr_abc123',
    rails: ['USD'],
    redirectUrl: 'https://yourapp.com/kyc-complete'
  })
});
const { kycLinkUrl } = await response.json();
Users progress through several KYC statuses: - NOT_SUBMITTED: No KYC information submitted yet - PENDING: KYC submitted and under review - APPROVED: KYC verified and approved - REJECTED: KYC rejected (see rejection reason) - EXPIRED: KYC documents expired (rare, annual review) Subscribe to KYC webhooks to track status changes in real-time.
The sessionToken in the kycLinkUrl can be used for programmatic KYC submission if you want to build your own KYC UI instead of using the hosted page. Contact support for documentation on this advanced use case.

​
Getting Help

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