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

# Person enrichments

An enrichment finds the missing emails and/or phones of people, using external data providers. It is the API equivalent of the [1-click enrichment](https://help.folk.app/en/articles/6804416-1-click-enrichment-find-emails-phone-numbers) of the app.

Enrichments started from the folk app and requested through the API are the same: everything below applies to both.

## Credits

Enrichments consume the enrichment credits of the workspace. Read [how credits are consumed](https://help.folk.app/en/articles/6804416-1-click-enrichment-find-emails-phone-numbers) to learn more.

* Use [Get credits](/api-reference/credits/get-credits) to check the credits left in the workspace.
* A request is rejected with a [`402` error](/api-reference/errors#payment-required) if the workspace doesn't have enough credits for the maximum possible cost of the enrichment. Nothing is performed or charged.

## Lifecycle

Enrichments run asynchronously:

1. Request an enrichment of up to 500 people with [Enrich people](/api-reference/person-enrichments/enrich-people). The response is a [`202` response](/api-reference/success-responses#accepted) with the enrichment, in the `pending` status (or already `completed` when every ID is skipped).
2. Poll [Get an enrichment of people](/api-reference/person-enrichments/get-an-enrichment-of-people) with the ID of the enrichment until it is over, or subscribe a [webhook](/webhooks/events-and-payloads#person-enrichment-events) to the `person_enrichment.finished` event.
3. Once over, the enrichment has one of the following statuses:
   * `completed`: the result for each person is in `items`, and the counts per result in `summary`.
   * `failed`: the enrichment couldn't run, see `errorReason`.

Use [List enrichments of people](/api-reference/person-enrichments/list-enrichments-of-people) to find an enrichment without its ID, for instance the ones still running. Each page returns up to 10 enrichments, as each one includes the result for every person.

## Result for each person

Each item of a completed enrichment has one of the following statuses:

* `enriched`: new data was found for every requested field.
* `partially_enriched`: new data was found for some requested fields, see `enrichedFields`.
* `not_enriched`: the person was searched, and no new data was found for the requested fields. A value the person already had doesn't count.
* `skipped`: the ID doesn't match a person you can enrich (unknown, deleted, not accessible to you, or you aren't a contributor in any of the person's groups), so the person wasn't searched.
* `error`: no enrichment provider could process this person, for instance because the providers were unavailable, so the person wasn't searched. Request a new enrichment for this person later.

<Info>
  New statuses may be added in the future: handle unknown values gracefully.
</Info>

All the enrichments of the workspace are visible to every member, but `items` and `summary` only include the people you can access. People deleted or merged after the request, including while being enriched, no longer appear in the result.

### Improving the results

The enrichment providers search with the data of the person: the more they know, the better the results. For people with the `not_enriched` or `partially_enriched` status, `missingInputs` lists the data the providers search with, that the person didn't have:

* `name`: a first or last name, set with `firstName` and `lastName`.
* `company`: a company linked to the person, set with `companies`.
* `companyWebsite`: a website on the primary company of the person, set with the `urls` of the company.
* `linkedinUrl`: a LinkedIn profile URL (`https://www.linkedin.com/in/...`), set with the `urls` of the person.

Adding this data with [Update a person](/api-reference/people/update-a-person) or [Update a company](/api-reference/companies/update-a-company) before requesting a new enrichment may improve the results, with no guarantee. For instance, a LinkedIn URL is often needed to find phone numbers.

### Saved data

The data that was found is saved on the person. Use the [people endpoints](/api-reference/people/get-a-person) to read it.


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