Create Customer

This is typically the first step in integrating with the Align API. After creating a customer, you’ll need to complete KYC verification before they can transact.

Method Signature

align.customers.create(data: CreateCustomerRequest): Promise<Customer>

Parameters

string

required

Customer’s email address. Must be unique across all customers.

'individual' | 'corporate'

required

Customer type. Determines which additional fields are required.

string

Customer’s first name. Required for individual customers.

string

Customer’s last name. Required for individual customers.

string

Company name. Required for corporate customers.

Returns

string

Unique identifier for the customer (UUID format)

string

Customer’s email address

'individual' | 'corporate'

Customer type

string

Customer’s first name (for individuals)

string

Customer’s last name (for individuals)

string

Company name (for corporates)

object

KYC status information (null until KYC is initiated)

Examples

Individual Customer

Create a customer account for an individual user:

TypeScript
JavaScript

import Align from "@tolbel/align";

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

const customer = await align.customers.create({
  email: "[email protected]",
  type: "individual",
  first_name: "Alice",
  last_name: "Smith",
});

console.log(`Customer ID: ${customer.customer_id}`);
// Customer ID: 123e4567-e89b-12d3-a456-426614174000

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

const Align = require("@tolbel/align").default;

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

const customer = await align.customers.create({
  email: "[email protected]",
  type: "individual",
  first_name: "Alice",
  last_name: "Smith",
});

console.log("Customer ID:", customer.customer_id);
console.log("Email:", customer.email);

Corporate Customer

Create a customer account for a business:

const company = await align.customers.create({
  email: "[email protected]",
  type: "corporate",
  company_name: "Acme Corporation",
});

console.log(`Company: ${company.company_name}`);
// Company: Acme Corporation

Full Response Example

{
  "customer_id": "123e4567-e89b-12d3-a456-426614174000",
  "email": "[email protected]",
  "type": "individual",
  "first_name": "Alice",
  "last_name": "Smith",
  "kycs": null
}

Error Handling

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

try {
  const customer = await align.customers.create({
    email: "[email protected]",
    type: "individual",
    first_name: "Alice",
    last_name: "Smith",
  });
} catch (error) {
  if (error instanceof AlignValidationError) {
    // Request validation failed
    console.error("Validation errors:", error.errors);
    // [{ path: ["email"], message: "Invalid email format" }]
  } else if (error instanceof AlignError) {
    if (error.status === 409) {
      console.error("Email already exists");
    } else {
      console.error(`API Error: ${error.message}`);
    }
  }
}

Common Errors

Status Code	Reason	Solution
400	Invalid request data	Check required fields and data types
409	Email already exists	Use a unique email or find existing customer
401	Invalid API key	Verify your API key is correct

Usage Notes

Email addresses must be unique across all customers. Attempting to create a customer with an existing email will result in a 409 Conflict error.

After creating a customer, initiate KYC verification using createKycSession to enable transactions.

Complete Workflow

Here’s a typical customer onboarding flow:

// 1. Create the customer
const customer = await align.customers.create({
  email: "[email protected]",
  type: "individual",
  first_name: "Alice",
  last_name: "Smith",
});

// 2. Initiate KYC verification
const kycSession = await align.customers.createKycSession(customer.customer_id);
console.log(`KYC Link: ${kycSession.kycs.kyc_flow_link}`);

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

// 4. Customer is now ready for transactions!

Get Customer

Retrieve customer details

Create KYC Session

Start identity verification

List Customers

List all customers

Update Customer

Update customer documents

Getting Started

API Reference

Method Signature

Parameters

Returns

Examples

Individual Customer

Corporate Customer

Full Response Example

Error Handling

Common Errors

Usage Notes

Complete Workflow

Get Customer

Create KYC Session

List Customers

Update Customer

​Method Signature

​Parameters

​Returns

​Examples

​Individual Customer

​Corporate Customer

​Full Response Example

​Error Handling

​Common Errors

​Usage Notes

​Complete Workflow

​Related Methods

Get Customer

Create KYC Session

List Customers

Update Customer

Method Signature

Parameters

Returns

Examples

Individual Customer

Corporate Customer

Full Response Example

Error Handling

Common Errors

Usage Notes

Complete Workflow

Related Methods