Create list build - Autotouch AI

This page documents the canonical HTTP contract for this endpoint.

Source-driven: the shared create contract supports companies, leads, jobs, and businesses. The selected source controls which inputs and filters apply; consult GET /api/list-builds/inputs and the source-specific operation metadata rather than assuming every field applies to every kind.

Company and people search: use leadmagic_company_search for companies and leadmagic_people_search for people. Read lists.build_companies or lists.build_people operation detail for the complete current filter schema. Named employer domains belong in people-search employer filters; provider company IDs are not interchangeable with your CRM IDs.

More of the same: POST {"kind":"companies","continuation":{"from_job_id":"lb_prior","additional_results":100}} to this endpoint (use leads for people). The prior build must be completed, owned by the caller, have more results, and have completed table delivery with a saved mapping. Continue after delivery finishes; the host restores the saved cursor, filters and table. Exhausted searches and changed criteria produce validation errors. An expired provider snapshot can restart once with unchanged filters and destination deduplication; further expiry fails explicitly. Stored-result pagination is separate from acquiring more results.

People example: {"kind":"leads","num_results":20,"source":{"type":"leadmagic_people_search","inputs":{"title":"SDR Manager","title_variants":["SDR Manager","Sales Development Manager"]}},"filters":{"people_filters":{"contact_city":["New York"],"contact_country_code":["US"]}},"destination":{"mode":"create","table_name":"SDR managers in NYC"}}. Add employer filters through company_filters; do not infer extra seniority or department restrictions solely from the title.

Native limits: company and people searches use pages of at most 25. Bounded requests support up to 1,500 results. Use the operation contract for source-specific formats and constraints. Contact availability is resolved later through contact finders.

source_scope carries source or preview context, never pagination; unsupported keys are rejected. The current list-build path preserves it in request/source evidence but does not constrain selection using its company entries. audience_fit_rubric is consumed only for lead builds and provides candidate-scoring inputs; it is not a universal search filter. The rubric is discarded unless it includes at least one positive-signal list field.

List-build rates and whether billing is enabled are runtime-configured. Call List-build pricing before quoting a charge; each accepted job and result read also reports its own execution facts.

See List-build input catalog and Search list-build inputs for available, operation-scoped values.

Body parameters

kind · optional
string
List kind: companies, leads, jobs, or businesses. It may also be inferred from source.type or target.kind.
source · optional
object
Source envelope. Its type and source-specific inputs select an enabled list-build profile; see the source catalog and operation metadata.
target · optional
object
Optional target envelope. For bounded jobs and local businesses use top-level completion_mode and num_results.
list_name · optional
string
Optional human-readable job/list name.
keywords · optional
string
Company keywords for company lists, or optional free-text lead keywords.
title · optional
string
Person title phrase. Put OR alternatives in source.inputs.title_variants; do not encode Boolean syntax into one title.
filters · optional
object
Source-specific structured filters. Consult the source input catalog and selected source contract.
destination · optional
object
Optional destination envelope for source/target workflows.
options · optional
object
Optional source-specific execution options.
dedupe · optional
object
Optional deduplication configuration.
continuation · optional
object
Resume a completed delivered native company/people build with {from_job_id, additional_results}. Additional results must be 1–1500. The host restores unchanged filters and the destination; omit a new source or filters.
presentation · optional
object
Optional result presentation settings.
source_scope · optional
object
Optional source context with type, source_preview_id, company_count, and up to 100 companies (name, domain, linkedin_company_id, linkedin_url). The current list-build path preserves this for source evidence; it does not apply the company entries as a selection constraint.
audience_fit_rubric · optional
object
Optional lead-build scoring rubric. Accepted list fields: target_titles, target_title_keywords, target_functions, target_seniorities, target_domain_role_tags, positive_keywords, exclude_keywords, negative_flags (each item is normalized and capped at 180 characters). It must contain at least one positive-signal list item or it is discarded. Optional text fields: rubric_version (80 chars), rubric_name (160), rubric_summary (500), source (120). Optional screening_policy accepts likely_threshold and possible_threshold, normalized to integers within 0–100; when a policy is retained their defaults are 75 and 50, and likely is raised to possible if lower. Unrecognized fields are ignored.
completion_mode · optional
string
For bounded source jobs, bounded or all_available when that source supports both.
num_results · optional
integer
Requested result count for supported sources. Must be 1–10,000 at the typed boundary; source-specific limits apply.
page_size · optional
integer
Requested page size; typed range 1–100. Source-specific limits apply.
filters.people_filters · optional
object
People search: person location, seniority, department, persona and supported flags. Use contact_city, contact_state (name), and contact_country_code for person geography.
filters.company_filters · optional
object
People search: employer constraints including size, funding, industry, specialties and technology.
filters.max_employees · optional
integer
Company search inclusive maximum employee count. Under 25 means 24. The people equivalent belongs in company_filters.
source.inputs.title_variants · optional
array<string>
People search: up to 12 combined title phrases, ORed. Variants must preserve the requested role.

Name	Type	Description
kind	string	List kind: companies, leads, jobs, or businesses. It may also be inferred from source.type or target.kind.
source	object	Source envelope. Its type and source-specific inputs select an enabled list-build profile; see the source catalog and operation metadata.
target	object	Optional target envelope. For bounded jobs and local businesses use top-level completion_mode and num_results.
list_name	string	Optional human-readable job/list name.
keywords	string	Company keywords for company lists, or optional free-text lead keywords.
title	string	Person title phrase. Put OR alternatives in source.inputs.title_variants; do not encode Boolean syntax into one title.
filters	object	Source-specific structured filters. Consult the source input catalog and selected source contract.
destination	object	Optional destination envelope for source/target workflows.
options	object	Optional source-specific execution options.
dedupe	object	Optional deduplication configuration.
continuation	object	Resume a completed delivered native company/people build with {from_job_id, additional_results}. Additional results must be 1–1500. The host restores unchanged filters and the destination; omit a new source or filters.
presentation	object	Optional result presentation settings.
source_scope	object	Optional source context with type, source_preview_id, company_count, and up to 100 companies (name, domain, linkedin_company_id, linkedin_url). The current list-build path preserves this for source evidence; it does not apply the company entries as a selection constraint.
audience_fit_rubric	object	Optional lead-build scoring rubric. Accepted list fields: target_titles, target_title_keywords, target_functions, target_seniorities, target_domain_role_tags, positive_keywords, exclude_keywords, negative_flags (each item is normalized and capped at 180 characters). It must contain at least one positive-signal list item or it is discarded. Optional text fields: rubric_version (80 chars), rubric_name (160), rubric_summary (500), source (120). Optional screening_policy accepts likely_threshold and possible_threshold, normalized to integers within 0–100; when a policy is retained their defaults are 75 and 50, and likely is raised to possible if lower. Unrecognized fields are ignored.
completion_mode	string	For bounded source jobs, bounded or all_available when that source supports both.
num_results	integer	Requested result count for supported sources. Must be 1–10,000 at the typed boundary; source-specific limits apply.
page_size	integer	Requested page size; typed range 1–100. Source-specific limits apply.
filters.people_filters	object	People search: person location, seniority, department, persona and supported flags. Use contact_city, contact_state (name), and contact_country_code for person geography.
filters.company_filters	object	People search: employer constraints including size, funding, industry, specialties and technology.
filters.max_employees	integer	Company search inclusive maximum employee count. Under 25 means 24. The people equivalent belongs in company_filters.
source.inputs.title_variants	array<string>	People search: up to 12 combined title phrases, ORed. Variants must preserve the requested role.

Errors

Status	Meaning
400	Invalid kind, missing required search signal, or invalid filter value.
401	Invalid API key or missing auth.
403	Missing search:run scope.
402	Insufficient credits.

Example

bash

curl -X POST "https://app.autotouch.ai/api/list-builds" \
  -H "Authorization: Bearer stk_your_key_id.your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "companies",
    "list_name": "US software companies",
    "source": {"type": "leadmagic_company_search"},
    "num_results": 100,
    "filters": {"industries": ["Software Development"], "country_codes": ["US"]}
  }'

Request body

json

{
  "kind": "companies",
  "list_name": "US software companies",
  "source": {"type": "leadmagic_company_search"},
  "num_results": 100,
  "filters": {
    "industries": ["Software Development"],
    "country_codes": ["US"]
  }
}

Response example

json

{
  "job_id": "lb_1234567890abcdef12345678",
  "kind": "companies",
  "list_name": "US software companies",
  "status": "queued",
  "stage": "queued",
  "message": "Queued",
  "progress": 0,
  "source": {"type": "leadmagic_company_search"},
  "source_type": "leadmagic_company_search",
  "target": {"requested_count": 100},
  "total_results": 0,
  "target_results": 100,
  "credits_used": 0
}