Skip to main content
KYC verification is required before customers can create virtual accounts or process transfers.

​
Method Signature

align.customers.createKycSession(customerId: string): Promise<KycSessionResponse>

​
Parameters

​
customerId
string
required
The unique customer identifier (UUID format)

​
Returns

​
kycs
object
KYC session information

​
Examples

​
Basic Usage

import Align from "@tolbel/align";

const align = new Align({
  apiKey: process.env.ALIGN_API_KEY!,
  environment: "sandbox",
});

const kycSession = await align.customers.createKycSession(
  "123e4567-e89b-12d3-a456-426614174000"
);

console.log(`KYC Link: ${kycSession.kycs.kyc_flow_link}`);
// https://kyc.alignlabs.dev/flow/abc123...

// Redirect user to this link to complete verification

​
Frontend Integration

Send the KYC link to your frontend for user redirect: 
// Backend API endpoint
app.post("/api/kyc-session", async (req, res) => {
  const { customerId } = req.body;

  const session = await align.customers.createKycSession(customerId);

  res.json({
    kycUrl: session.kycs.kyc_flow_link,
  });
});

// Frontend redirect
const response = await fetch("/api/kyc-session", {
  method: "POST",
  body: JSON.stringify({ customerId }),
});

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

// Option 1: Redirect in same window
window.location.href = kycUrl;

// Option 2: Open in new tab
window.open(kycUrl, "_blank");

// Option 3: Embed in iframe (if allowed)
document.getElementById("kyc-frame").src = kycUrl;

​
Response Example

{
  "kycs": {
    "kyc_flow_link": "https://kyc.alignlabs.dev/flow/abc123def456"
  }
}

​
KYC Status Flow

StatusSub-StatusDescription
pendingkyc_form_submission_startedUser has started the verification
approvedkyc_form_submission_acceptedVerification successful
rejectedkyc_form_resubmission_requiredVerification requires more details
KYC links expire after a certain period. If the link expires, call this method again to generate a new one.

​
Sandbox Testing

In the sandbox environment, simulate KYC approval without completing the actual flow: 
// Create customer
const customer = await align.customers.create({
  email: "[email protected]",
  type: "individual",
  first_name: "Test",
  last_name: "User",
});

// Create KYC session
await align.customers.createKycSession(customer.customer_id);

// Simulate approval (sandbox only!)
await align.customers.simulateCustomer({
  customer_id: customer.customer_id,
  action: "kyc.status.approve",
});

// Customer is now KYC-approved
const updated = await align.customers.get(customer.customer_id);
console.log(updated.kycs?.sub_status);
// "kyc_form_submission_accepted"

Create Customer

Create a customer first

Simulate Customer

Test KYC approval in sandbox

Get Customer

Check KYC status