Skip to main content

​
Overview

A candidate is an entity that Find All 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
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

Every candidate in Find All results, SSE events, and webhook payloads follows this structure:
PropertyTypeDescription
candidate_idstringUnique identifier for the candidate
namestringName of the entity
urlstringPrimary URL for the entity
descriptionstringBrief description of the entity
match_statusenumOne of generated, matched, and unmatched
outputobjectKey-value pairs showing evaluation results for each match condition and enrichment (see section below for more details)
basisarray[FieldBasis]Citations, reasoning, and confidence scores for each field. 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 // only match_condition contains boolean field is_match
  },
  "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 on discovering new matches. By excluding these known entities, you won’t be charged for generating or evaluating them again, making your searches more cost-effective.
Find All 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 to prevent specific entities from being generated or evaluated. Excluded entities won’t incur evaluation costs or appear in results/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 "parallel-beta: findall-2025-09-15" \
  -H "Content-Type: application/json" \
  -d '{
    "objective": "Find all portfolio companies of Khosla Ventures",
    "match_conditions": [...],
    "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 all candidates (matched and unmatched) after run completion
  • Streaming Events: Stream candidates in real-time as they’re generated and evaluated
  • Webhooks: Receive HTTP callbacks for candidate events