Get Customer

Method Signature

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

Parameters

string

required

The unique customer identifier (UUID format)

Returns

string

Unique identifier for the customer

string

Customer’s email address

'individual' | 'corporate'

Customer type

string

Customer’s first name (for individuals)

string

Customer’s last name (for individuals)

object

KYC verification status and details

Show KYC Object Properties

string

Overall KYC status: pending, approved, rejected, not_started

string

Detailed status: kyc_form_submission_started, kyc_form_submission_accepted, kyc_form_resubmission_required

string

URL for the customer to complete KYC verification

Examples

TypeScript
JavaScript

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
}

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

console.log("Email:", customer.email);
console.log("Name:", customer.first_name, customer.last_name);

if (customer.kycs) {
  console.log("KYC Status:", customer.kycs.sub_status);
}

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.

Primary Method: Webhooks (Recommended)

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

Getting Started

API Reference

Method Signature

Parameters

Returns

Examples

Full Response Example

Error Handling

Monitoring KYC Status

Primary Method: Webhooks (Recommended)

Secondary Method: Robust Polling (Fallback)

Demo/Testing Polling

Create Customer

List Customers

​Method Signature

​Parameters

​Returns

​Examples

​Full Response Example

​Error Handling

​Monitoring KYC Status

​Primary Method: Webhooks (Recommended)

​Secondary Method: Robust Polling (Fallback)

​Demo/Testing Polling

​Related Methods

Create Customer

List Customers

Method Signature

Parameters

Returns

Examples

Full Response Example

Error Handling

Monitoring KYC Status

Primary Method: Webhooks (Recommended)

Secondary Method: Robust Polling (Fallback)

Demo/Testing Polling

Related Methods