Query lead research

Fetch research row values for specific lead IDs from one research table.

POST/api/leads/query/research

HTTP referenceScope leads:readUpdated March 6, 2026

This page documents the canonical HTTP contract for this endpoint.

When to use this endpoint

Use it after /api/leads/query when you know which lead IDs and which research table you care about.

This keeps the main lead query fast and makes research hydration explicit.

Body parameters

lead_idsrequired
array<string>
Lead IDs whose rows should be resolved; may be empty.
source_table_idrequired
string
Research table ID; must be present as a string.
field_ids · optional
array<string>
Optional column ID subset; null omits the restriction.

Name	Type	Description
lead_idsrequired	array<string>	Lead IDs whose rows should be resolved; may be empty.
source_table_idrequired	string	Research table ID; must be present as a string.
field_ids	array<string>	Optional column ID subset; null omits the restriction.

Errors

Status	Meaning
400	Request body does not validate.
401	Invalid API key or missing auth.
403	Missing leads:read scope.

Example

bash

curl -X POST "https://app.autotouch.ai/api/leads/query/research" \
    -H "Authorization: Bearer stk_your_key_id.your_secret" \
    -H "Content-Type: application/json" \
    -d '{"lead_ids":["67c4b113b4dd8f2d4999f0f1"],"source_table_id":"tbl_123"}'

Request body

json

{
    "lead_ids": ["67c4b113b4dd8f2d4999f0f1", "67c4b113b4dd8f2d4999f0f2"],
    "source_table_id": "tbl_123",
    "field_ids": ["col_456", "col_789"]
  }

Response example

json

{
    "research_data_by_id": {
      "67c4b113b4dd8f2d4999f0f1": {
        "col_456": "Renewal risk",
        "col_789": "Hiring 4 AEs"
      },
      "67c4b113b4dd8f2d4999f0f2": null
    }
  }