Customers
curl --request GET \
--url https://carbonapistagingsecure.getcarbon.co/baas/api/v1/customers \
--header 'apikey: <api-key>' \
--header 'x-carbon-key: <x-carbon-key>'const options = {
method: 'GET',
headers: {'x-carbon-key': '<x-carbon-key>', apikey: '<api-key>'}
};
fetch('https://carbonapistagingsecure.getcarbon.co/baas/api/v1/customers', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://carbonapistagingsecure.getcarbon.co/baas/api/v1/customers",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"apikey: <api-key>",
"x-carbon-key: <x-carbon-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}import requests
url = "https://carbonapistagingsecure.getcarbon.co/baas/api/v1/customers"
headers = {
"x-carbon-key": "<x-carbon-key>",
"apikey": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)require 'uri'
require 'net/http'
url = URI("https://carbonapistagingsecure.getcarbon.co/baas/api/v1/customers")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-carbon-key"] = '<x-carbon-key>'
request["apikey"] = '<api-key>'
response = http.request(request)
puts response.read_bodypackage main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://carbonapistagingsecure.getcarbon.co/baas/api/v1/customers"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-carbon-key", "<x-carbon-key>")
req.Header.Add("apikey", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"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"
}
}Customers
Fetch Customers
Retrieve a list of customers with pagination and filtering support.
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>'const options = {
method: 'GET',
headers: {'x-carbon-key': '<x-carbon-key>', apikey: '<api-key>'}
};
fetch('https://carbonapistagingsecure.getcarbon.co/baas/api/v1/customers', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://carbonapistagingsecure.getcarbon.co/baas/api/v1/customers",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"apikey: <api-key>",
"x-carbon-key: <x-carbon-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}import requests
url = "https://carbonapistagingsecure.getcarbon.co/baas/api/v1/customers"
headers = {
"x-carbon-key": "<x-carbon-key>",
"apikey": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)require 'uri'
require 'net/http'
url = URI("https://carbonapistagingsecure.getcarbon.co/baas/api/v1/customers")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-carbon-key"] = '<x-carbon-key>'
request["apikey"] = '<api-key>'
response = http.request(request)
puts response.read_bodypackage main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://carbonapistagingsecure.getcarbon.co/baas/api/v1/customers"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-carbon-key", "<x-carbon-key>")
req.Header.Add("apikey", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"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 bygender, email, bvn, or phone.
Request
Method:GET
URL: /v1/customers
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
x-carbon-key | Header | string | Yes | API key for authentication. |
page | Query | integer | No | Page number for pagination. |
limit | Query | integer | No | Number of customers per page. |
gender | Query | string | No | Filter by gender (e.g. MALE, FEMALE). |
email | Query | string | No | Filter by customer email address. |
bvn | Query | string | No | Filter by Bank Verification Number. |
phone | Query | string | No | Filter 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
| Field | Type | Description |
|---|---|---|
status | string | Request status (success) |
message | string | Human-readable result message |
data | array | List of customer objects |
data[].gender | string | Customer gender (MALE, FEMALE) |
data[].dob | string | Date of birth (ISO 8601) |
data[].address | object | Customer address details |
total | integer | Total number of matching customers |
page | integer | Current page number |
limit | integer | Number of results per page |
filters_applied | object | Active filters used in the query |
Authorizations
Provide your API key in the 'apikey' header.
Headers
Query Parameters
Filter by gender (e.g. MALE, FEMALE)
Filter by customer email address
Filter by Bank Verification Number
Filter by phone number
Response
200 - application/json
OK
The response is of type object.
⌘I