Customers

The Customer API allows you to create, update, retrieve, and delete customer records. Our flexible onboarding process supports registration using either a phone number or an email address, ensuring a smooth initiation process for users across different regions and preferences. Behind the scenes, our API transforms incoming data, performs rigorous validation—including KYC checks—and securely persists customer data for future operations.

Create Customer

Endpoint: POST /v1/customers

Description:
Create a new customer by providing essential contact and KYC information. You can register customers using either an email address, a phone number, or both. In addition to the basic contact details, you can provide KYC data (such as address, city, and country) to comply with regulatory requirements.

(Tip: ensure that either the email or phone number is provided to allow for successful registration.)

Sample Request Body:

{
  "email": "[email protected]",
  "phone_number": "1234567890",
  "type": "individual",
  "kyc_type": "standard",
  "address_line_1": "123 Main St",
  "city": "Metropolis",
  "country": "US"
}

Response:

{
  "id": "cus_xxx"
}

Update a Customer

Modify an existing customer's details by updating their contact or KYC information. This endpoint verifies that the customer belongs to your organization and enforces the same validation rules as during registration. Changes to critical data may trigger a re-verification process.

Endpoint: PUT /v1/customers/{id}

Sample Request Body:

{
  "email": "[email protected]",
  "phone_number": "0987654321",
  "type": "individual",
  "kyc_type": "enhanced",
  "address_line_1": "456 New Ave",
  "city": "Gotham",
  "country": "US"
}

Retrieve Customer Details

Fetch detailed information for a specific customer using their unique identifier. The response includes all customer data, such as contact details, KYC status, and any linked bank accounts. This endpoint is essential for viewing a customer’s profile and ensuring that their information is up to date.

Endpoint: GET /v1/customers/{id}

Response Example:

{
  "id": "cus_abc123def456",
  "email": "[email protected]",
  "phone_number": "1234567890",
  "type": "individual",
  "kyc_type": "standard",
  "address_line_1": "123 Main St",
  "city": "Metropolis",
  "country": "US",
  "is_verified": true,
  "created_at": "2025-03-17T10:00:00Z"
}

Delete a Customer

Remove a customer record from the system. This is a soft delete operation, meaning the customer’s data remains in the database for historical and auditing purposes, but is marked as deleted so that it is excluded from active queries.

Endpoint: DELETE /v1/customers/{id}

Response Example:

{
  "success": true
}