Skip to main content

Customers Endpoints

This section covers all customer-related endpoints.

1. Create a Customer​

Create a new customer record.
The same endpoint supports both individuals and businesses:

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

You can create a single customer or multiple customers in bulk by passing an array of customer objects into this endpoint.

Document Uploads

The fields verification_document and incorporation_certificate appear in the customer object but should not be set directly via API.

  • Upload customer documents (IDs, passports, incorporation certs) via the Celar Dashboard.
  • The Dashboard stores them, generates a secure URL, and links it to the customer.
  • When you fetch a customer (GET /customers/:id), you may see these URLs populated.

Individual Example​

curl --request POST \
  --url https://api.sandbox.celar.io/api/v1/customers \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "country": "KEN",
  "email": "alice99@example.com",
  "type": "individual",
  "wallet_address": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
  "address": "45 Koinange Street, Nairobi",
  "name": "Alice Wanjiku",
  "tax_id": "P87126345B",
  "document_type": "passport"
}'

Example Response​

{
  "message": "1 customer(s) created successfully",
  "customers": [
    {
      "id": "cr_f12ab34cd567",
      "created_at": "2025-09-26T08:11:20.880Z",
      "updated_at": "2025-09-26T08:11:20.880Z",
      "country": "KEN",
      "email": "alice99@example.com",
      "type": "individual",
      "wallet_address": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
      "address": "45 Koinange Street, Nairobi",
      "is_active": true,
      "name": "Alice Wanjiku",
      "psp_id": "psp_62ac45f3bc99",
      "tax_id": "P87126345B",
      "document_type": "passport",
      "verification_document": null,
      "incorporation_certificate": null
    }
  ]
}

Business Example​

curl --request POST \
  --url https://api.sandbox.celar.io/api/v1/customers \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "country": "KEN",
  "email": "acme.ltd@example.com",
  "type": "business",
  "wallet_address": "0x47c99e83Ff01123f4Bbd2A9e7aAF35A2F97B4761",
  "address": "10 Industrial Area Road, Nairobi",
  "name": "Acme Trading Ltd",
  "tax_id": "C5562399K",
  "document_type": "incorporation_certificate"
}'

2. Get All Customers​

Retrieve a list of all customers under your PSP account. Supports filters like pagination, limit, and offset.

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

3. Get a Single Customer​

Retrieve details of a specific customer by their customer_id.

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

4. Get Customer Balance​

Retrieve the total settled pay-in balance for a given customer. This shows how much stablecoin value has been confirmed into your Celar wallets for that user.

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

Example Response​

{
  "customer_id": "cr_f12ab34cd567",
  "balance": "1250.50",
  "currency": "USDC"
}

5. Update a Customer​

Update an existing customer’s details. Only the following fields can be updated: name, email, address, wallet_address, document_type, verification_document, incorporation_certificate.

curl --request PATCH \
  --url https://api.sandbox.celar.io/api/v1/customers/<customer_id> \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Alice N. Wanjiku",
  "address": "101 Moi Avenue, Nairobi",
  "wallet_address": "0x5D3a536E4D6DbD6114cc1Ead35777bAB948E3643"
}'

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": "alice99@example.com",
    "type": "individual",
    "wallet_address": "0x5D3a536E4D6DbD6114cc1Ead35777bAB948E3643",
    "address": "101 Moi Avenue, Nairobi",
    "is_active": true,
    "name": "Alice N. Wanjiku",
    "psp_id": "psp_62ac45f3bc99",
    "tax_id": "P87126345B",
    "document_type": "passport",
    "verification_document": null,
    "incorporation_certificate": null
  }
}
Document Uploads

As with creation, verification_document and incorporation_certificate are linked only via the Dashboard after uploads. Do not set raw URLs directly in API requests.

6. Deactivate a Customer​

This action cannot be reversed once it is done. 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 <your_api_key>'

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": "alice99@example.com",
    "type": "individual",
    "wallet_address": "0x5D3a536E4D6DbD6114cc1Ead35777bAB948E3643",
    "address": "101 Moi Avenue, Nairobi",
    "is_active": false,
    "name": "Alice N. Wanjiku",
    "psp_id": "psp_62ac45f3bc99",
    "tax_id": "P87126345B",
    "document_type": "passport",
    "verification_document": "https://example.com",
    "incorporation_certificate": null
  }
}