Skip to main content
GET
/
customers
List customers
curl --request GET \
  --url https://api.cartevo.co/api/v1/customers \
  --header 'Authorization: Bearer <token>'
{
  "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

NameRequiredDescription
AuthorizationYesBearer <access_token>

​
Query parameters

NameTypeDefaultDescription
pageinteger11-indexed page number.
limitinteger10Items per page. Max recommended: 100.
syncbooleanfalseIf 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

StatusTrigger
401Missing 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`);

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[]
​
pagination
object