API Reference

Leads

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

List leads

client.leads.list(LeadListParams { rotorAPIVersion, archived, limit, 4 more } params, RequestOptionsoptions?): LeadListResponse { data, pagination, status }

GET/leads

Returns a paginated list of leads for the authenticated company. Results are ordered by creation date (newest first).

ParametersExpand Collapse

params: LeadListParams { rotorAPIVersion, archived, limit, 4 more }

rotorAPIVersion: "1.1.0"

Header param: Required OpenAPI version header.

archived?: boolean

Query param: Include archived leads (default false)

limit?: number

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

minimum1

maximum1000

page?: number

Query param: Page number (1-based)

minimum1

search?: string

Query param: Search by name, email, or phone

stage?: string

Query param: Filter by pipeline stage

tags?: string

Query param: Filter by tags (comma-separated). Returns leads that have any of the specified tags.

ReturnsExpand Collapse

LeadListResponse { data, pagination, status }

data?: Array<Data>

id?: string

archived?: boolean | null

archived_at?: string | null

assigned_to?: string | null

created_at?: string | null

email?: string | null

follow_up_date?: string | null

lead_source?: string | null

location?: Array<number> | null

name?: string

notes?: string | null

phone?: string | null

priority?: "low" | "medium" | "high" | null

One of the following:

"low"

"medium"

"high"

projected_value?: number | null

property_city?: string | null

property_country?: string | null

property_state?: string | null

property_street1?: string | null

property_street2?: string | null

property_zip?: string | null

service_type?: string | null

stage?: string | null

Pipeline stage

tags?: Array<string>

value_score?: number | null

pagination?: Pagination { has_more, limit, page, total }

has_more?: boolean

Whether more pages are available

limit?: number

page?: number

total?: number

Total number of matching records

status?: string

List leads

TypeScript

HTTP

TypeScript

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 leads = await client.leads.list({ 'rotor-api-version': '1.1.0' });

console.log(leads.data);

200 example

401 example

403 example

429 example

500 example

{
  "data": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "archived": true,
      "archived_at": "2019-12-27T18:11:19.117Z",
      "assigned_to": "assigned_to",
      "created_at": "2019-12-27T18:11:19.117Z",
      "email": "dev@stainless.com",
      "follow_up_date": "2019-12-27T18:11:19.117Z",
      "lead_source": "lead_source",
      "location": [
        0
      ],
      "name": "name",
      "notes": "notes",
      "phone": "phone",
      "priority": "low",
      "projected_value": 0,
      "property_city": "property_city",
      "property_country": "property_country",
      "property_state": "property_state",
      "property_street1": "property_street1",
      "property_street2": "property_street2",
      "property_zip": "property_zip",
      "service_type": "service_type",
      "stage": "stage",
      "tags": [
        "string"
      ],
      "value_score": 0
    }
  ],
  "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

200 example

401 example

403 example

429 example

500 example

{
  "data": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "archived": true,
      "archived_at": "2019-12-27T18:11:19.117Z",
      "assigned_to": "assigned_to",
      "created_at": "2019-12-27T18:11:19.117Z",
      "email": "dev@stainless.com",
      "follow_up_date": "2019-12-27T18:11:19.117Z",
      "lead_source": "lead_source",
      "location": [
        0
      ],
      "name": "name",
      "notes": "notes",
      "phone": "phone",
      "priority": "low",
      "projected_value": 0,
      "property_city": "property_city",
      "property_country": "property_country",
      "property_state": "property_state",
      "property_street1": "property_street1",
      "property_street2": "property_street2",
      "property_zip": "property_zip",
      "service_type": "service_type",
      "stage": "stage",
      "tags": [
        "string"
      ],
      "value_score": 0
    }
  ],
  "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"
}