> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tako.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Enrichment API

> Screen companies and people with filters, or match the ones you already know, and get each list back as a card whose rows you export through Contents. In beta.

> [!NOTE]
>
> The Enrichment API is in **beta**. Its request and response shapes can change.

## Capabilities

The **Enrichment API** builds lists of companies and people in one synchronous call. It reads Tako's structured company and people data: company registries and licensed company and people profiles. It has four endpoints:

| Endpoint | Use it to |
| - | - |
| [`POST /v1/companies/search`](https://docs.tako.com/api-reference/companies-search) | Build a list of companies from filters, such as Series B enterprise SaaS companies in the US |
| [`POST /v1/people/search`](https://docs.tako.com/api-reference/people-search) | Build a list of people from filters, such as heads of sales at a set of companies |
| [`POST /v1/companies/enrich`](https://docs.tako.com/api-reference/companies-enrich) | Look up companies you can name, by website, LinkedIn page or name |
| [`POST /v1/people/enrich`](https://docs.tako.com/api-reference/people-enrich) | Look up people you know, by email, phone, LinkedIn profile or name |

> [card] Filters, not prompts
>
> You send typed filters and get the companies or people that match them. The same request returns the same kind of list each time.

> [card] Lists as cards
>
> Each response carries its list as one card. The card previews the first 10 rows, and [Contents](https://docs.tako.com/api-reference/contents.md) exports every row.

> [card] Contacts you pay for only when you want them
>
> Contact details and some company fields are [premium columns](https://docs.tako.com/documentation/integrating-tako/contents/for-coding-agent.md#premium-columns). Review the list first, then reveal them with a premium export.

To describe a list in words and let an agent work out the steps, use the [Company Agent](https://docs.tako.com/documentation/integrating-tako/agent/company.md). It takes about a minute and can read the web. Use the Enrichment API when you know the filters or the names, and want an answer in one call.

## Example: find the heads of sales at Series B SaaS companies

[Try in Playground](https://tako.com/console/playground/enrich/company-search)

**1. Search for the companies.**

```bash theme={null}
curl -X POST https://tako.com/api/v1/companies/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "industry": "enterprise_saas",
    "country": "US",
    "funding_stages": ["series_b"]
  }'
```

The response counts the matches, reads the filters back, and carries the list as a card:

```json theme={null}
{
  "total": 480,
  "total_is_lower_bound": false,
  "applied": ["status=active", "industry=enterprise_saas", "country=US", "latest_funding_stage=series_b"],
  "notes": [],
  "card": {
    "title": "Series B enterprise SaaS companies in US (480)",
    "description": "480 companies match ...\n\n| Name | Estimated revenue | Headcount | ... |",
    "webpage_url": "https://tako.com/card/CARD_ID/"
  }
}
```

The `card` is shortened here. Its `description` holds a table of the first 10 rows, and says how many more rows and fields the full data has.

**2. Get the rows.** Pass the card's `webpage_url` to Contents:

```bash theme={null}
curl -X POST https://tako.com/api/v1/contents \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tako.com/card/CARD_ID/", "content_format": "json_records", "max_rows": 100 }'
```

**3. Search for the people.** Send the companies' websites, from the `website` column, as `company_domains`:

```bash theme={null}
curl -X POST https://tako.com/api/v1/people/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": ["head of sales"],
    "company_domains": ["example.com", "example.org"]
  }'
```

**4. Reveal the contacts you want.** Export the people card through Contents with `"premium": true`. See [Get the rows and reveal premium fields](#get-the-rows-and-reveal-premium-fields).

## Get the rows and reveal premium fields

A response doesn't inline its rows unless you ask. You have two ways to get them:

* **Contents.** Pass the card's `webpage_url` to [`POST /v1/contents`](https://docs.tako.com/api-reference/contents). Page a long list with `offset` and `max_rows`. This is the only way to reveal premium fields.
* **`include_contents`.** Set `include_contents: true` on the search or enrich request to inline rows under `card.content`. `max_rows` caps them, and `content_format` picks `json_compact` (the default), `json_records`, `csv` or `card_json`. Inlined rows never carry premium values.

Premium cells are withheld by default: `null` in the JSON row formats and `[premium: withheld]` in CSV. To reveal them, send the Contents request again with `"premium": true`. `card_json` carries no premium values, and Contents refuses `premium: true` with it.

## What a list holds

The API reference publishes each list's fields as enums: `CompanyListField` and `PersonListField` hold every field in column order, and the `PreviewField`, `CardOnlyField` and `PremiumField` enums beside them hold the subsets.

**Company list**

| | Fields |
| - | - |
| In the card's preview | `name`, `status`, `estimated_revenue`\*, `headcount`, `industry`, `funding_stage`, `total_raised`, `last_funding_date`, `investors`, `location`, `website`, `tako_url` |
| Also in the exported rows | `company_type`, `linkedin_followers`\*, `linkedin_url`, `ticker`, `established`, `parent`\*, `subsidiaries`\*, `description`, `headcount_range`, `tags`, `metro`, `naics_codes`, `postcode`, `funding_round_count`, `funding_rounds`, `sic_codes`, `also_known_as`, `other_domains`, `street_address`, `twitter_url`, `facebook_url`, `sources` |
| On the card only | `last_funding_date`, `investors` |

**People list**

| | Fields |
| - | - |
| In the card's preview | `name`, `title`, `department`, `employer`, `schools`, `in_role_since`, `location`, `linkedin_url`, `work_email`\*, `phone`\*, `personal_email`\*, `tako_url` |
| Also in the exported rows | `seniority`, `description`, `education`, `experience`, `registry_seats`, `sub_role`, `business_area`, `occupation`, `job_summary`, `skills`, `industry`, `metro`, `job_verified_on`, `twitter_url`, `github_url`, `all_emails`\*, `all_personal_emails`\*, `employer_industry`, `employer_tako_industries`, `employer_tags`, `employer_size`, `employer_funding_stage`, `employer_founded`, `employer_location`, `employer_listing`, `sources` |
| On the card only | `schools`, `registry_companies` |

\* Premium. The preview leaves out a column that's empty on every row it shows. A card-only field appears on the card and isn't in the exported rows.

## Pricing

| What | List price |
| - | - |
| A search or enrich request | `$2.00` per 1,000 requests |
| Rows, inlined or exported | `$1.50` per 1,000 rows, plus `$0.001` per export |
| Premium people fields (`person_contact`) | `$45.00` per 1,000 people revealed |
| Premium company fields (`company_record`) | `$22.50` per 1,000 companies revealed |

* A request is billed once, whatever it returns. An enrich request with 25 items costs the same as one with a single item.
* A request that Tako refuses or that fails isn't billed. An enrich request in which every lookup failed returns `503` and isn't billed.
* Rows are billed only when you fetch them: through Contents, or inlined with `include_contents`. Without `include_contents`, the card's `content.cost` is a quote for fetching the rows, not a charge.
* Premium fields are billed only on a Contents export with `premium: true`.

[Contents pricing](https://docs.tako.com/documentation/integrating-tako/contents/pricing.md#premium-columns) defines a premium record and shows how to price an export before you run it. Negotiated terms on your account can change these rates, and the card's `export_pricing` gives your exact ones.

## Access

Send your [Tako API key](https://tako.com/console/api-keys) in the `X-API-Key` header. A `403` means the Enrichment API isn't available to your account. Tako doesn't bill a `403`, so don't retry it; contact [support@tako.com](mailto:support@tako.com).

> [!NOTE]
>
> The Python and TypeScript SDKs don't have Enrichment API methods yet. Call the endpoints over HTTP until they do.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.