Skip to main content

​
What is Enrichment?

Enrichment is when you have existing structured data—like a list of companies, products, or contacts—and want to enhance it with additional information from the web. The Task API makes it easy to define what data you have and what additional fields you need, then automatically researches and populates those fields at scale. The Task API supports two primary use cases: Enrichment and Deep Research. The Enrichment use case involves inputting structured data (eg. as a spreadsheet, JSON input, or database), and outputting structured enrichments. A single API call corresponds to a single row of enrichment, allowing for 20+ columns created with one call. This guide focuses on Enrichment, if you’re looking to conduct open-ended research without structured input data, see our Deep Research Quickstart.

​
How Enrichment Works

With enrichment, you define two schemas:
  1. Input Schema: The data fields you already have (e.g., company name, website)
  2. Output Schema: The new fields you want to add (e.g., employee count, funding sources, founding date)
The Task API researches the web and populates your output fields with accurate, cited information.

​
1. Set up Prerequisites

Generate your API key on Platform. Then, set up with the TypeScript SDK, Python SDK or with cURL: 
echo "Install curl and jq via brew, apt, or your favorite package manager"
export PARALLEL_API_KEY="PARALLEL_API_KEY"

​
2. Execute your First Enrichment Task

Let’s enrich a simple company record. We’ll start with just a company name and enrich it with a founding date:
You can learn about our available Processors here →
echo "Creating the run:"
RUN_JSON=$(curl -s "https://api.parallel.ai/v1/tasks/runs" \
-H "x-api-key: ${PARALLEL_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
    "task_spec": {
        "output_schema": "The founding date of the company in the format MM-YYYY"
    },
    "input": "United Nations",
    "processor": "base"
}')
echo "$RUN_JSON" | jq .
RUN_ID=$(echo "$RUN_JSON" | jq -r '.run_id')

echo "Retrieving the run result, blocking until the result is available:"
curl -s "https://api.parallel.ai/v1/tasks/runs/${RUN_ID}/result" \
  -H "x-api-key: ${PARALLEL_API_KEY}" | jq .

​
Sample Response

Immediately after a Task Run is created, the Task Run object, including the status of the Task Run, is returned. On completion, the Task Run Result object is returned. Basis, including citations, reasoning, confidence, and excerpts - is returned with every Task Run Result. 
{
  "run_id": "trun_9907962f83aa4d9d98fd7f4bf745d654",
  "status": "queued",
  "is_active": true,
  "warnings": null,
  "processor": "base",
  "metadata": null,
  "created_at": "2025-04-23T20:21:48.037943Z",
  "modified_at": "2025-04-23T20:21:48.037943Z"
}

​
3. From Simple to Rich Enrichment

The Task API supports increasingly sophisticated enrichment patterns:
1

Single Input → Single Output Field

The simplest enrichment: take one piece of data (like a company name) and add one new field (like founding date). This straightforward approach is illustrated above.
2

Single Input → Multiple Output Fields

Enrich a single input field with multiple new data points. For example, pass in a company name and receive founding date, employee count, and funding sources.
echo "Creating the run:"
RUN_JSON=$(curl -s 'https://api.parallel.ai/v1/tasks/runs' \
-H "x-api-key: ${PARALLEL_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"input": "United Nations",
"processor": "core",
"task_spec": {
"output_schema": {
  "type": "json",
  "json_schema": {
    "type": "object",
    "properties": {
      "founding_date": {
        "type": "string",
        "description": "The official founding date of the company in the format MM-YYYY"
      },
      "employee_count": {
        "type": "string",
        "enum": [
          "1-10 employees",
          "11-50 employees",
          "51-200 employees",
          "201-500 employees",
          "501-1000 employees",
          "1001-5000 employees",
          "5001-10000 employees",
          "10001+ employees"
        ],
        "description": "The range of employees working at the company. Choose the most accurate range possible and make sure to validate across multiple sources."
      },
      "funding_sources": {
        "type": "string",
        "description": "A detailed description, containing 1-4 sentences, of the company's funding sources, including their estimated value."
      }
    },
    "required": ["founding_date", "employee_count", "funding_sources"],
    "additionalProperties": false
  }
}
}
}'
)
echo "$RUN_JSON" | jq .
RUN_ID=$(echo "$RUN_JSON" | jq -r '.run_id')

echo "Retrieving the run result, blocking until the result is available:"
curl -s "https://api.parallel.ai/v1/tasks/runs/${RUN_ID}/result" \
  -H "x-api-key: ${PARALLEL_API_KEY}" | jq .
3

Multiple Inputs → Multiple Outputs (Full Enrichment)

The full enrichment pattern: define both input and output schemas. Provide multiple data fields you already have (company name and website) and specify all the fields you want to enrich. This is the most common pattern for enriching CRM data, compliance checks, and other structured workflows.
echo "Creating the run:"
RUN_JSON=$(curl -s 'https://api.parallel.ai/v1/tasks/runs' \
-H "x-api-key: ${PARALLEL_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"input": {
"company_name": "United Nations",
"company_website": "www.un.org"
},
"processor": "core",
"task_spec": {
"output_schema": {
  "type": "json",
  "json_schema": {
    "type": "object",
    "properties": {
      "founding_date": {
        "type": "string",
        "description": "The official founding date of the company in the format MM-YYYY"
      },
      "employee_count": {
        "type": "string",
        "enum":[
          "1-10 employees",
          "11-50 employees",
          "51-200 employees",
          "201-500 employees",
          "501-1000 employees",
          "1001-5000 employees",
          "5001-10000 employees",
          "10001+ employees"
        ],
        "description": "The range of employees working at the company. Choose the most accurate range possible and make sure to validate across multiple sources."
      },
      "funding_sources": {
        "type": "string",
        "description": "A detailed description, containing 1-4 sentences, of the company's funding sources, including their estimated value."
      }
    },
    "required": ["founding_date", "employee_count", "funding_sources"],
    "additionalProperties": false
  }
},
"input_schema": {
  "type": "json",
  "json_schema": {
    "type": "object",
    "properties": {
      "company_name": {
        "type": "string",
        "description": "The name of the company to research"
      },
      "company_website": {
        "type": "string",
        "description": "The website of the company to research"
      }
    },
    "required": ["company_name", "company_website"]
  }
}
}
}'
)
echo "$RUN_JSON" | jq .
RUN_ID=$(echo "$RUN_JSON" | jq -r '.run_id')

echo "Retrieving the run result, blocking until the result is available:"
curl -s "https://api.parallel.ai/v1/tasks/runs/${RUN_ID}/result" \
  -H "x-api-key: ${PARALLEL_API_KEY}" | jq .
Writing Effective Task Specs: For best practices on defining input and output schemas that produce high-quality results, see our Task Spec Best Practices guide.

​
Sample Enrichment Result

{
  "run": {
    "run_id": "trun_0824bb53c79c407b89614ba22e9db51c",
    "status": "completed",
    "is_active": false,
    "warnings": [],
    "processor": "core",
    "metadata": null,
    "created_at": "2025-04-24T16:05:03.403102Z",
    "modified_at": "2025-04-24T16:05:33.099450Z"
  },
  "output": {
    "content": {
      "funding_sources": "The United Nations' funding comes from governments, multilateral partners, and other non-state entities. This funding is acquired through assessed and voluntary contributions from its member states.",
      "employee_count": "10001+ employees",
      "founding_date": "10-1945"
    },
    "basis": [
      {
        "field": "funding_sources",
        "citations": [
          {
            "title": "Funding sources",
            "url": "https://www.financingun.report/un-financing/un-funding/funding-entity",
            "excerpts": [
              "The UN system is funded by a diverse set of partners: governments, multilateral partners, and other non-state funding."
            ]
          },
          {
            "title": "US Funding for the UN",
            "url": "https://betterworldcampaign.org/us-funding-for-the-un",
            "excerpts": [
              "Funding from Member States for the UN system comes from two main sources: assessed and voluntary contributions."
            ]
          }
        ],
        "reasoning": "The United Nations' funding is derived from a diverse set of partners, including governments, multilateral organizations, and other non-state entities, as stated by financingun.report. According to betterworldcampaign.org, the funding from member states is acquired through both assessed and voluntary contributions.",
        "confidence": "high"
      },
      {
        "field": "employee_count",
        "citations": [
          {
            "title": "Funding sources",
            "url": "https://www.financingun.report/un-financing/un-funding/funding-entity",
            "excerpts": []
          }
        ],
        "reasoning": "The UN employs approximately 37,000 people, with a total personnel count of 133,126 in 2023.",
        "confidence": "low"
      },
      {
        "field": "founding_date",
        "citations": [
          {
            "title": "Funding sources",
            "url": "https://www.financingun.report/un-financing/un-funding/funding-entity",
            "excerpts": []
          },
          {
            "title": "History of the United Nations",
            "url": "https://www.un.org/en/about-us/history-of-the-un",
            "excerpts": [
              "The United Nations officially began, on 24 October 1945, when it came into existence after its Charter had been ratified by China, France, the Soviet Union, ..."
            ]
          },
          {
            "title": "The Formation of the United Nations, 1945",
            "url": "https://history.state.gov/milestones/1937-1945/un",
            "excerpts": [
              "The United Nations came into existence on October 24, 1945, after 29 nations had ratified the Charter. Table of Contents. 1937–1945: Diplomacy and the Road to ..."
            ]
          }
        ],
        "reasoning": "The United Nations officially began on October 24, 1945, as stated in multiple sources including the UN's official history and the US Department of State's historical milestones. This date is when the UN came into existence after its Charter was ratified by key member states.",
        "confidence": "high"
      }
    ],
    "type": "json"
  }
}

​
Next Steps

  • Task Groups: Enrich multiple records concurrently with parallel execution and batch tracking
  • Task Spec Best Practices: Optimize your input and output schemas for accuracy and speed
  • Choose a Processor: Select the right processor tier for your enrichment use case
  • Access Research Basis: Understand citations, confidence levels, and reasoning for every enriched field
  • Deep Research: Explore open-ended research without structured input data
  • Streaming Events: Receive real-time updates via Server-Sent Events for long-running enrichments
  • Webhooks: Configure HTTP callbacks for task completion notifications
  • API Reference: Complete endpoint documentation for the Task API

​
Rate Limits

See Rate Limits for default quotas and how to request higher limits.