Enrich people
curl --request POST \
--url https://api.folk.app/v1/person-enrichments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"fields": [
"emails",
"phones"
],
"ids": [
"per_05834d3b-2c1a-4e5f-8a9b-0c1d2e3f4a5b",
"per_9a1c7e2f-3b4d-4c5e-9f6a-7b8c9d0e1f2a",
"per_77be1a2b-4c5d-4e6f-8a7b-9c0d1e2f3a4b"
]
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
fields: ['emails', 'phones'],
ids: [
'per_05834d3b-2c1a-4e5f-8a9b-0c1d2e3f4a5b',
'per_9a1c7e2f-3b4d-4c5e-9f6a-7b8c9d0e1f2a',
'per_77be1a2b-4c5d-4e6f-8a7b-9c0d1e2f3a4b'
]
})
};
fetch('https://api.folk.app/v1/person-enrichments', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.folk.app/v1/person-enrichments"
payload = {
"fields": ["emails", "phones"],
"ids": ["per_05834d3b-2c1a-4e5f-8a9b-0c1d2e3f4a5b", "per_9a1c7e2f-3b4d-4c5e-9f6a-7b8c9d0e1f2a", "per_77be1a2b-4c5d-4e6f-8a7b-9c0d1e2f3a4b"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)require 'uri'
require 'net/http'
url = URI("https://api.folk.app/v1/person-enrichments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"fields\": [\n \"emails\",\n \"phones\"\n ],\n \"ids\": [\n \"per_05834d3b-2c1a-4e5f-8a9b-0c1d2e3f4a5b\",\n \"per_9a1c7e2f-3b4d-4c5e-9f6a-7b8c9d0e1f2a\",\n \"per_77be1a2b-4c5d-4e6f-8a7b-9c0d1e2f3a4b\"\n ]\n}"
response = http.request(request)
puts response.read_bodypackage main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.folk.app/v1/person-enrichments"
payload := strings.NewReader("{\n \"fields\": [\n \"emails\",\n \"phones\"\n ],\n \"ids\": [\n \"per_05834d3b-2c1a-4e5f-8a9b-0c1d2e3f4a5b\",\n \"per_9a1c7e2f-3b4d-4c5e-9f6a-7b8c9d0e1f2a\",\n \"per_77be1a2b-4c5d-4e6f-8a7b-9c0d1e2f3a4b\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.folk.app/v1/person-enrichments",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'fields' => [
'emails',
'phones'
],
'ids' => [
'per_05834d3b-2c1a-4e5f-8a9b-0c1d2e3f4a5b',
'per_9a1c7e2f-3b4d-4c5e-9f6a-7b8c9d0e1f2a',
'per_77be1a2b-4c5d-4e6f-8a7b-9c0d1e2f3a4b'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}{
"data": {
"id": "enr_3f2a6c1e-8b1d-4f0a-9c2e-5d7b8a9e0f11",
"status": "pending",
"fields": [
"emails",
"phones"
],
"createdAt": "2026-09-23T13:02:36.209Z",
"finishedAt": null,
"errorReason": null,
"summary": null,
"items": null
}
}{
"error": {
"code": "INVALID_REQUEST",
"message": "The request was invalid.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#bad-request",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "No valid API key provided.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#unauthorized",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "Not enough enrichment credits: 12 needed, 5 left.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#payment-required",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "FORBIDDEN",
"message": "The API key doesn’t have permissions to perform the request.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#forbidden",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "The requested resource was not found.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#not-found",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
"message": "A request with the same Idempotency-Key is still being processed. Retry once it has completed.",
"documentationUrl": "https://developer.folk.app/api-reference/idempotency#errors",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "UNPROCESSABLE_ENTITY",
"message": "Invalid query parameters",
"documentationUrl": "https://developer.folk.app/api-reference/errors#unprocessable-entity",
"details": {
"issues": [
{
"code": "too_small",
"minimum": 1,
"type": "number",
"inclusive": true,
"exact": false,
"message": "Number must be greater than or equal to 1",
"path": [
"limit"
]
}
]
},
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "TOO_MANY_REQUESTS",
"message": "You have exceeded your rate limit.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#rate-limiting",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z",
"details": {
"policy": "burst",
"limit": 20,
"remaining": 0,
"windowSeconds": 2,
"retryAfter": "2025-10-01T12:00:02.000Z",
"policies": [
{
"policy": "default",
"limit": 600,
"remaining": 412,
"windowSeconds": 60,
"retryAfter": "2025-10-01T12:01:00.000Z"
},
{
"policy": "burst",
"limit": 20,
"remaining": 0,
"windowSeconds": 2,
"retryAfter": "2025-10-01T12:00:02.000Z"
}
]
}
}
}{
"error": {
"code": "INTERNAL_SERVER_ERROR",
"message": "An internal server error occurred.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#internal-server-error",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "SERVICE_UNAVAILABLE",
"message": "The service is currently unavailable.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#service-unavailable",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}Person enrichments
Enrich people
Request an asynchronous enrichment of emails and/or phones for up to 500 people.
POST
/
v1
/
person-enrichments
Enrich people
curl --request POST \
--url https://api.folk.app/v1/person-enrichments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"fields": [
"emails",
"phones"
],
"ids": [
"per_05834d3b-2c1a-4e5f-8a9b-0c1d2e3f4a5b",
"per_9a1c7e2f-3b4d-4c5e-9f6a-7b8c9d0e1f2a",
"per_77be1a2b-4c5d-4e6f-8a7b-9c0d1e2f3a4b"
]
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
fields: ['emails', 'phones'],
ids: [
'per_05834d3b-2c1a-4e5f-8a9b-0c1d2e3f4a5b',
'per_9a1c7e2f-3b4d-4c5e-9f6a-7b8c9d0e1f2a',
'per_77be1a2b-4c5d-4e6f-8a7b-9c0d1e2f3a4b'
]
})
};
fetch('https://api.folk.app/v1/person-enrichments', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.folk.app/v1/person-enrichments"
payload = {
"fields": ["emails", "phones"],
"ids": ["per_05834d3b-2c1a-4e5f-8a9b-0c1d2e3f4a5b", "per_9a1c7e2f-3b4d-4c5e-9f6a-7b8c9d0e1f2a", "per_77be1a2b-4c5d-4e6f-8a7b-9c0d1e2f3a4b"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)require 'uri'
require 'net/http'
url = URI("https://api.folk.app/v1/person-enrichments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"fields\": [\n \"emails\",\n \"phones\"\n ],\n \"ids\": [\n \"per_05834d3b-2c1a-4e5f-8a9b-0c1d2e3f4a5b\",\n \"per_9a1c7e2f-3b4d-4c5e-9f6a-7b8c9d0e1f2a\",\n \"per_77be1a2b-4c5d-4e6f-8a7b-9c0d1e2f3a4b\"\n ]\n}"
response = http.request(request)
puts response.read_bodypackage main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.folk.app/v1/person-enrichments"
payload := strings.NewReader("{\n \"fields\": [\n \"emails\",\n \"phones\"\n ],\n \"ids\": [\n \"per_05834d3b-2c1a-4e5f-8a9b-0c1d2e3f4a5b\",\n \"per_9a1c7e2f-3b4d-4c5e-9f6a-7b8c9d0e1f2a\",\n \"per_77be1a2b-4c5d-4e6f-8a7b-9c0d1e2f3a4b\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.folk.app/v1/person-enrichments",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'fields' => [
'emails',
'phones'
],
'ids' => [
'per_05834d3b-2c1a-4e5f-8a9b-0c1d2e3f4a5b',
'per_9a1c7e2f-3b4d-4c5e-9f6a-7b8c9d0e1f2a',
'per_77be1a2b-4c5d-4e6f-8a7b-9c0d1e2f3a4b'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}{
"data": {
"id": "enr_3f2a6c1e-8b1d-4f0a-9c2e-5d7b8a9e0f11",
"status": "pending",
"fields": [
"emails",
"phones"
],
"createdAt": "2026-09-23T13:02:36.209Z",
"finishedAt": null,
"errorReason": null,
"summary": null,
"items": null
}
}{
"error": {
"code": "INVALID_REQUEST",
"message": "The request was invalid.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#bad-request",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "No valid API key provided.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#unauthorized",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "Not enough enrichment credits: 12 needed, 5 left.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#payment-required",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "FORBIDDEN",
"message": "The API key doesn’t have permissions to perform the request.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#forbidden",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "The requested resource was not found.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#not-found",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
"message": "A request with the same Idempotency-Key is still being processed. Retry once it has completed.",
"documentationUrl": "https://developer.folk.app/api-reference/idempotency#errors",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "UNPROCESSABLE_ENTITY",
"message": "Invalid query parameters",
"documentationUrl": "https://developer.folk.app/api-reference/errors#unprocessable-entity",
"details": {
"issues": [
{
"code": "too_small",
"minimum": 1,
"type": "number",
"inclusive": true,
"exact": false,
"message": "Number must be greater than or equal to 1",
"path": [
"limit"
]
}
]
},
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "TOO_MANY_REQUESTS",
"message": "You have exceeded your rate limit.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#rate-limiting",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z",
"details": {
"policy": "burst",
"limit": 20,
"remaining": 0,
"windowSeconds": 2,
"retryAfter": "2025-10-01T12:00:02.000Z",
"policies": [
{
"policy": "default",
"limit": 600,
"remaining": 412,
"windowSeconds": 60,
"retryAfter": "2025-10-01T12:01:00.000Z"
},
{
"policy": "burst",
"limit": 20,
"remaining": 0,
"windowSeconds": 2,
"retryAfter": "2025-10-01T12:00:02.000Z"
}
]
}
}
}{
"error": {
"code": "INTERNAL_SERVER_ERROR",
"message": "An internal server error occurred.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#internal-server-error",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "SERVICE_UNAVAILABLE",
"message": "The service is currently unavailable.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#service-unavailable",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}Request an enrichment of emails and/or phones for up to 500 people. folk searches the requested fields with external data providers, and saves the data found on each person. To learn more, read the Person enrichments guide.
Asynchronous processing
The enrichment runs asynchronously: the request returns a202 response with the enrichment in the pending status, before any person is enriched. If no ID matches a person you can enrich, the enrichment is already completed in the response, with every item skipped.
To know when the enrichment is over, either:
- Poll the Get an enrichment of people endpoint with the returned
iduntil the status of the enrichment iscompletedorfailed. - Subscribe a webhook to the
person_enrichment.finishedevent, then get the enrichment from theurlof the event.
items, and the counts per result in summary.
You can also find the enrichment later with List enrichments of people.
Credits
Enrichments consume the enrichment credits of the workspace. Read how credits are consumed to learn more.- Check the credits left in the workspace with Get credits.
- The request is rejected with a
402error if the workspace doesn’t have enough credits for the maximum possible cost of the enrichment. Nothing is performed or charged: send a smaller request, or add credits to the workspace.
People to enrich
Enriching a person needs the contributor role or above in at least one of its groups.- Duplicate IDs are enriched once.
- IDs of people already merged into another one are resolved to the resulting person.
- IDs that don’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) don’t reject the request: they are reported with the
skippedstatus in the result of the enrichment. - People deleted or merged after the request, including while being enriched, no longer appear in the result of the enrichment, nor in its
summary.
The more a person has data, the better the results. Names, a company, a
company website and a LinkedIn URL help the providers find the requested
fields. For people that aren’t fully enriched,
missingInputs lists the data
that was missing: read Improving the
results to learn more.Authorizations
API key for authentication
Headers
A unique key, such as a UUID, that makes retrying this request safe: a retry with the same key and body returns the original response without running the operation again. Keys are kept for 24 hours after the request completes.
Maximum string length:
255Example:
"8e03978e-40d5-43e8-bc93-6894a57f9324"
Body
application/json
The fields to enrich on each person. Each field can only be requested once.
Required array length:
1 - 2 elementsA person field to enrich. One of: emails, phones.
Available options:
emails, phones Example:
["emails", "phones"]
The IDs of the people to enrich, up to 500. Duplicate IDs are enriched once. IDs that don't match a person you can enrich don't reject the request: they are reported as items with the skipped status.
Required array length:
1 - 500 elementsRequired string length:
40Example:
[
"per_05834d3b-2c1a-4e5f-8a9b-0c1d2e3f4a5b",
"per_9a1c7e2f-3b4d-4c5e-9f6a-7b8c9d0e1f2a",
"per_77be1a2b-4c5d-4e6f-8a7b-9c0d1e2f3a4b"
]
Response
The enrichment that has been requested.
An enrichment of emails and/or phones for a list of people, run asynchronously.
Show child attributes
Show child attributes
Example:
{
"id": "enr_3f2a6c1e-8b1d-4f0a-9c2e-5d7b8a9e0f11",
"status": "pending",
"fields": ["emails", "phones"],
"createdAt": "2026-09-23T13:02:36.209Z",
"finishedAt": null,
"errorReason": null,
"summary": null,
"items": null
}
Example:
["This field is deprecated"]