Skip to main content
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 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 to learn more.
  • Use Get credits to check the credits left in the workspace.
  • A request is rejected with a 402 error 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. The response is a 202 response with the enrichment, in the pending status (or already completed when every ID is skipped).
  2. Poll Get an enrichment of people with the ID of the enrichment until it is over, or subscribe a webhook 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 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.
New statuses may be added in the future: handle unknown values gracefully.
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 or 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 to read it.