Create KYC Session

KYC verification is required before customers can create virtual accounts or process transfers.

Method Signature

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

Parameters

string

required

The unique customer identifier (UUID format)

Returns

object

KYC session information

Show KYC Object Properties

string

URL for the customer to complete KYC verification

Examples

Basic Usage

TypeScript
JavaScript

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

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

console.log("KYC Link:", kycSession.kycs.kyc_flow_link);

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

Status	Sub-Status	Description
`pending`	`kyc_form_submission_started`	User has started the verification
`approved`	`kyc_form_submission_accepted`	Verification successful
`rejected`	`kyc_form_resubmission_required`	Verification 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

Getting Started

API Reference

Create KYC Session

Method Signature

Parameters

Returns

Examples

Basic Usage

Frontend Integration

Response Example

KYC Status Flow

Sandbox Testing

Create Customer

Simulate Customer

Get Customer

​Method Signature

​Parameters

​Returns

​Examples

​Basic Usage

​Frontend Integration

​Response Example

​KYC Status Flow

​Sandbox Testing

​Related Methods

Create Customer

Simulate Customer

Get Customer

Method Signature

Parameters

Returns

Examples

Basic Usage

Frontend Integration

Response Example

KYC Status Flow

Sandbox Testing

Related Methods