Skip to main content
GET
/
v1
/
customers
Customers
curl --request GET \
  --url https://carbonapistagingsecure.getcarbon.co/baas/api/v1/customers \
  --header 'apikey: <api-key>' \
  --header 'x-carbon-key: <x-carbon-key>'
{
  "status": "success",
  "message": "Customers fetched successfully",
  "data": [
    {
      "id": "1732ca47-42b2-4990-a65d-c369e934eed3",
      "first_name": "adisa",
      "last_name": "cooker",
      "email": "adisa@yahoo.com",
      "phone": "08071000030",
      "gender": "MALE",
      "dob": "1989-12-31T23:00:00.000Z",
      "address": {
        "street": "NO 1 LAGOS ROAD",
        "city": "IKEJA",
        "state": "LAGOS STATE",
        "country": "NIGERIA"
      },
      "nin": "11111111111",
      "bvn": "11111011116",
      "is_business": false,
      "business_name": "",
      "mode": "sandbox",
      "created_at": "2025-08-19T13:24:12+01:00",
      "updated_at": "2025-08-19T13:24:12+01:00"
    }
  ],
  "total": 6,
  "page": 1,
  "limit": 10,
  "filters_applied": {
    "bvn": "11111011116"
  }
}

​
Overview

This endpoint retrieves a list of customers with pagination and optional filtering by gender, email, bvn, or phone.

​
Request

Method: GET URL: /v1/customers

​
Parameters

NameInTypeRequiredDescription
x-carbon-keyHeaderstringYesAPI key for authentication.
pageQueryintegerNoPage number for pagination.
limitQueryintegerNoNumber of customers per page.
genderQuerystringNoFilter by gender (e.g. MALE, FEMALE).
emailQuerystringNoFilter by customer email address.
bvnQuerystringNoFilter by Bank Verification Number.
phoneQuerystringNoFilter by phone number.

​
Response

Status Code: 200 OK Content-Type: application/json

​
Example Response

{
  "status": "success",
  "message": "Customers fetched successfully",
  "data": [
    {
      "id": "1732ca47-42b2-4990-a65d-c369e934eed3",
      "first_name": "adisa",
      "last_name": "cooker",
      "email": "adisa@yahoo.com",
      "phone": "08071000030",
      "gender": "MALE",
      "dob": "1989-12-31T23:00:00.000Z",
      "address": {
        "street": "NO 1 LAGOS ROAD",
        "city": "IKEJA",
        "state": "LAGOS STATE",
        "country": "NIGERIA"
      },
      "nin": "11111111111",
      "bvn": "11111011116",
      "is_business": false,
      "business_name": "",
      "mode": "sandbox",
      "created_at": "2025-08-19T13:24:12+01:00",
      "updated_at": "2025-08-19T13:24:12+01:00"
    }
  ],
  "total": 6,
  "page": 1,
  "limit": 10,
  "filters_applied": {
    "bvn": "11111011116"
  }
}

​
Response Fields

FieldTypeDescription
statusstringRequest status (success)
messagestringHuman-readable result message
dataarrayList of customer objects
data[].genderstringCustomer gender (MALE, FEMALE)
data[].dobstringDate of birth (ISO 8601)
data[].addressobjectCustomer address details
totalintegerTotal number of matching customers
pageintegerCurrent page number
limitintegerNumber of results per page
filters_appliedobjectActive filters used in the query

Authorizations

​
apikey
string
header
required

Provide your API key in the 'apikey' header.

Headers

​
x-carbon-key
string
required

Query Parameters

​
page
integer
​
limit
integer
​
gender
string

Filter by gender (e.g. MALE, FEMALE)

​
email
string

Filter by customer email address

​
bvn
string

Filter by Bank Verification Number

​
phone
string

Filter by phone number

Response

200 - application/json

OK

The response is of type object.