Customers Endpoints

This section covers customer record management endpoints. Every transaction in Celar must be linked to a customer, so creating and maintaining accurate customer records is the foundation of your integration.

Customer Lifecycle

A typical integration follows this sequence for each customer:

Create the customer with personal and address details
Continue in Compliance for the KYC/KYB flow
Add payment details after verification is in progress or complete
Once kyc_status returns success, the customer is cleared for transactions

Businesses have an additional step between 1 and 2 — the business details form collects company name, registered address, incorporation certificate number, and beneficiary owner information before the person details step.

1. Create a Customer

Create a new customer record. The same endpoint handles both individuals and businesses — the type field determines which fields are required.

Individuals set type to individual with document_type as id_card, passport, or driver_license. Businesses set type to business with document_type as incorporation_certificate.

Document Uploads

Fields like verification_document, proof_of_residential_address, incorporation_certificate, and proof_of_business_address cannot be set here. After creating the customer, continue with the compliance flow in Next: Continue in Compliance.

Individual Example

curl --request POST \
  --url https://api.sandbox.celar.io/api/v1/customers \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "country": "KEN",
    "currency": "KES",
    "email": "john.doe@example.com",
    "type": "individual",
    "tax_id": "TAX12345",
    "document_type": "id_card",
    "first_name": "John",
    "last_name": "Doe",
    "dob": "1995-06-15",
    "government_id_number": "12345678",
    "residential_address": {
      "street_line_1": "123 Main Street",
      "region": "Nairobi County",
      "city": "Nairobi",
      "zip": "00100",
      "country": "KEN"
    }
  }'

Business Example

curl --request POST \
  --url https://api.sandbox.celar.io/api/v1/customers \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "country": "KEN",
    "currency": "KES",
    "email": "legal@novaindustries.co.ke",
    "type": "business",
    "tax_id": "TAX889922",
    "document_type": "incorporation_certificate",
    "business_name": "Nova Industries Limited",
    "first_name": "Samuel",
    "last_name": "Kariuki",
    "dob": "1982-09-14",
    "government_id_number": "55667788",
    "registered_business_address": {
      "street_line_1": "45 Industrial Area Road",
      "region": "Nairobi County",
      "city": "Nairobi",
      "zip": "00500",
      "country": "KEN"
    },
    "residential_address": {
      "street_line_1": "10 Kilimani Estate",
      "region": "Nairobi County",
      "city": "Nairobi",
      "zip": "00100",
      "country": "KEN"
    },
    "business_tax_id": "BUS667788",
    "incorporation_certificate_number": "C.2023/990011",
    "ownership_percentage": "70",
    "beneficiary_owners": [
      {
        "first_name": "Test",
        "last_name": "Owner",
        "tax_id": "TAX001122",
        "dob": "1990-01-01",
        "email": "test.owner@example.com",
        "phone_number": "+254700000000",
        "ownership_percentage": "10",
        "address": {
          "street_line_1": "123 Test Road",
          "region": "Nairobi County",
          "city": "Nairobi",
          "zip": "00100",
          "country": "KEN"
        },
        "government_id_type": "national_id",
        "government_id_number": "99887766"
      }
    ]
  }'

Example Response

{
  "message": "1 customer(s) created successfully",
  "customers": [
    {
      "id": "cr_53c79dae85d2cee2",
      "created_at": "2026-02-27T13:20:23.543Z",
      "updated_at": "2026-02-27T13:20:23.543Z",
      "country": "KEN",
      "email": "legal@novaindustries.co.ke",
      "type": "business",
      "is_active": true,
      "psp_id": "psp_155dc696b5cdd4f4",
      "tax_id": "TAX889922",
      "currency": "KES",
      "document_type": "incorporation_certificate",
      "verification_document": null,
      "incorporation_certificate": null,
      "proof_of_residential_address": null,
      "proof_of_business_address": null,
      "kyc_status": "pending",
      "business_name": "Nova Industries Limited",
      "first_name": "Samuel",
      "last_name": "Kariuki",
      "dob": "1982-09-13T21:00:00.000Z",
      "government_id_number": "",
      "registered_business_address": {
        "zip": "00500",
        "city": "Nairobi",
        "region": "Nairobi County",
        "country": "KEN",
        "street_line_1": "45 Industrial Area Road"
      },
      "residential_address": {
        "zip": "00100",
        "city": "Nairobi",
        "region": "Nairobi County",
        "country": "KEN",
        "street_line_1": "10 Kilimani Estate"
      },
      "business_tax_id": "BUS667788",
      "incorporation_certificate_number": "C.2023/990011",
      "ownership_percentage": "70",
      "has_beneficiary_owners": true
    }
  ]
}

info

Document fields (verification_document, incorporation_certificate, proof_of_residential_address, proof_of_business_address) are always null on creation. Complete the compliance flow in Next: Continue in Compliance before relying on the customer for production payment activity.

Next: Continue in Compliance

Before adding payment details, complete the customer verification flow in Compliance Workflows & Endpoints.

Use the Compliance section for:

Upload Customer Documents
Complete Identity Verification
the dashboard verification path as an alternative to the API workflow
kyc_status expectations before the customer starts transacting

Once that flow is complete, return here for payment details and customer management endpoints.

2. Add Payment Details

Attach banking and wallet information to a customer. This is required before the customer can send or receive funds.

The endpoint handles both creation and updates — if payment details already exist for the customer, the record is updated in place. You do not need to call a separate payment-details update endpoint.

routing_number and bank_address are optional. Only include them when relevant, typically for US-based customers where ACH transfers require a routing number.

Field	Required	Description
`customer_id`	Yes	The customer to attach payment details to
`bank_name`	Yes	Name of the customer's bank
`account_number`	Yes	Bank account number
`wallet_address`	Yes	Ethereum-compatible wallet address
`routing_number`	No	Required for US ACH transfers
`bank_address`	No	Physical address of the bank branch

curl --request PATCH \
  --url https://api.sandbox.celar.io/api/v1/customers/payment-details \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "customer_id": "cr_53c79dae85d2cee2",
    "bank_name": "Equity Bank",
    "account_number": "0011223344",
    "wallet_address": "0x5D3a536E4D6DbD6114cc1Ead35777bAB948E3643"
  }'

For US customers with ACH:

curl --request PATCH \
  --url https://api.sandbox.celar.io/api/v1/customers/payment-details \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "customer_id": "cr_53c79dae85d2cee2",
    "bank_name": "Chase",
    "account_number": "000123456789",
    "wallet_address": "0x5D3a536E4D6DbD6114cc1Ead35777bAB948E3643",
    "routing_number": "021000021",
    "bank_address": {
      "street_line_1": "270 Park Avenue",
      "city": "New York",
      "region": "NY",
      "zip": "10017",
      "country": "USA"
    }
  }'

Example Response

{
  "message": "Payment details added successfully"
}

If payment details already existed for the customer:

{
  "message": "Payment details updated successfully"
}

note

Payment details are scoped to the customer. A customer can only have one active set of payment details at a time. Calling this endpoint again with a different account number will replace the existing record.

5. Get All Customers

Retrieve a paginated list of all customers under your PSP account.

Query param	Type	Default	Description
`limit`	number	`50`	Number of records to return
`offset`	number	`0`	Number of records to skip
`search`	string	-	Search by email
`status`	string	-	Filter by `active` or `inactive`

curl --request GET \
  --url 'https://api.sandbox.celar.io/api/v1/customers?limit=20&offset=0&status=active' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'

Example Response

{
  "message": "Customers retrieved successfully",
  "total": 1,
  "customers": [
    {
      "id": "cr_53c79dae85d2cee2",
      "created_at": "2026-02-27T13:20:23.543Z",
      "updated_at": "2026-02-27T13:20:23.543Z",
      "country": "KEN",
      "email": "john.doe@example.com",
      "type": "individual",
      "is_active": true,
      "kyc_status": "pending",
      "psp_id": "psp_155dc696b5cdd4f4"
    }
  ]
}

6. Get a Single Customer

Retrieve full details of a specific customer by their customer_id. The response includes their current KYC status, document paths, addresses, and payment details.

curl --request GET \
  --url https://api.sandbox.celar.io/api/v1/customers/{customer_id} \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'

Example Response

{
  "message": "Customer retrieved successfully",
  "customer": {
    "id": "cr_53c79dae85d2cee2",
    "created_at": "2026-02-27T13:20:23.543Z",
    "updated_at": "2026-02-27T13:20:23.543Z",
    "country": "KEN",
    "email": "john.doe@example.com",
    "type": "individual",
    "is_active": true,
    "kyc_status": "pending",
    "psp_id": "psp_155dc696b5cdd4f4",
    "tax_id": "TAX12345",
    "currency": "KES",
    "document_type": "id_card",
    "verification_document": "customers/verification_document_id_a3f1c2b4.pdf",
    "proof_of_residential_address": "customers/proof_of_residential_address_bill_9e2d1a.pdf",
    "incorporation_certificate": null,
    "proof_of_business_address": null,
    "first_name": "John",
    "last_name": "Doe",
    "dob": "1995-06-15T00:00:00.000Z",
    "government_id_number": "12345678",
    "residential_address": {
      "zip": "00100",
      "city": "Nairobi",
      "region": "Nairobi County",
      "country": "KEN",
      "street_line_1": "123 Main Street"
    }
  }
}

7. Update a Customer

Update an existing customer's registered phone number. Only phone_number is accepted by this endpoint.

Field	Type	Description
`phone_number`	string	Customer's registered phone number in E.164 format

curl --request PATCH \
  --url https://api.sandbox.celar.io/api/v1/customers/{customer_id} \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "phone_number": "+254712345678"
  }'

Example Response

{
  "message": "Customer updated successfully",
  "customer": {
    "id": "cr_f12ab34cd567",
    "created_at": "2025-09-26T08:11:20.880Z",
    "updated_at": "2025-09-26T09:22:15.102Z",
    "country": "KEN",
    "email": "john.doe@example.com",
    "type": "individual",
    "phone_number": "+254712345678",
    "is_active": true,
    "kyc_status": "pending_update",
    "psp_id": "psp_62ac45f3bc99"
  }
}

note

Updating phone_number sets kyc_status to pending_update and triggers a background compliance re-check. Payment-detail review behavior is handled separately through PATCH /customers/payment-details.

8. Deactivate a Customer

Soft-deletes a customer by setting is_active to false. The customer record is retained for audit and compliance purposes.

warning

This action cannot be undone through the API. A deactivated customer cannot be linked to any new transactions.

curl --request DELETE \
  --url https://api.sandbox.celar.io/api/v1/customers/{customer_id} \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'

Example Response

{
  "message": "Customer deactivated successfully",
  "customer": {
    "id": "cr_f12ab34cd567",
    "created_at": "2025-09-26T08:11:20.880Z",
    "updated_at": "2025-09-26T09:45:10.729Z",
    "country": "KEN",
    "email": "john.doe@example.com",
    "type": "individual",
    "wallet_address": "0x5D3a536E4D6DbD6114cc1Ead35777bAB948E3643",
    "is_active": false,
    "kyc_status": "pending",
    "psp_id": "psp_62ac45f3bc99",
    "verification_document": "customers/verification_document_id_a3f1c2b4.pdf",
    "incorporation_certificate": null
  }
}

Customer Lifecycle​

1. Create a Customer​

Individual Example​

Business Example​

Example Response​

Next: Continue in Compliance​

2. Add Payment Details​

Example Response​

5. Get All Customers​

Example Response​

6. Get a Single Customer​

Example Response​

7. Update a Customer​

Example Response​

8. Deactivate a Customer​

Example Response​

Customer Lifecycle

1. Create a Customer

Individual Example

Business Example

Example Response

Next: Continue in Compliance

2. Add Payment Details

Example Response

5. Get All Customers

Example Response

6. Get a Single Customer

Example Response

7. Update a Customer

Example Response

8. Deactivate a Customer

Example Response