Skip to content
Rotor API Logo Rotor API
Get started
API Reference
Customers

List customers

client.customers.list(CustomerListParams { rotorAPIVersion, archived, limit, 4 more } params, RequestOptionsoptions?): CustomerListResponse { data, pagination, status }
GET/customers

Returns a paginated list of customers for the authenticated company.

ParametersExpand Collapse
params: CustomerListParams { rotorAPIVersion, archived, limit, 4 more }
rotorAPIVersion: "1.1.0"

Header param: Required OpenAPI version header.

archived?: boolean

Query param: Include archived customers (default false)

limit?: number

Query param: Number of results per page (max 1000)

minimum1
maximum1000
page?: number

Query param: Page number (1-based)

minimum1

Query param: Search by first name, last name, company name, email, or phone

status?: "active" | "inactive"

Query param: Filter by customer status

One of the following:
"active"
"inactive"
tags?: string

Query param: Filter by tags (comma-separated)

ReturnsExpand Collapse
CustomerListResponse { data, pagination, status }
data?: Array<Data>
id?: string
address?: Address { city, country, state, 3 more }
city: string
country: string
state: string
street1: string
zip: string
street2?: string | null
company_name?: string
created_at?: string
email?: string
first_name?: string
has_payment_method?: boolean

Whether the customer has at least one saved payment method on file

last_name?: string
location?: Array<number> | null
notes?: string | null
phone?: string
source?: string
status?: "active" | "inactive"
One of the following:
"active"
"inactive"
tags?: Array<string> | null

Whether more pages are available

Total number of matching records

status?: string

List customers

import Rotor from 'getrotor';

const client = new Rotor({
  rotorAPIVersion: '1.1.0',
  apiKey: process.env['ROTOR_API_KEY'], // This is the default and can be omitted
});

const customers = await client.customers.list({ 'rotor-api-version': '1.1.0' });

console.log(customers.data);
{
  "data": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "address": {
        "city": "city",
        "country": "country",
        "state": "state",
        "street1": "street1",
        "zip": "zip",
        "street2": "street2"
      },
      "company_name": "company_name",
      "created_at": "2019-12-27T18:11:19.117Z",
      "email": "dev@stainless.com",
      "first_name": "first_name",
      "has_payment_method": true,
      "last_name": "last_name",
      "location": [
        0
      ],
      "notes": "notes",
      "phone": "phone",
      "source": "source",
      "status": "active",
      "tags": [
        "string"
      ]
    }
  ],
  "pagination": {
    "has_more": true,
    "limit": 50,
    "page": 1,
    "total": 142
  },
  "status": "success"
}
{
  "status": "error",
  "message": "Authentication required. Provide x-api-key header.",
  "error_code": "AUTHENTICATION_REQUIRED"
}
{
  "status": "error",
  "message": "Forbidden: required scope 'leads:read' not granted for this API key",
  "error_code": "INSUFFICIENT_SCOPE"
}
{
  "status": "error",
  "message": "Daily API key request limit of 1000 exceeded",
  "error_code": "RATE_LIMIT_EXCEEDED"
}
{
  "status": "error",
  "message": "Internal server error"
}
Returns Examples
{
  "data": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "address": {
        "city": "city",
        "country": "country",
        "state": "state",
        "street1": "street1",
        "zip": "zip",
        "street2": "street2"
      },
      "company_name": "company_name",
      "created_at": "2019-12-27T18:11:19.117Z",
      "email": "dev@stainless.com",
      "first_name": "first_name",
      "has_payment_method": true,
      "last_name": "last_name",
      "location": [
        0
      ],
      "notes": "notes",
      "phone": "phone",
      "source": "source",
      "status": "active",
      "tags": [
        "string"
      ]
    }
  ],
  "pagination": {
    "has_more": true,
    "limit": 50,
    "page": 1,
    "total": 142
  },
  "status": "success"
}
{
  "status": "error",
  "message": "Authentication required. Provide x-api-key header.",
  "error_code": "AUTHENTICATION_REQUIRED"
}
{
  "status": "error",
  "message": "Forbidden: required scope 'leads:read' not granted for this API key",
  "error_code": "INSUFFICIENT_SCOPE"
}
{
  "status": "error",
  "message": "Daily API key request limit of 1000 exceeded",
  "error_code": "RATE_LIMIT_EXCEEDED"
}
{
  "status": "error",
  "message": "Internal server error"
}