Candidates

Overview

A candidate is an entity that FindAll discovers during the generation phase of a run. Each candidate represents a potential match that is evaluated against your match conditions.

Candidate States

Candidates progress through these states during evaluation:

Generated: Discovered from web data, queued for evaluation
Matched: Successfully satisfied all match conditions
Unmatched: Failed to satisfy one or more match conditions
Discarded: Removed from further evaluation because the candidate was invalid, irrelevant, or duplicated

Post-Match Events: When using Streaming Events or Webhooks, you may receive enriched events for matched candidates. These are event types (not match_status values) that indicate when additional data has been extracted via enrichments after a candidate has already matched.

Candidate Object Structure

Candidates in FindAll results, SSE events, and webhook payloads use this model. Webhook payloads also include findall_id. Optional fields are omitted when they are not available.

Property	Type	Description
`candidate_id`	string	Unique identifier for the candidate
`name`	string	Name of the entity
`url`	string	Primary URL for the entity
`description`	string, optional	Brief description of the entity, when available
`match_status`	enum	One of `generated`, `matched`, `unmatched`, and `discarded`
`output`	object, optional	Key-value pairs showing evaluation results for each match condition and enrichment; omitted before evaluation (see section below for more details)
`basis`	array[FieldBasis], optional	Citations, reasoning, and confidence scores for evaluated fields. See FieldBasis for more details.

Understanding the `output` Field

The output field contains evaluation results where each key corresponds to a field name. Match conditions include an is_matched boolean, while enrichments do not:

{
  "founded_after_2020_check": {
    "value": "2021",
    "type": "match_condition",
    "is_matched": true
  },
  "ceo_name": {
    "value": "Ramin Hasani",
    "type": "enrichment"
  }
}

Understanding the `basis` Field

The basis field provides citations, reasoning, and confidence scores for each field in output.

For complete details on basis structure and usage, see Access Research Basis.

Excluding Candidates

Use case: Excluding candidates is useful when you already know certain entities match your criteria (such as results from previous runs or entities you’ve already identified), allowing you to focus the run on discovering new matches.

FindAll uses intelligence to deduplicate and disambiguate candidates you provide in the exclude list, which handles aliases and entities with slightly different names or URL variations. However, using the most official and disambiguated name and URL is recommended for best results.

Provide an exclude_list with up to 10,000 entries to prevent specific entities from being generated or evaluated. Excluded entities do not appear in results or events. Exclude list structure: Array of objects with name (string) and url (string) fields.

curl -X POST "https://api.parallel.ai/v1beta/findall/runs" \
  -H "x-api-key: $PARALLEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "objective": "FindAll portfolio companies of Khosla Ventures",
    "entity_type": "companies",
    "match_conditions": [
      {
        "name": "khosla_ventures_portfolio_check",
        "description": "Company must be a portfolio company of Khosla Ventures."
      }
    ],
    "generator": "core",
    "match_limit": 20,
    "exclude_list": [
      {"name": "Figure AI", "url": "https://www.figure.ai"},
      {"name": "Anthropic", "url": "https://www.anthropic.com"}
    ]
  }'

from parallel import Parallel

client = Parallel(api_key="YOUR_API_KEY")

findall_run = client.beta.findall.create(
    objective="FindAll portfolio companies of Khosla Ventures",
    entity_type="companies",
    match_conditions=[
        {
            "name": "khosla_ventures_portfolio_check",
            "description": "Company must be a portfolio company of Khosla Ventures."
        }
    ],
    generator="core",
    match_limit=20,
    exclude_list=[
        {"name": "Figure AI", "url": "https://www.figure.ai"},
        {"name": "Anthropic", "url": "https://www.anthropic.com"}
    ]
)

import Parallel from 'parallel-web';

const client = new Parallel({
  apiKey: process.env.PARALLEL_API_KEY
});

const run = await client.beta.findall.create({
  objective: "FindAll portfolio companies of Khosla Ventures",
  entity_type: "companies",
  match_conditions: [
    {
      name: "khosla_ventures_portfolio_check",
      description: "Company must be a portfolio company of Khosla Ventures."
    }
  ],
  generator: "core",
  match_limit: 20,
  exclude_list: [
    { name: "Figure AI", url: "https://www.figure.ai" },
    { name: "Anthropic", url: "https://www.anthropic.com" }
  ]
});

Retrieving Candidates

Candidates can be accessed through multiple methods:

/result endpoint: Retrieve the current candidate snapshot while a run is active or after it stops. Active snapshots can also include generated candidates.
Streaming Events: Stream candidates in real-time as they’re generated and evaluated
Webhooks: Receive HTTP callbacks for the candidate event types emitted by the webhook runtime

FindAll Quickstart: Get started with FindAll API
Generators and Pricing: Understand generator options and pricing
Run Lifecycle: Learn about run statuses and metrics
Enrichments: Extract additional data from matched candidates
Streaming Events: Monitor candidates in real-time
Webhooks: Set up notifications for candidate events
Access Research Basis: Deep dive into citation and reasoning structure

Getting started

Web Tools

Web Agents

Developer Tools

Platform Integrations

Data Integrations

Additional Resources

Overview

Candidate States

Candidate Object Structure

Understanding the `output` Field

Understanding the `basis` Field

Excluding Candidates

Retrieving Candidates

​Overview

​Candidate States

​Candidate Object Structure

​Understanding the output Field

​Understanding the basis Field

​Excluding Candidates

​Retrieving Candidates

​Related Topics

Overview

Candidate States

Candidate Object Structure

Understanding the `output` Field

Understanding the `basis` Field

Excluding Candidates

Retrieving Candidates

Related Topics