Query leads - Autotouch AI

This page documents the canonical HTTP contract for this endpoint.

Recommended external usage

Use this endpoint as the canonical external lead list/filter surface.
Prefer this over the older query-string GET /api/leads route for new integrations.
Use /api/leads/query/research when you need actual research row values for selected lead IDs.
The response includes research linkage metadata via related_tables and research_summary.

Body parameters

filter · optional
object
Optional FilterDescriptor with root rule/group. Rule operators require value or values except is_empty/is_not_empty; groups require children and NOT requires exactly one child.
search · optional
string
Optional free-text lead search.
sort · optional
array<object>
Optional sort specs; each item is { field, direction }.
pagination · optional
object
Optional { limit, cursor }; limit defaults to 50 and must be >=1, cursor is opaque.
scope · optional
string
Optional scope: org or user.
source_table_id · optional
string
Optional research table context.
source_table_scope · optional
string
Research scope: company or lead; defaults to company.
related_tables_mode · optional
string
Optional related-table expansion mode: linked, direct, or none.
include_research_data · optional
boolean
Optional inline research_data hydration. For external callers, the follow-up /query/research endpoint is usually cleaner.
include_placeholder_leads · optional
boolean
Optional toggle to include placeholder leads.
selection_context · optional
string
Optional descriptor selection context.
ids_only · optional
boolean
Return ID-only query records; defaults to false.
include_count · optional
boolean
Include total_count for the matching query; defaults to false.

Name	Type	Description
filter	object	Optional FilterDescriptor with root rule/group. Rule operators require value or values except is_empty/is_not_empty; groups require children and NOT requires exactly one child.
search	string	Optional free-text lead search.
sort	array<object>	Optional sort specs; each item is { field, direction }.
pagination	object	Optional { limit, cursor }; limit defaults to 50 and must be >=1, cursor is opaque.
scope	string	Optional scope: org or user.
source_table_id	string	Optional research table context.
source_table_scope	string	Research scope: company or lead; defaults to company.
related_tables_mode	string	Optional related-table expansion mode: linked, direct, or none.
include_research_data	boolean	Optional inline research_data hydration. For external callers, the follow-up /query/research endpoint is usually cleaner.
include_placeholder_leads	boolean	Optional toggle to include placeholder leads.
selection_context	string	Optional descriptor selection context.
ids_only	boolean	Return ID-only query records; defaults to false.
include_count	boolean	Include total_count for the matching query; defaults to false.

Errors

Status	Meaning
400	Invalid descriptor payload.
401	Invalid API key or missing auth.
403	Missing leads:read scope.
503	Query/search timeout or CRM text search index unavailable.

Example

bash

curl -X POST "https://app.autotouch.ai/api/leads/query" \
    -H "Authorization: Bearer stk_your_key_id.your_secret" \
    -H "Content-Type: application/json" \
    -d @lead-query.json

Request body

json

{
    "filter": {
      "root": {
        "kind": "group",
        "logic": "and",
        "children": [
          { "kind": "rule", "field": "lead_status", "operator": "eq", "value": "new" },
          { "kind": "rule", "field": "research.tbl_123.col_456", "operator": "contains", "value": "renewal" }
        ]
      }
    },
    "search": "Acme",
    "sort": [
      { "field": "last_contacted", "direction": "desc" }
    ],
    "pagination": {
      "limit": 50
    },
    "scope": "org",
    "source_table_id": "tbl_123",
    "source_table_scope": "company",
    "related_tables_mode": "linked",
    "include_research_data": false
  }

Response example

json

{
    "leads": [
      {
        "id": "67c4b113b4dd8f2d4999f0f1",
        "first_name": "Ada",
        "last_name": "Lovelace",
        "lead_status": "new",
        "company_id": "67c4b2dcb4dd8f2d4999f12a",
        "company_domain": "analyticalengines.com",
        "related_tables": [
          { "id": "tbl_123", "name": "ICP Prospects", "rowCount": null }
        ],
        "research_summary": {
          "primary_table": { "id": "tbl_123", "name": "ICP Prospects", "source": "company", "row_id": "row_123" },
          "direct_tables": [],
          "indirect_tables": [
            { "id": "tbl_123", "name": "ICP Prospects", "source": "company", "row_id": "row_123" }
          ],
          "all_tables": [
            { "id": "tbl_123", "name": "ICP Prospects", "source": "company", "row_id": "row_123" }
          ],
          "counts": { "direct": 0, "indirect": 1, "total": 1 }
        }
      }
    ],
    "next_cursor": "eyJsYXN0X2NvbnRhY3RlZCI6IjIwMjYtMDMtMDYiLCJfaWQiOiI2N2M0YjExM2I0ZGQ4ZjJkNDk5OWYwZjEifQ==",
    "has_more": true,
    "as_of": "2026-03-06T12:00:00Z",
    "total_count": null
  }