List Customers

List customers

curl --request GET \
  --url https://api.cartevo.co/api/v1/customers \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.cartevo.co/api/v1/customers"

headers = {"Authorization": "Bearer <token>"}

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

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.cartevo.co/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://api.cartevo.co/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 => [
    "Authorization: Bearer <token>"
  ],
]);

$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.cartevo.co/api/v1/customers"

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

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.cartevo.co/api/v1/customers")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cartevo.co/api/v1/customers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "statusCode": 200,
  "message": "Data retrieved successfully",
  "data": [
    {
      "id": "4d4dad81-7899-4612-a9f6-133ce56a4507",
      "email": "customer@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "is_active": true,
      "country": "Cameroon",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 15,
    "totalPages": 1
  }
}

GET

customers

List customers

curl --request GET \
  --url https://api.cartevo.co/api/v1/customers \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.cartevo.co/api/v1/customers"

headers = {"Authorization": "Bearer <token>"}

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

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.cartevo.co/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://api.cartevo.co/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 => [
    "Authorization: Bearer <token>"
  ],
]);

$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.cartevo.co/api/v1/customers"

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

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.cartevo.co/api/v1/customers")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cartevo.co/api/v1/customers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "statusCode": 200,
  "message": "Data retrieved successfully",
  "data": [
    {
      "id": "4d4dad81-7899-4612-a9f6-133ce56a4507",
      "email": "customer@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "is_active": true,
      "country": "Cameroon",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 15,
    "totalPages": 1
  }
}

Overview

GET /customers returns a paginated list of customers registered under your company. Use it to render a back-office customer list, search, or to reconcile your local cache against Cartevo.

When to use it

Render a “all customers” view in your dashboard.
Find a customer by name/email when their ID is not at hand.
Reconcile your local customer database against Cartevo’s source of truth.

Prerequisites

Authenticated as a company user.

Request

Headers

Name	Required	Description
`Authorization`	Yes	`Bearer <access_token>`

Query parameters

Name	Type	Default	Description
`page`	integer	`1`	1-indexed page number.
`limit`	integer	`10`	Items per page. Max recommended: `100`.
`sync`	boolean	`false`	If `true`, force a re-sync from the upstream provider before returning. Slower; use sparingly.

Response

200 — Success

{
  "success": true,
  "statusCode": 200,
  "message": "10 items retrieved successfully",
  "data": [
    {
      "id": "8d4f2a1b-5c3e-4d7f-9a6b-2e1c8f9d0a3b",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "country": "Cameroon",
      "phone_country_code": "+237",
      "phone_number": "600000000",
      "is_active": true,
      "created_at": "2026-05-09T10:15:00.000Z",
      "updated_at": "2026-05-09T10:15:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 137,
    "totalPages": 14
  }
}

For the per-customer field reference, see GET /customers/{id}.

Error responses

Status	Trigger
`401`	Missing or expired Bearer token.

Code examples

cURL

curl -G https://api.cartevo.co/api/v1/customers \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=50"

Node.js (axios)

const { data } = await axios.get("https://api.cartevo.co/api/v1/customers", {
  headers: { Authorization: `Bearer ${token}` },
  params: { page: 1, limit: 50 },
});
console.log(`${data.meta.total} customers total`);

POST /customers — register a new customer.
GET /customers/{id} — full customer detail.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

page

integer

Example:

1

limit

integer

Example:

20

Response

200 - application/json

A list of customers.

success

boolean

Example:

true

statusCode

integer

Example:

200

message

string

Example:

"Data retrieved successfully"

data

object[]

Show child attributes

pagination

object

Show child attributes

Terminate Card Enroll Customer

API documentation

Auth

Cards

Customers

Wallets

Payment Collection

Webhook

Overview

When to use it

Prerequisites

Request

Headers

Query parameters

Response

200 — Success

Error responses

Code examples

Authorizations

Query Parameters

Response

​Overview

​When to use it

​Prerequisites

​Request

​Headers

​Query parameters

​Response

​200 — Success

​Error responses

​Code examples

​Related

Authorizations

Query Parameters

Response

Overview

When to use it

Prerequisites

Request

Headers

Query parameters

Response

200 — Success

Error responses

Code examples

Related