Advanced Targeting

Take your company discovery to the next level with advanced targeting techniques including multi-entity ICPs, contact density controls, and iterative refinement.

Prerequisites

Before starting, ensure you have:

Completed the Quickstart guide
Understanding of ICPs and entity types
Your API key (see Authentication)

Multi-entity ICPs allow you to discover both companies and contacts in a single workflow. Define a parent entity (typically company) and child entities (typically person) with targeting criteria for each.

Entity Target Configuration

Each entity target in your ICP includes:

Field	Type	Description
`entity_type`	string	Entity type: `company` or `person`
`description`	string	Targeting criteria and enrichment fields
`root`	boolean	`true` for the parent entity
`desired_count`	integer	Contacts per parent (child entities only)

Creating a Multi-Entity ICP

curl -X POST "https://api.linkt.ai/v1/icp" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Healthcare SaaS VPs",
    "description": "VP+ decision makers at healthcare SaaS companies",
    "mode": "discovery",
    "entity_targets": [
      {
        "entity_type": "company",
        "root": true,
        "description": "## Criteria\n- Healthcare technology sector\n- 50-500 employees\n- Series A or B funding\n- US or Canada headquarters\n\n## Enrichment Fields\n- healthcare_focus: Specific healthcare verticals (mental health, dental, etc.)\n- tech_stack: Primary technologies and platforms"
      },
      {
        "entity_type": "person",
        "root": false,
        "desired_count": 3,
        "description": "## Criteria\n- VP or C-level title\n- Engineering, Product, or Sales department\n- Current role for 1+ years\n\n## Enrichment Fields\n- decision_scope: Evidence of budget authority"
      }
    ]
  }'

Response:

{
  "id": "507f1f77bcf86cd799439011",
  "name": "Healthcare SaaS VPs",
  "mode": "discovery",
  "entity_targets": [
    {
      "entity_type": "company",
      "root": true,
      "description": "## Criteria\n- Healthcare technology sector...",
      "desired_count": null
    },
    {
      "entity_type": "person",
      "root": false,
      "description": "## Criteria\n- VP or C-level title...",
      "desired_count": 3
    }
  ],
  "created_at": "2025-01-06T10:00:00Z"
}

Result Expectations

With this configuration:

Companies: Linkt discovers companies matching your criteria
Contacts: For each company, up to 3 people matching the person criteria are discovered
Enrichment: Both entity types receive their specified custom fields

Root Entity

The root: true entity is the primary search target. Child entities are discovered for each root entity found. Only one entity target can be root.

Desired Count Configuration

The desired_count field controls how many child entities to discover per parent. This is essential for contact density control.

Configuration Options

Value	Result
`1` (default)	1 contact per company
`3`	3 contacts per company
`5`	5 contacts per company
`10` (max)	10 contacts per company

Setting Desired Count

curl -X POST "https://api.linkt.ai/v1/icp" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enterprise Accounts + Contacts",
    "mode": "discovery",
    "entity_targets": [
      {
        "entity_type": "company",
        "root": true,
        "description": "## Criteria\n- Enterprise B2B SaaS\n- 500+ employees"
      },
      {
        "entity_type": "person",
        "desired_count": 5,
        "description": "## Criteria\n- Director+ level\n- IT or Engineering department"
      }
    ]
  }'

Practical Guidelines

Scenario	Recommended Count
Initial outreach	1-2
Multi-threaded sales	3-5
Account-based marketing	5-10
Research/intelligence	1

Credit Usage

Higher desired_count values consume more credits per company discovered. Balance contact density with your budget.

Filtering Strategies

Entity target descriptions support multiple criteria categories for precise targeting.

Criteria Categories

Category	Purpose	Examples
Location	Geographic targeting	"North America", "San Francisco Bay Area"
Size	Company/team sizing	"50-500 employees", "Mid-market"
Industry	Vertical/sector focus	"B2B SaaS", "Healthcare tech", "Fintech"
Funding	Investment stage	"Series A or B", "Profitable and growing"
Technology	Tech stack preferences	"Using Salesforce", "React stack"
Signals	Behavioral indicators	"Recently hired VP Sales", "Expanding markets"
Exclusion	Negative targeting	"NOT enterprise (>1000)", "Exclude agencies"

Combining Criteria

Structure your entity target description with clear sections:

## Criteria
- B2B SaaS companies (Industry)
- 50-200 employees (Size)
- Series A or B funding (Funding)
- US headquarters (Location)
- Using modern tech stack (Technology)
- NOT consulting or agencies (Exclusion)
 
## Enrichment Fields
- primary_product: Main product or service offered
- tech_stack: Key technologies and frameworks used

Example: Multi-Criteria ICP

curl -X POST "https://api.linkt.ai/v1/icp" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AI Startups - West Coast",
    "mode": "discovery",
    "entity_targets": [
      {
        "entity_type": "company",
        "root": true,
        "description": "## Criteria\n- AI/ML-focused technology company\n- Series A through Series C funding\n- 20-200 employees\n- Headquarters in California, Washington, or Oregon\n- NOT consulting firms or agencies\n- Founded after 2018\n\n## Enrichment Fields\n- ai_focus_area: Primary AI/ML application (NLP, computer vision, etc.)\n- notable_customers: Known enterprise customers\n- recent_news: Latest funding or product announcements"
      }
    ]
  }'

Use the user_feedback field in search tasks to refine results without modifying your ICP.

How It Works

Execute initial search with your ICP
Review results and identify gaps
Add feedback to the task's user_feedback field
Execute again with refined targeting

Adding Feedback

The user_feedback field is append-only, accumulating refinements over time:

curl -X PATCH "https://api.linkt.ai/v1/task/507f1f77bcf86cd799439013" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "task_config": {
      "type": "search",
      "desired_contact_count": 3,
      "user_feedback": "Focus more on enterprise software vendors. Exclude companies that are primarily agencies or consultancies."
    }
  }'

Feedback Best Practices

Do	Don't
Be specific about what to include/exclude	Give vague instructions
Reference concrete examples	Contradict original criteria
Add incremental refinements	Rewrite entire targeting

Example Feedback Patterns

Too broad results:

"Need companies with 100+ employees minimum.
Results included too many early-stage startups."

Wrong industry mix:

"Focus on enterprise software vendors only.
Exclude marketing agencies and consulting firms."

Geographic refinement:

"Prioritize San Francisco Bay Area and NYC.
Secondary priority for Austin and Seattle."

Performance Optimization

Optimize ICP Descriptions

Practice	Impact
Be specific	Fewer false positives
Use clear categories	Better matching
Include exclusions	Filters irrelevant results
Limit enrichment fields	Faster processing

Batch Size Recommendations

Dataset Size	Approach
< 50 companies	Single search task
50-200 companies	Split into 2-3 tasks
200+ companies	Multiple focused ICPs

Credit-Efficient Patterns

Start narrow, expand later — Begin with strict criteria, loosen if needed
Use exclusions — Filter out obvious non-matches upfront
Limit contact count — Start with 1-2 contacts, increase for promising accounts
Reuse ICPs — Create reusable ICPs for recurring searches

Complete Example

Here's a full workflow for multi-entity discovery with refinement:

import requests
import time
 
API_KEY = "your-api-key"
BASE_URL = "https://api.linkt.ai/v1"
HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}
 
def advanced_search(icp_config, feedback=None):
    """Execute advanced multi-entity search with optional feedback."""
 
    # Step 1: Create multi-entity ICP
    print("Creating ICP...")
    icp_response = requests.post(
        f"{BASE_URL}/icp",
        headers=HEADERS,
        json=icp_config
    )
    icp = icp_response.json()
    icp_id = icp["id"]
    print(f"  ICP created: {icp_id}")
 
    # Step 2: Create sheets for each entity type
    sheets = {}
    for target in icp_config["entity_targets"]:
        entity_type = target["entity_type"]
        print(f"Creating {entity_type} sheet...")
        sheet_response = requests.post(
            f"{BASE_URL}/sheet",
            headers=HEADERS,
            json={
                "name": f"{icp_config['name']} - {entity_type}",
                "icp_id": icp_id,
                "entity_type": entity_type
            }
        )
        sheets[entity_type] = sheet_response.json()["id"]
 
    # Step 3: Create search task
    print("Creating search task...")
 
    # Get desired_contact_count from person entity target
    desired_count = 1
    for target in icp_config["entity_targets"]:
        if target["entity_type"] == "person" and "desired_count" in target:
            desired_count = target["desired_count"]
 
    task_config = {
        "type": "search",
        "desired_contact_count": desired_count,
        "user_feedback": feedback or ""
    }
 
    task_response = requests.post(
        f"{BASE_URL}/task",
        headers=HEADERS,
        json={
            "name": f"Search: {icp_config['name']}",
            "flow_name": "search",
            "deployment_name": "main",
            "sheet_id": sheets["company"],
            "task_config": task_config
        }
    )
    task_id = task_response.json()["id"]
    print(f"  Task created: {task_id}")
 
    # Step 4: Execute
    print("Executing search...")
    run_response = requests.post(
        f"{BASE_URL}/task/{task_id}/execute",
        headers=HEADERS,
        json={"icp_id": icp_id}
    )
    run_id = run_response.json()["run_id"]
 
    # Step 5: Wait for completion
    print("Waiting for completion...")
    while True:
        run = requests.get(
            f"{BASE_URL}/run/{run_id}",
            headers={"x-api-key": API_KEY}
        ).json()
 
        if run["status"] == "COMPLETED":
            break
        elif run["status"] in ["FAILED", "CANCELED", "CRASHED"]:
            raise Exception(f"Search failed: {run.get('error')}")
 
        time.sleep(10)  # Poll every 10 seconds
 
    # Step 6: Get results
    results = {}
    for entity_type, sheet_id in sheets.items():
        entities = requests.get(
            f"{BASE_URL}/sheet/{sheet_id}/entities",
            headers={"x-api-key": API_KEY}
        ).json()
        results[entity_type] = entities
        print(f"  {entity_type}: {entities['total']} entities")
 
    return {
        "icp_id": icp_id,
        "task_id": task_id,
        "sheets": sheets,
        "results": results
    }
 
# Example: Multi-entity search
result = advanced_search({
    "name": "Healthcare SaaS Decision Makers",
    "description": "VPs at healthcare technology companies",
    "mode": "discovery",
    "entity_targets": [
        {
            "entity_type": "company",
            "root": True,
            "description": """## Criteria
- Healthcare technology sector
- B2B SaaS business model
- 50-500 employees
- Series A through Series C funding
- US headquarters
 
## Enrichment Fields
- healthcare_vertical: Specific healthcare focus area
- key_products: Main product offerings"""
        },
        {
            "entity_type": "person",
            "desired_count": 3,
            "description": """## Criteria
- VP, Director, or C-level title
- Engineering, Product, or Sales department
- Decision-making authority
 
## Enrichment Fields
- focus_area: Primary responsibility area"""
        }
    ]
})
 
print(f"\nFound {result['results']['company']['total']} companies")
print(f"Found {result['results']['person']['total']} contacts")

Next Steps

Contact Discovery — Person-focused search workflows
ICPs Reference — Complete ICP documentation
Custom Fields — Extending entity schemas