List customers

curl --request GET \
  --url https://api.bitnob.com/api/customers \
  --header 'X-Auth-Client: <api-key>' \
  --header 'X-Playground-Client-Secret: <api-key>'

const options = {
  method: 'GET',
  headers: {'X-Auth-Client': '<api-key>', 'X-Playground-Client-Secret': '<api-key>'}
};

fetch('https://api.bitnob.com/api/customers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.bitnob.com/api/customers"

headers = {
    "X-Auth-Client": "<api-key>",
    "X-Playground-Client-Secret": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.bitnob.com/api/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 => [
    "X-Auth-Client: <api-key>",
    "X-Playground-Client-Secret: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bitnob.com/api/customers"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Auth-Client", "<api-key>")
	req.Header.Add("X-Playground-Client-Secret", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "data": {
    "customers": [
      {
        "card_counts": {
          "active": 1,
          "blocked": 0,
          "frozen": 0,
          "lite": 0,
          "pending": 0,
          "pending_termination": 0,
          "prepaid_standard": 0,
          "standard": 1,
          "terminated": 0,
          "total": 1
        },
        "card_program_kyc": [
          {
            "card_program": "collateral",
            "normalized_status": "approved"
          }
        ],
        "city": "Lekki",
        "company_id": "019a3b5c-1a2b-7c3d-8e4f-5a6b7c8d9e01",
        "country": "NGA",
        "created_at": "2026-10-28T14:02:11.482913Z",
        "created_by": "019a3b5c-2b3c-7d4e-9f50-6b7c8d9e0f12",
        "customer_type": "individual",
        "date_of_birth": "1990-04-12",
        "dial_code": "+234",
        "email": "adaeze.okafor@example.com",
        "first_name": "Adaeze",
        "id": "019a3c10-5e6f-7a80-9b1c-2d3e4f5a6b70",
        "id_number": "22200000000",
        "id_type": "bvn",
        "is_active": true,
        "kyc_status": "approved",
        "last_name": "Okafor",
        "line1": "12 Admiralty Way",
        "metadata": "",
        "phone_number": "8000000001",
        "postal_code": "106104",
        "state": "Lagos",
        "updated_at": "2026-10-29T08:12:40.004121Z"
      },
      {
        "card_counts": {
          "active": 0,
          "blocked": 0,
          "frozen": 0,
          "lite": 0,
          "pending": 0,
          "pending_termination": 0,
          "prepaid_standard": 0,
          "standard": 0,
          "terminated": 0,
          "total": 0
        },
        "card_program_kyc": [],
        "city": "Apapa",
        "company_id": "019a3b5c-1a2b-7c3d-8e4f-5a6b7c8d9e01",
        "company_name": "Acme Logistics Ltd",
        "country": "NGA",
        "created_at": "2026-10-27T10:31:45.120044Z",
        "created_by": "019a3b5c-2b3c-7d4e-9f50-6b7c8d9e0f12",
        "customer_type": "business",
        "dial_code": "+234",
        "email": "finance@acmelogistics.example.com",
        "first_name": "Tunde",
        "id": "019a3c11-7a8b-7c9d-8e0f-1a2b3c4d5e61",
        "is_active": true,
        "kyc_status": "",
        "last_name": "Bakare",
        "line1": "4 Creek Road",
        "metadata": "",
        "phone_number": "8000000002",
        "registration_number": "RC0000001",
        "state": "Lagos",
        "updated_at": "2026-10-27T10:31:45.120044Z"
      }
    ],
    "has_more": true,
    "next_cursor": "eyJ0aW1lc3RhbXAiOiIyMDI2LTEwLTI3VDEwOjMxOjQ1LjEyWiIsImlkIjoiMDE5YTNjMTEifQ",
    "page_size": 2,
    "prev_cursor": "",
    "total": 37
  },
  "message": "Customers retrieved successfully",
  "success": true,
  "timestamp": "2026-10-30T09:15:02.481Z"
}

GET

api

customers

List customers

curl --request GET \
  --url https://api.bitnob.com/api/customers \
  --header 'X-Auth-Client: <api-key>' \
  --header 'X-Playground-Client-Secret: <api-key>'

const options = {
  method: 'GET',
  headers: {'X-Auth-Client': '<api-key>', 'X-Playground-Client-Secret': '<api-key>'}
};

fetch('https://api.bitnob.com/api/customers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.bitnob.com/api/customers"

headers = {
    "X-Auth-Client": "<api-key>",
    "X-Playground-Client-Secret": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.bitnob.com/api/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 => [
    "X-Auth-Client: <api-key>",
    "X-Playground-Client-Secret: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bitnob.com/api/customers"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Auth-Client", "<api-key>")
	req.Header.Add("X-Playground-Client-Secret", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "data": {
    "customers": [
      {
        "card_counts": {
          "active": 1,
          "blocked": 0,
          "frozen": 0,
          "lite": 0,
          "pending": 0,
          "pending_termination": 0,
          "prepaid_standard": 0,
          "standard": 1,
          "terminated": 0,
          "total": 1
        },
        "card_program_kyc": [
          {
            "card_program": "collateral",
            "normalized_status": "approved"
          }
        ],
        "city": "Lekki",
        "company_id": "019a3b5c-1a2b-7c3d-8e4f-5a6b7c8d9e01",
        "country": "NGA",
        "created_at": "2026-10-28T14:02:11.482913Z",
        "created_by": "019a3b5c-2b3c-7d4e-9f50-6b7c8d9e0f12",
        "customer_type": "individual",
        "date_of_birth": "1990-04-12",
        "dial_code": "+234",
        "email": "adaeze.okafor@example.com",
        "first_name": "Adaeze",
        "id": "019a3c10-5e6f-7a80-9b1c-2d3e4f5a6b70",
        "id_number": "22200000000",
        "id_type": "bvn",
        "is_active": true,
        "kyc_status": "approved",
        "last_name": "Okafor",
        "line1": "12 Admiralty Way",
        "metadata": "",
        "phone_number": "8000000001",
        "postal_code": "106104",
        "state": "Lagos",
        "updated_at": "2026-10-29T08:12:40.004121Z"
      },
      {
        "card_counts": {
          "active": 0,
          "blocked": 0,
          "frozen": 0,
          "lite": 0,
          "pending": 0,
          "pending_termination": 0,
          "prepaid_standard": 0,
          "standard": 0,
          "terminated": 0,
          "total": 0
        },
        "card_program_kyc": [],
        "city": "Apapa",
        "company_id": "019a3b5c-1a2b-7c3d-8e4f-5a6b7c8d9e01",
        "company_name": "Acme Logistics Ltd",
        "country": "NGA",
        "created_at": "2026-10-27T10:31:45.120044Z",
        "created_by": "019a3b5c-2b3c-7d4e-9f50-6b7c8d9e0f12",
        "customer_type": "business",
        "dial_code": "+234",
        "email": "finance@acmelogistics.example.com",
        "first_name": "Tunde",
        "id": "019a3c11-7a8b-7c9d-8e0f-1a2b3c4d5e61",
        "is_active": true,
        "kyc_status": "",
        "last_name": "Bakare",
        "line1": "4 Creek Road",
        "metadata": "",
        "phone_number": "8000000002",
        "registration_number": "RC0000001",
        "state": "Lagos",
        "updated_at": "2026-10-27T10:31:45.120044Z"
      }
    ],
    "has_more": true,
    "next_cursor": "eyJ0aW1lc3RhbXAiOiIyMDI2LTEwLTI3VDEwOjMxOjQ1LjEyWiIsImlkIjoiMDE5YTNjMTEifQ",
    "page_size": 2,
    "prev_cursor": "",
    "total": 37
  },
  "message": "Customers retrieved successfully",
  "success": true,
  "timestamp": "2026-10-30T09:15:02.481Z"
}

Authorizations

X-Auth-Client

string

header

required

Your workspace client id.

All calls must include four headers:

X-Auth-Client — your workspace client id
X-Auth-Timestamp — Unix seconds
X-Auth-Nonce — 16-byte random hex
X-Auth-Signature — hex(HMAC-SHA256( {client_id}:{timestamp}:{nonce}:{raw_body}, client_secret))

The playground computes the timestamp, nonce and signature for you.

X-Playground-Client-Secret

string

header

required

Your sandbox client secret. The playground uses it to sign the request in your browser and removes it before the request is sent. Never send your client secret as a header in your own integration.

Query Parameters

page_size

integer

default:20

Page size. limit is accepted as an alias. Values below 1 use the default; values above 50 are capped at 50.

Required range: 1 <= x <= 50

limit

integer

default:20

Alias for page_size.

Required range: 1 <= x <= 50

after

string

Opaque cursor from the previous page's next_cursor.

cursor

string

Alias for after.

next_cursor

string

Alias for after.

string<email>

Filter by email address.

phone_number

string

Filter by phone number.

customer_type

string

Comma-separated list of customer types.

Example:

"individual,business"

first_name

string

Filter by first name.

last_name

string

Filter by last name.

company_name

string

Filter by company name.

country

string

Comma-separated list of country codes.

id_type

string

Comma-separated list of ID document types.

city

string

Filter by city.

state

string

Filter by state.

is_active

boolean

Filter by whether the customer is active.

string

Free-text search.

Maximum string length: 255

period

enum<string>

Creation-date window. When set it overrides start_date and end_date, except custom, which requires both.

Available options:

all_time,

last_7_days,

last_1_month,

last_3_months,

last_6_months,

last_12_months,

year_to_date,

custom

start_date

string

Start of the creation-date window, RFC 3339 or YYYY-MM-DD.

end_date

string

End of the creation-date window, RFC 3339 or YYYY-MM-DD.

Response

Successful responses are wrapped in this envelope, and so are errors a handler answers itself (request body and field validation, some not-found and conflict cases, ORG_NOT_ACTIVE): success is false and error carries a code and message. Errors raised by authentication and by the services behind a handler are a Problem instead.

success

boolean

required

true on success

timestamp

string<date-time>

required

When the response was written.

data

object

The payload; its shape is given per operation. Omitted when there is none.

Show child attributes

error

object

Show child attributes

message

string

Human-readable summary; omitted when empty.

metadata

object

List metadata. Page lists set page, per_page, total and total_pages; offset and cursor lists set limit, offset, has_more and next_cursor. Zero and empty fields are omitted, and metadata is absent when nothing is set.

Show child attributes

request_id

string

Set on error envelopes: the request's correlation id (req_ followed by a UUID), the same value as the X-Correlation-ID response header. Quote it to support.

Get started

Identity

Balances

Customers

Beneficiaries

Addresses

Lightning

LNURL

Nodes

Withdrawals

Transfers

Transactions

Exchange rates

Trading

Payouts

Virtual accounts

Virtual cards

List customers

Authorizations

Query Parameters

Response