---
title: "POST /billpay/bulk-create-customer-control-numbers"
method: POST
path: "/billpay/bulk-create-customer-control-numbers"
---

# POST /billpay/bulk-create-customer-control-numbers

`POST /billpay/bulk-create-customer-control-numbers`

Bulk create BillPay Customer Control Numbers (max 50 per request). Each item follows the single-create format. Supports partial success — valid items are created; invalid ones are returned in the errors array

## Request body

- object
  - `controlNumbers` object[], required — Array of customer control number items
    - `customerName` string, required — Name of the customer
    - `customerEmail` string — Email (required if customerPhone not provided)
    - `customerPhone` string — Phone - 12 digits, country code, no plus (required if customerEmail not provided)
    - `billReference` string — Custom bill reference
    - `billAmount` number — Amount of the bill
    - `billDescription` string — Description of the bill
    - `billPaymentMode` 'ALLOW_PARTIAL_AND_OVER_PAYMENT' | 'EXACT' — Payment mode

## Response `200`

Bulk create result - may include partial success with per-item errors

- BulkCreateResponse
  - `billPayNumbers` string[] — Array of successfully created BillPay numbers
  - `created` number — Count of successfully created control numbers
  - `failed` number — Count of failed items
  - `errors` object[] — Present only when failed > 0
    - `index` number — 0-based index of the failed item in the request array
    - `reason` string — Error message for the failed item

## Other responses

- `400` — Validation Error
- `401` — Unauthorized

---

[API](https://skmtc.net/clickpesa/apis/core-api-openapi-specification.md) · [All operations](https://skmtc.net/clickpesa/apis/core-api-openapi-specification/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/clickpesa/core-api-openapi-specification/versions/9f70f35c5590/schema)