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
Customer’s email address. Must be unique across all customers.
type
'individual' | 'corporate'
required
Customer type. Determines which additional fields are required.
Customer’s first name. Required for individual customers.
Customer’s last name. Required for individual customers.
Company name. Required for corporate customers.
Returns
Unique identifier for the customer (UUID format)
type
'individual' | 'corporate'
Customer type
Customer’s first name (for individuals)
Customer’s last name (for individuals)
Company name (for corporates)
KYC status information (null until KYC is initiated)
Examples
Individual Customer
Create a customer account for an individual user:
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!