Leads

List leads

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

GET

/leads

List leads

curl --request GET \
  --url 'https://api.getrotor.com/open-api/leads?page=1&limit=50&stage=qualified&archived=false&tags=web-form%2Cinterested&search=John' \
  --header 'x-api-key: <api-key>' \
  --header 'rotor-api-version: 1.1.0'

{
  "data": [
    {
      "archived": true,
      "archived_at": "2023-11-07T05:31:56Z",
      "assigned_to": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "email": "jsmith@example.com",
      "follow_up_date": "2023-11-07T05:31:56Z",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "lead_source": "<string>",
      "location": [
        123
      ],
      "name": "<string>",
      "notes": "<string>",
      "phone": "<string>",
      "priority": "low",
      "projected_value": 123,
      "property_city": "<string>",
      "property_country": "<string>",
      "property_state": "<string>",
      "property_street1": "<string>",
      "property_street2": "<string>",
      "property_zip": "<string>",
      "service_type": "<string>",
      "stage": "<string>",
      "tags": [
        "<string>"
      ],
      "value_score": 123
    }
  ],
  "pagination": {
    "has_more": true,
    "limit": 50,
    "page": 1,
    "total": 142
  },
  "status": "success"
}

Authorizations

x-api-keystringheaderrequired

Company API key in the format: rotor_{keyId}_{keySecret}

To obtain an API key:

Log into your Rotor dashboard
Go to Settings → Integrations → API Keys
Create a new key and select the scopes you need
Copy the key — it's only shown once!

Query Parameters

pageintegerquerydefault:1

Page number (1-based)

Required range: 1 <= x

Example: 1

limitintegerquerydefault:50

Number of results per page (max 1000)

Required range: 1 <= x <= 1000

Example: 50

stagestringquery

Filter by pipeline stage

Example: qualified

archivedbooleanquery

Include archived leads (default false)

Example: false

tagsstringquery

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

Example: web-form,interested

searchstringquery

Search by name, email, or phone

Example: John

Headers

rotor-api-versionenum<string>headerdefault:1.1.0required

Required OpenAPI version header.

Available options: 1.1.0

Example: 1.1.0

Response

Leads listed successfully

dataobject[]

Show child attributes

paginationobject

Show child attributes

statusstring

Example: success

Still need help? Ask the team