Ctrl K
Create Customer
POST/api/v1/customers
Creates a new customer (individual or business) and automatically generates a default wallet. No webhook is sent for the customer record itself; use the response to confirm success. A reserve_virtual_account.success webhook is sent for the default wallet's virtual account.
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| returnIfExist | boolean | No | When true, if a matching customer already exists (by email/phone/BVN rules) the API returns success with new_customer: false instead of an error. |
Request Body
| Name | Type | Required | Description |
|---|---|---|---|
| bvn | string | Yes | Exactly 11 digits. Primary identity verification for Nigerian KYC. |
| string | Yes | Valid email; lowercased server-side. | |
| name | string | Yes | Customer name; Unicode NFKC-normalized. |
| phone | string | Yes | Phone; international format applied server-side. |
| id_type | string | No | One of: "international_passport", "nin", "voter_card", "driver_license". |
| id_number | string | No | Supplied with id_type when used. |
| third_party_identifier | string | No | Your stable correlation id. |
| interest_payout_wallet | string | No | PVB wallet id for interest payouts. |
| bypass_withdrawal_limit_rule | boolean | No | Only honoured if the business branch is allowlisted. |
| enable_interest_accrual | boolean | No | If false, disables interest on the created customer path. |
BVN is mandatory: The Bank Verification Number must be exactly 11 digits. It is the primary identity anchor for BVN verification before the customer (and downstream API wallets) are provisioned. Optional NIN-style fields (id_type, id_number) are supplementary in the current implementation and do not replace BVN.
1
Request Example
(cURL)
curl -X POST "https://api.piggyvest.business/api/v1/customers?returnIfExist=true" \-H "Authorization: Bearer YOUR_SECRET_KEY" \-H "Content-Type: application/json" \-d '{ "bvn": "22112200222", "email": "myuser@gmail.com", "name": "John Champion", "phone": "08122299933", "id_type": "nin", "id_number": "08123490456", "third_party_identifier": "71521345-802f-4934-82bb-e0c8f8ff1e9d", "interest_payout_wallet": "023f843a-be7e-494a-bc5d-9f49f4cc640f", "enable_interest_accrual": true}'2
Success Response(200)
(JSON)
{ "status": true, "message": "Customer created successfully", "data": { "customer_id": "905f18f2-858a-4522-9e38-1f5d18bad423", "wallet_id": "023f843a-be7e-494a-bc5d-9f49f4cc640f", "new_customer": true }}3
Error Response(400)
(JSON)
{ "status": false, "message": "An error occurred creating customer"}