Enrichments

Built on Task API: FindAll enrichments use Task API processors, JSON output schemas, and pricing. FindAll supplies the candidate input and handles orchestration automatically, running a task on each matched candidate.

Overview

FindAll enrichments allow you to extract additional non-boolean information about candidates that should not be used as filters for matches. For example, if you’re finding companies, you might want to extract the CEO name as pure enrichment data—something you want to know about each match, but not something that should affect whether a candidate matches your criteria.

Match Conditions vs. Enrichments

Understanding the distinction between match conditions and enrichments is fundamental to using FindAll effectively.

	Match Conditions	Enrichments
Purpose	Required criteria that determine whether a candidate is a match	Additional data fields extracted only for matched candidates
When Executed	During FindAll generation and evaluation process	Only on matched candidates using the Task API
Output format	Boolean match decision + extracted value	Structured JSON values defined by `output_schema`
Type of Criteria	Must be boolean/filterable (yes/no questions)	Can be any type of data extraction
Affects Matching?	✅ Yes - determines which candidates reach `matched` status	❌ No - does not affect which candidates match
When to Add	Must be defined when creating the run	Add after the run is created through `/enrich`; the endpoint can be called multiple times
Example Questions	• “Is the company founded after 2020?” • “Has the company raised Series A funding?” • “Is the company in the healthcare industry?”	• “What is the CEO’s name?” • “What is the company’s revenue?” • “What products does the company offer?”

Why This Separation Matters

This two-stage approach is efficient and cost-effective:

Filter first: Match conditions quickly narrow down candidates to relevant matches
Enrich selectively: Extract detailed data only from the matches that matter

This means you don’t pay to enrich hundreds of candidates that won’t match your criteria.

Adding Enrichments

Enrichments can be added anytime after a FindAll run is created, even for completed runs. Once added:

Enrichments will run on all matches (both ones that exist when the request is made and all future matches)
If enrichments are present, extend will also perform the same set of enrichments on all extended matches

Adding an enrichment to a terminal run requeues the run while FindAll schedules and processes the enrichment.

Creating Enrichments

Task API Concepts Apply Here: Enrichments use the same task spec structure as Task API runs. You’ll define:

Processors: Choose any supported Task API processor
Output Schema: Define structured JSON output (same format as Task API)
Pricing: Charged according to Task API processor pricing

You don’t define input_schema. FindAll supplies entity_name, entity_url, and entity_description for each matched candidate; entity_name is always present.

Quick Example

curl -X POST "https://api.parallel.ai/v1beta/findall/runs/findall_40e0ab8c10754be0b7a16477abb38a2f/enrich" \
  -H "x-api-key: $PARALLEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "processor": "core",
    "output_schema": {
      "type": "json",
      "json_schema": {
        "type": "object",
        "properties": {
          "ceo_name": {
            "type": "string",
            "description": "Name of the CEO"
          },
          "founding_year": {
            "type": "string",
            "description": "Year the company was founded"
          }
        },
        "required": ["ceo_name", "founding_year"],
        "additionalProperties": false
      }
    }
  }'

from parallel import Parallel
from pydantic import BaseModel, Field

client = Parallel(api_key="YOUR_API_KEY")

class CompanyEnrichment(BaseModel):
    ceo_name: str = Field(
        description="Name of the CEO"
    )
    founding_year: str = Field(
        description="Year the company was founded"
    )

client.beta.findall.enrich(
    findall_id="findall_40e0ab8c10754be0b7a16477abb38a2f",
    processor="core",
    output_schema={
        "type": "json",
        "json_schema": CompanyEnrichment.model_json_schema()
    }
)

import Parallel from 'parallel-web';

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

await client.beta.findall.enrich(
  "findall_40e0ab8c10754be0b7a16477abb38a2f",
  {
    processor: "core",
    output_schema: {
      type: "json",
      json_schema: {
        type: "object",
        properties: {
          ceo_name: {
            type: "string",
            description: "Name of the CEO"
          },
          founding_year: {
            type: "string",
            description: "Year the company was founded"
          }
        },
        required: ["ceo_name", "founding_year"],
        additionalProperties: false
      }
    }
  }
);

Retrieving Enrichment Results

You can access enrichment results through multiple methods:

Streaming Events (/events): Enrichment results stream in real-time as they complete
Webhooks: Subscribe to findall.candidate.enriched events to receive enrichment results via HTTP callbacks
Result endpoint (/result): Enrichment data is included in candidate snapshots once it is available; the endpoint works while a run is active and after it stops

Enrichment data is added to the candidate’s output object with type: "enrichment". See Candidates for details on how enrichments appear in the candidate structure.

Task API Foundation

Enrichments are built on Task API, so these guides will help you understand how they work:

Task API Quickstart: Learn the Task API that powers enrichments
Specify a Task: Master task_spec structure and best practices
Choose a Task Processor: Understand Task API processor options
Execute Task Runs: Learn about pricing and execution patterns

FindAll Features

Preview: Test queries with 5–10 evaluated candidates before running full searches
Extend Runs: Increase match limits without paying new fixed costs
Streaming Events: Receive real-time updates via Server-Sent Events
Webhooks: Configure HTTP callbacks for run completion and matches
Run Lifecycle: Understand run statuses and how to cancel runs
API Reference: Complete endpoint documentation

Getting started

Web Tools

Web Agents

Developer Tools

Platform Integrations

Data Integrations

Additional Resources

Overview

Match Conditions vs. Enrichments

Why This Separation Matters

Adding Enrichments

Creating Enrichments

Quick Example

Retrieving Enrichment Results

Task API Foundation

FindAll Features

​Overview

​Match Conditions vs. Enrichments

​Why This Separation Matters

​Adding Enrichments

​Creating Enrichments

​Quick Example

​Retrieving Enrichment Results

​Related Topics

​Task API Foundation

​FindAll Features

Overview

Match Conditions vs. Enrichments

Why This Separation Matters

Adding Enrichments

Creating Enrichments

Quick Example

Retrieving Enrichment Results

Related Topics

Task API Foundation

FindAll Features