Skip to main content

​
Method Signature

align.customers.get(customerId: string): Promise<Customer>

​
Parameters

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

​
Returns

​
customer_id
string
Unique identifier for the customer
​
email
string
Customer’s email address
​
type
'individual' | 'corporate'
Customer type
​
first_name
string
Customer’s first name (for individuals)
​
last_name
string
Customer’s last name (for individuals)
​
kycs
object
KYC verification status and details

​
Examples

import Align from "@tolbel/align";

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

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

console.log(`Email: ${customer.email}`);
// Email: [email protected]

console.log(`Name: ${customer.first_name} ${customer.last_name}`);
// Name: Alice Smith

// Check KYC status
if (customer.kycs) {
  console.log(`KYC Status: ${customer.kycs.sub_status}`);
  // KYC Status: kyc_form_submission_accepted
}

​
Full Response Example

{
  "customer_id": "123e4567-e89b-12d3-a456-426614174000",
  "email": "[email protected]",
  "type": "individual",
  "first_name": "Alice",
  "last_name": "Smith",
  "kycs": {
    "status": "approved",
    "sub_status": "kyc_form_submission_accepted",
    "kyc_flow_link": "https://kyc.alignlabs.dev/flow/..."
  }
}

​
Error Handling

import { AlignError } from "@tolbel/align";

try {
  const customer = await align.customers.get("invalid-id");
} catch (error) {
  if (error instanceof AlignError && error.statusCode === 404) {
    console.error("Customer not found");
  }
}

​
Monitoring KYC Status

Demo Only Notice: Simple while loops or setInterval polling are not suitable for production applications. They consume unnecessary resources and are unreliable if your server restarts.
The most efficient way to track KYC updates is to listen for the customer.kycs.updated webhook event. This allows your application to react in real-time. 
// Webhook Handler (e.g., Express route)
app.post(
  "/webhooks/align",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    // ... Verification logic (see Webhooks documentation) ...

    const event = JSON.parse(req.body.toString());

    if (event.event_type === "customer.kycs.updated") {
      // 1. Get the customer ID from the event
      const customerId = event.entity_id;

      // 2. Fetch the latest customer data to check the new status
      const customer = await align.customers.get(customerId);

      // 3. Handle the status change
      if (customer.kycs?.status === "approved") {
        console.log(`✅ KYC Approved for customer ${customerId}`);
        // TODO: Enable feature access for user
      } else if (customer.kycs?.status === "rejected") {
        console.log(`❌ KYC Rejected for customer ${customerId}`);
        // TODO: Notify user to retry
      }
    }

    res.status(200).send("OK");
  }
);

​
Secondary Method: Robust Polling (Fallback)

For added reliability, implementing a robust polling mechanism (e.g., a scheduled Cron job or a queue-based worker like BullMQ/Redis) is recommended to double-check statuses in case a webhook event is missed. Do not use simple while-loops in your main request thread. Instead, schedule a background job: 
// Example: Cron job running every 5 minutes
cron.schedule("*/5 * * * *", async () => {
  console.log("Running KYC status sync...");

  // Fetch pending verifications from YOUR database
  const pendingUsers = await db.users.find({ kycStatus: "pending" });

  for (const user of pendingUsers) {
    const customer = await align.customers.get(user.alignCustomerId);

    // Update local database if status has changed
    if (customer.kycs?.status !== user.kycStatus) {
      await db.users.update(user.id, { kycStatus: customer.kycs?.status });
    }
  }
});

​
Demo/Testing Polling

For scripts or quick local testing only, you can use a simple loop: 
async function waitForKycApproval(customerId: string) {
  let attempts = 0;
  while (attempts < 20) {
    const customer = await align.customers.get(customerId);

    if (customer.kycs?.status === "approved") return true;
    if (customer.kycs?.status === "rejected") return false;

    await new Promise((r) => setTimeout(r, 5000)); // Wait 5s
    attempts++;
  }
  return false;
}
Instead of polling, use webhooks to receive real-time KYC status updates.

Create Customer

Create a new customer

List Customers

Search and list customers