Reference
Customers
Full CRUD plus find-or-create and search. PII is encrypted at rest and decrypted for API responses.
The customers module is the contact directory for sales. Create customers
upfront, or use find-or-create to avoid duplicates when syncing from
WooCommerce or Shopify.
PII fields (email, phone, tin, address) are encrypted at rest. The
API decrypts on read, so responses always contain plaintext.
List customers
/v1/customersReturns active customers, sorted by name.
Query parameters
| Field | Type | Required | Notes |
|---|---|---|---|
businessId | string | yes | |
limit | integer | no | Default 50, max 100. |
Soft-deleted customers are excluded.
Get a single customer
/v1/customers/{id}Fetches one customer.
Response — 200
{
"success": true,
"data": {
"id": "cust_xyz",
"name": "Acme Ltd",
"email": "finance@acme.com",
"phone": "+2348012345678",
"address": "15 Adeola Odeku St, Victoria Island, Lagos",
"tin": "12345678-0001",
"companyName": "Acme Technologies Ltd",
"accountBalanceKobo": 0,
"accountBalance": 0,
"isActive": true,
"createdAt": "2026-03-20T09:15:00.000Z"
}
}Search customers
/v1/customers/searchSubstring match on name or email, among active customers only.
Query parameters
| Field | Type | Required | Notes |
|---|---|---|---|
businessId | string | yes | |
q | string | yes | Case-insensitive substring. |
Example
curl "https://api.finorabusiness.com/v1/customers/search?businessId=$BID&q=acme" \
-H "Authorization: Bearer $FINORA_API_KEY"Returns up to 50 matches in { customers, count }.
Find or create
/v1/customers/find-or-createIdempotent lookup by email. Returns existing customer if found, otherwise creates one.
Use this for integrations that receive a new order per shopper — you won't create duplicate Finora Business customer records for repeat buyers.
Body
| Field | Type | Required | Notes |
|---|---|---|---|
email | string | yes | The match key. Lowercased and hashed internally. |
name | string | no | Used only when creating. Defaults to the email local part. |
phone | string | no | Used only when creating. |
Response
A created: true flag indicates a new record. created: false means an
existing customer was matched on email_hash.
{
"success": true,
"data": {
"id": "cust_xyz",
"name": "Jane Doe",
"email": "jane@example.com",
"created": false
}
}Create a customer
/v1/customersCreates a customer with the full field set.
Body
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | yes | Display name. Max 200 chars. |
email | string | yes | Lowercased and encrypted on write. |
phone | string | no | |
address | string | no | |
companyName | string | no | |
tin | string | no | Nigerian Tax Identification Number. |
Update a customer
/v1/customers/{id}Updates any of name, email, phone, address, companyName, tin.
Unknown fields are ignored. To soft-delete, use the DELETE method instead.
Soft-delete a customer
/v1/customers/{id}Marks the customer inactive. Historical invoices and receipts are preserved.
Soft-deleted customers no longer appear in GET /v1/customers or
/v1/customers/search. Their transaction history remains queryable through
invoices and receipts.
Related endpoints
Reference index
Back to all modules