List Building

Build company lists using Extruct API methods, guided by a decision tree. Reads from the company context file for ICP and seed companies.

Trigger Phrases

“find companies”, “build a list”, “company search”, “prospect list”, “target accounts”, “outbound list”, “discover companies”, “ICP search”, “lookalike search”, “seed company”

Official API Reference

https://www.extruct.ai/docs

Decision Tree

Before running any queries, determine the right approach:

Have a seed company from win cases or context file?
  YES → Method 1: Lookalike Search (pass seed domain)
  NO  ↓

New vertical, need broad exploration?
  YES → Method 2: Semantic Search (3-5 queries from different angles)
  NO  ↓

Need qualification against specific criteria?
  YES → Method 3: Discovery API (criteria-scored async research)
  NO  ↓

Need maximum coverage?
  YES → Combine Search + Discovery (~15% overlap expected)

Before You Start

Read the company context file if it exists:

claude-code-gtm/context/{company}_context.md

Extract:

ICP profiles - for query design and filters
Win cases - for seed companies in lookalike mode
DNC list - domains to exclude from results

Also check for a hypothesis set at claude-code-gtm/context/{vertical-slug}/hypothesis_set.md. If it exists, use the Search angle field from each hypothesis to design search queries - these are pre-defined query suggestions tailored to each pain point.

Environment

Variable	Service
`EXTRUCT_API_TOKEN`	Extruct API

Before making API calls, check that EXTRUCT_API_TOKEN is set by running test -n "$EXTRUCT_API_TOKEN" && echo "set" || echo "missing". If missing, ask the user to provide their Extruct API token and set it via export EXTRUCT_API_TOKEN=<value>. Do not proceed until confirmed.

Base URL: https://api.extruct.ai/v1

Method 1: Lookalike Search

Use when you have a seed company (from win cases, existing customers, or user input). Endpoint: GET /companies/{identifier}/similar where identifier is a domain or company UUID.

Key Parameters

filters

object

JSON with include (size, country) and range (founded)

limit

number

default:"100"

Max results (up to 200)

offset

number

For pagination

Response Fields

name, domain, short_description, founding_year, employee_count, hq_country, hq_city, relevance_score

When to Use Lookalike

You have a happy customer and want more like them
Context file has win cases with domains
User says “find companies similar to X”

Tips

Run multiple similar-company searches with different seed companies for broader coverage
Combine with filters to constrain geography or size
Deduplicate across runs by domain
Default to limit=100; increase up to 200 when broader coverage is needed

Method 2: Semantic Search - Fast, Broad

Endpoint: GET /companies/search

Key Parameters

string

required

Natural language query describing the target companies

filters

object

JSON with include (size, country) and range (founded)

limit

number

default:"100"

Max results (up to 200)

Response Fields

name, domain, short_description, founding_year, employee_count, hq_country, hq_city, relevance_score

Query Strategy

Write 3-5 queries per campaign, each from a different angle on the same ICP
Describe the product/use case, not the company type
Deduplicate across queries by domain - overlap is expected
Default to limit=100 per query; increase up to 200 when needed
Target 200-800 companies total across all queries

Method 3: Discovery API - Deep, Qualified

Endpoint: POST /discovery_tasks

Key Parameters

query

string

required

2-3 sentence description of the ideal company (like a job description)

desired_num_results

number

default:"50"

Target result count

criteria

array

List of { key, name, criterion } objects for auto-grading (up to 5)

Polling

Poll: GET /discovery_tasks/{task_id} - status: created | in_progress | done | failed. Poll every 60 seconds. Fetch results: GET /discovery_tasks/{task_id}/results with limit and offset params.

Response Fields

company_name, company_website, company_description, relevance (0-100), scores (per-criteria grade 1-5 with explanation), founding_year

Query Strategy

Write queries like a job description - 2-3 sentences describing the ideal company
Use criteria to auto-qualify - each company gets graded 1-5 per criterion
Default desired_num_results=50 for first pass; expand after quality review
Use up to 5 criteria per task; keep criteria focused and non-overlapping
Run separate tasks for different ICP segments
Scans many candidates to find qualified matches - runtime depends on query scope
Up to 250 results per task

Upload to Table

Create a company kind table via POST /tables with a single input column (kind: "input", key: "input"). Extruct auto-enriches each domain with a Company Profile. Upload domains in batches of 50 via POST /tables/{table_id}/rows. Each row: { "data": { "input": "domain.com" } }. Add 0.5s delay between batches. Pass "run": true in the rows payload to trigger agent columns on upload.

Re-run After Enrichment

After the list-enrichment skill adds data points to this list, consider re-running list building using enrichment insights as Discovery criteria. For example:

If enrichment reveals that “companies using legacy ERP” are the best fit, create a Discovery task with that as a criterion
If enrichment shows a geographic cluster, run a Search with tighter geo filters

This creates a feedback loop: list → enrich → learn → refine list

Result Size Guidance

Campaign stage	Target list size	Method
Exploration	50-100	Search (2-3 queries)
First campaign	200-500	Search (5 queries) + Discovery
Scaling	500-2000	Discovery (high desired_num_results) + multiple Search

Workflow

Verify API reference

Read local references for Discovery API and search filters
Fetch live docs: https://www.extruct.ai/docs
Compare endpoints, params, and response fields
If discrepancies found, update local reference files and flag changes to user

Read context and decide method

Read context file for ICP, seed companies, and DNC list
Follow the decision tree to pick the right method

Draft queries

Draft 3-5 queries for Search, or 1-2 for Discovery

Run queries

Execute queries and collect results

Deduplicate and filter

Deduplicate across all results by domain
Remove DNC domains

Upload to table

Upload to Extruct company table for auto-enrichment
Add agent columns if user needs custom research

Deliver results

Ask user for preferred output: Extruct table link, local CSV, or both

Get Started

Core Concepts

Skills Reference

Guides

API Integration

Trigger Phrases

Official API Reference

Decision Tree

Before You Start

Environment

Method 1: Lookalike Search

Key Parameters

Response Fields

When to Use Lookalike

Tips

Method 2: Semantic Search - Fast, Broad

Key Parameters

Response Fields

Query Strategy

Method 3: Discovery API - Deep, Qualified

Key Parameters

Polling

Response Fields

Query Strategy

Upload to Table

Re-run After Enrichment

Result Size Guidance

Workflow

Build docs developers (and LLMs) love

Get Started

Core Concepts

Skills Reference

Guides

API Integration

​Trigger Phrases

​Official API Reference

​Decision Tree

​Before You Start

​Environment

​Method 1: Lookalike Search

​Key Parameters

​Response Fields

​When to Use Lookalike

​Tips

​Method 2: Semantic Search - Fast, Broad

​Key Parameters

​Response Fields

​Query Strategy

​Method 3: Discovery API - Deep, Qualified

​Key Parameters

​Polling

​Response Fields

​Query Strategy

​Upload to Table

​Re-run After Enrichment

​Result Size Guidance

​Workflow

Build docs developers (and LLMs) love

Trigger Phrases

Official API Reference

Decision Tree

Before You Start

Environment

Method 1: Lookalike Search

Key Parameters

Response Fields

When to Use Lookalike

Tips

Method 2: Semantic Search - Fast, Broad

Key Parameters

Response Fields

Query Strategy

Method 3: Discovery API - Deep, Qualified

Key Parameters

Polling

Response Fields

Query Strategy

Upload to Table

Re-run After Enrichment

Result Size Guidance

Workflow