Customers

Base URL: $BUSINESS_API

The object

idstring · required
tenant_idstring · required
customer_typestring · required

one of individual, business

categorystring · required

one of residential, commercial, industrial, institutional, government

display_namestring · required
tax_numberstring · optional
emailstring (email) · optional
phonestring · optional
statusstring · required

one of active, suspended, closed

The object
{
  "id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "customer_type": "individual",
  "category": "residential",
  "display_name": "Ana Matsinhe",
  "tax_number": "TAX-2026-000142",
  "email": "ana.matsinhe@example.org",
  "phone": "+258841234567",
  "status": "active"
}

Download the customer import CSV template

Logs

GET /customers/import/template

Requires business:customers:create. The CSV header the import reads: display_name (required), customer_type (individual or business, default individual), category (residential, commercial, industrial, institutional or government, default residential), phone, email, tax_number.

Returns

200 The CSV template

Errors 401 · 403

curl -X GET "$BUSINESS_API/customers/import/template" \
  -H "Authorization: Bearer sk_test_..."
Response 200

The CSV template

Validate a customer CSV without writing anything

Logs

POST /customers/import/dry-run

Parses and validates the CSV (at most 2000 rows and 2 MiB) and returns every row with its normalized data and errors by field; rows that repeat a phone or e-mail of an earlier row are errors. Nothing is written except the dry run itself, which can be confirmed for 24 hours. Requires business:customers:create.

Body application/json

csvstring · required

CSV text with the header display_name[,customer_type,category,phone,email,tax_number]

Returns

200 The dry run

Show attributes
dry_run_idstring · required
confirmedboolean · required
total_rowsinteger · required
valid_rowsinteger · required
error_rowsinteger · required
created_countinteger · required
expires_atstring (date-time) · required
rowsarray of object · required
Show child attributes
rowinteger · required

Line number in the file (the header is line 1)

dataobject · required
Show child attributes
display_namestring · optional
customer_typestring · optional

one of individual, business

categorystring · optional
phonestring · optional
emailstring · optional
tax_numberstring · optional
errorsarray of object · required
Show child attributes
fieldstring · required

display_name, customer_type, category, phone, email, tax_number or row

reasonstring · required

one of required, too_long, invalid, invalid_customer_type, invalid_category, invalid_phone, invalid_email, duplicate, duplicate_in_file

codestring · required

one of required, too_long, invalid, invalid_customer_type, invalid_category, invalid_phone, invalid_email, duplicate, duplicate_in_file

duplicate_of_rowinteger · optional

For duplicate_in_file

createdboolean · required
customer_idstring · optional

Errors 400 · 401 · 403

curl -X POST "$BUSINESS_API/customers/import/dry-run" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "csv": "csv"
}'
Response 200
{
  "dry_run_id": "dry_2JtWoLL8YFXGwxhQOzhO6PpUIfV",
  "confirmed": true,
  "total_rows": 125000,
  "valid_rows": 1,
  "error_rows": 1,
  "created_count": 1,
  "expires_at": "2026-11-19T09:30:00Z",
  "rows": [
    {
      "row": 1,
      "data": {
        "display_name": "Ana Matsinhe",
        "customer_type": "individual",
        "category": "category",
        "phone": "+258841234567",
        "email": "ana.matsinhe@example.org",
        "tax_number": "TAX-2026-000142"
      },
      "errors": [
        {
          "field": "field",
          "reason": "required",
          "code": "required",
          "duplicate_of_row": 1
        }
      ],
      "created": true,
      "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck"
    }
  ]
}

Confirm a customer import dry run

Logs

POST /customers/import

Creates each valid row of the dry run through the customer service, once per idempotency key (body idempotency_key or the Idempotency-Key header): the same key returns the first answer and creates nothing more; another key returns 409. A dry run with no valid rows returns 400; a stale one (over 24 hours) returns 409. A confirm that creates at least one customer completes the utility_real customer_import step. Requires business:customers:create.

Body application/json

dry_run_idstring · required
idempotency_keystring · optional

Or the Idempotency-Key header

Returns

200 The confirmation, with the created customer per row

Show attributes
dry_run_idstring · required
confirmedboolean · required
total_rowsinteger · required
valid_rowsinteger · required
error_rowsinteger · required
created_countinteger · required
expires_atstring (date-time) · required
rowsarray of object · required
Show child attributes
rowinteger · required

Line number in the file (the header is line 1)

dataobject · required
Show child attributes
display_namestring · optional
customer_typestring · optional

one of individual, business

categorystring · optional
phonestring · optional
emailstring · optional
tax_numberstring · optional
errorsarray of object · required
Show child attributes
fieldstring · required

display_name, customer_type, category, phone, email, tax_number or row

reasonstring · required

one of required, too_long, invalid, invalid_customer_type, invalid_category, invalid_phone, invalid_email, duplicate, duplicate_in_file

codestring · required

one of required, too_long, invalid, invalid_customer_type, invalid_category, invalid_phone, invalid_email, duplicate, duplicate_in_file

duplicate_of_rowinteger · optional

For duplicate_in_file

createdboolean · required
customer_idstring · optional

Errors 400 · 401 · 403 · 404 · 409

curl -X POST "$BUSINESS_API/customers/import" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run_id": "dry_2JtWoLL8YFXGwxhQOzhO6PpUIfV",
  "idempotency_key": "idempotency key"
}'
Response 200
{
  "dry_run_id": "dry_2JtWoLL8YFXGwxhQOzhO6PpUIfV",
  "confirmed": true,
  "total_rows": 125000,
  "valid_rows": 1,
  "error_rows": 1,
  "created_count": 1,
  "expires_at": "2026-11-19T09:30:00Z",
  "rows": [
    {
      "row": 1,
      "data": {
        "display_name": "Ana Matsinhe",
        "customer_type": "individual",
        "category": "category",
        "phone": "+258841234567",
        "email": "ana.matsinhe@example.org",
        "tax_number": "TAX-2026-000142"
      },
      "errors": [
        {
          "field": "field",
          "reason": "required",
          "code": "required",
          "duplicate_of_row": 1
        }
      ],
      "created": true,
      "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck"
    }
  ]
}

List customers

Logs

GET /customers

List utility customers using resource filters and cursor pagination

Returns the tenant's customers one cursor page at a time; the filters combine. Requires business:customers:read; an invalid limit or cursor returns 400.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

qstring · query · optional

Resource-specific text search.

customer_typestring · query · optional

Return only customers of this type: individual or business.

one of individual, business

categorystring · query · optional

Return only customers in this tariff category: residential, commercial, industrial, institutional or government.

one of residential, commercial, industrial, institutional, government

statusstring · query · optional

Return only customers in this status: active, suspended or closed.

one of active, suspended, closed

Returns

200 Utility customers in the authenticated tenant

Show attributes
dataarray of Customer · required
Show child attributes
idstring · required
tenant_idstring · required
customer_typestring · required

one of individual, business

categorystring · required

one of residential, commercial, industrial, institutional, government

display_namestring · required
tax_numberstring · optional
emailstring (email) · optional
phonestring · optional
statusstring · required

one of active, suspended, closed

has_moreboolean · required
next_cursorstring · optional

Permissions business:customers:read · Roles: admin, analyst, billing_clerk, customer_service, field_supervisor, finance, operations, owner, viewer

curl -X GET "$BUSINESS_API/customers" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "customer_type": "individual",
      "category": "residential",
      "display_name": "Ana Matsinhe",
      "tax_number": "TAX-2026-000142",
      "email": "ana.matsinhe@example.org",
      "phone": "+258841234567",
      "status": "active"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Register a utility customer

Logs

POST /customers

Creates a customer in the authenticated tenant with the active status. display_name, a valid customer_type (individual or business) and a valid category are required; tax_number, email and phone are optional and trimmed. Requires business:customers:create; invalid input returns 400. Creating a customer does not create an account or property, which are separate resources.

Body application/json

display_namestring · required
customer_typestring · required

one of individual, business

categorystring · required

one of residential, commercial, industrial, institutional, government

phonestring · optional
emailstring (email) · optional
tax_numberstring · optional

Returns

201 Customer registered

Show attributes
idstring · required
tenant_idstring · required
customer_typestring · required

one of individual, business

categorystring · required

one of residential, commercial, industrial, institutional, government

display_namestring · required
tax_numberstring · optional
emailstring (email) · optional
phonestring · optional
statusstring · required

one of active, suspended, closed

Permissions business:customers:create · Roles: admin, customer_service, owner

curl -X POST "$BUSINESS_API/customers" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "display_name": "Ana Matsinhe",
  "customer_type": "individual",
  "category": "residential",
  "phone": "+258841234567",
  "email": "ana.matsinhe@example.org",
  "tax_number": "TAX-2026-000142"
}'
Response 201
{
  "id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "customer_type": "individual",
  "category": "residential",
  "display_name": "Ana Matsinhe",
  "tax_number": "TAX-2026-000142",
  "email": "ana.matsinhe@example.org",
  "phone": "+258841234567",
  "status": "active"
}

Get a customer in the authenticated utility tenant

Logs

GET /customers/{id}

Returns one customer with its type, category, contact details and status. Requires business:customers:read; an unknown customer returns 404.

Parameters

idstring · path · required

Identifier of the customer in the authenticated tenant.

Returns

200 Customer resource

Show attributes
idstring · required
tenant_idstring · required
customer_typestring · required

one of individual, business

categorystring · required

one of residential, commercial, industrial, institutional, government

display_namestring · required
tax_numberstring · optional
emailstring (email) · optional
phonestring · optional
statusstring · required

one of active, suspended, closed

Permissions business:customers:read · Roles: admin, analyst, billing_clerk, customer_service, field_supervisor, finance, operations, owner, viewer

curl -X GET "$BUSINESS_API/customers/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "customer_type": "individual",
  "category": "residential",
  "display_name": "Ana Matsinhe",
  "tax_number": "TAX-2026-000142",
  "email": "ana.matsinhe@example.org",
  "phone": "+258841234567",
  "status": "active"
}

Get the metadata of a customer

Logs

GET /customers/{id}/metadata

Returns the free-form key-value metadata the tenant has stored on a customer, as a resource_type, resource_id and metadata object. A customer without metadata returns an empty map. Requires business:metadata:read; returns 404 when the customer does not exist in the tenant.

Parameters

idstring · path · required

Identifier of the customer whose metadata is read (at most 120 characters).

Returns

200 Metadata

Show attributes
resource_typestring · optional
resource_idstring · optional
metadataobject · optional

Errors 404

Permissions business:metadata:read · Roles: admin, customer_service, owner

curl -X GET "$BUSINESS_API/customers/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

Merge metadata

Logs

PUT /customers/{id}/metadata

Merge metadata; an empty value deletes the key

Merges the supplied keys into the customer's existing metadata and returns the full result; keys not in the request stay unchanged. A request may set at most 50 keys, each key at most 40 characters with no square brackets or control characters, and each value at most 500 characters; a resource may hold at most 50 keys in total. Requires business:metadata:write; invalid keys or values return 400 listing each offending field, and an unknown customer returns 404.

Parameters

idstring · path · required

Identifier of the customer whose metadata is merged (at most 120 characters).

Body application/json

metadataobject · required

Returns

200 Resulting metadata

Show attributes
resource_typestring · optional
resource_idstring · optional
metadataobject · optional

Errors 400 · 404

Permissions business:metadata:write · Roles: admin, owner

curl -X PUT "$BUSINESS_API/customers/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "metadata": {
    "key": "value"
  }
}'
Response 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

Download a customer statement of account as PDF

Logs

GET /customers/{id}/statement.pdf

Renders the customer's statement of account for a date range and returns it as an inline application/pdf file. Movements before from are summed into the opening balance, and movements inside the range are listed in date order with debits and credits. Without from and to the range is the last year up to today; dates use YYYY-MM-DD, and a malformed date or from after to returns 400. Returns 403 when the caller may not read the customer's statement and 404 when the customer does not exist.

Parameters

idstring · path · required

Customer id

layoutstring · query · optional · default a4

Page format. mobile is one narrow column sized to its content, for reading on a phone. An unknown value renders A4.

one of a4, mobile

fromstring (date) · query · optional

Start of the statement (YYYY-MM-DD); defaults to one year before to

tostring (date) · query · optional

End of the statement (YYYY-MM-DD); defaults to today

Returns

200 PDF document

Errors 403 · 404

Permissions business:customers:read · Roles: admin, analyst, billing_clerk, customer_service, field_supervisor, finance, operations, owner, viewer

curl -X GET "$BUSINESS_API/customers/{id}/statement.pdf" \
  -H "Authorization: Bearer sk_test_..."
Response 200

PDF document