curl --request POST \
--url https://api.tryfuse.ai/api/v1/business/lists/{listId}/enrich \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '{}'import requests
url = "https://api.tryfuse.ai/api/v1/business/lists/{listId}/enrich"
payload = {}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({})
};
fetch('https://api.tryfuse.ai/api/v1/business/lists/{listId}/enrich', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"listIds": [
"68a1f20b9c41d20014b3e901"
],
"mode": "phone_and_email",
"totalContacts": 200,
"estimatedMinutes": 10
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}Enrich a list's contacts in place
Runs an enrichment over the list’s contacts in place. mode selects what runs: the waterfall modes (email, phone, phone_and_email) discover new values through the provider waterfall and take an optional row filters object or an explicit contactIds selection; validate_emails re-verifies the contacts’ existing emails; demographics resolves manually-added rows to canonical contacts. limit bounds the processed (and billed) rows — required unless contactIds is given, and capped at 5,000 for validate_emails/demographics. Billing is per processed contact: up to 50 credits per work email (100 when personal emails are prioritised in the workspace settings), 200 per phone, 10 per re-verified address, 2 per resolved demographics row; the balance must cover the reserved price up front (402 INSUFFICIENT_CREDITS) and contacts already carrying the requested data are never re-charged — with the waterfall modes a fully enriched list answers 409 ALL_CONTACTS_ALREADY_ENRICHED before anything bills, while validate_emails and demographics report a nothing-to-do run as 202 with totalContacts: 0. Async: totalContacts is the requested count and estimatedMinutes a rough duration; poll GET /business/lists/{listId}/rows (emails/phones fill in) or the list’s metrics.
Errors:
402INSUFFICIENT_CREDITS— The credit balance does not cover the reserved price for the requested rows.404LIST_NOT_FOUND— No list with that id is visible to the token owner.409ALL_CONTACTS_ALREADY_ENRICHED— Every contact in the list already carries the requested data; nothing to run. Waterfall modes (email, phone, phone_and_email) only — validate_emails and demographics answer 202 with totalContacts 0 instead.422CONTACT_LIST_REQUIRED— The list is a company list; enrichment runs on contacts.422CONTACT_NOT_IN_LIST— A contactIds entry is not a row of this list.422VALIDATION_FAILED— mode missing/unknown, limit missing without contactIds or outside 1-10000, filters/contactIds sent together or with validate_emails/demographics.429RATE_LIMITED— The lists rate bucket (120 requests/minute, 10,000/day per token owner) is exhausted.
Requires one of the following token scopes: lists.
curl --request POST \
--url https://api.tryfuse.ai/api/v1/business/lists/{listId}/enrich \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '{}'import requests
url = "https://api.tryfuse.ai/api/v1/business/lists/{listId}/enrich"
payload = {}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({})
};
fetch('https://api.tryfuse.ai/api/v1/business/lists/{listId}/enrich', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"listIds": [
"68a1f20b9c41d20014b3e901"
],
"mode": "phone_and_email",
"totalContacts": 200,
"estimatedMinutes": 10
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}Authorizations
Your API token (af_…) as the Basic-auth username, with an empty password.
Path Parameters
24-character hex id of the list (from GET /business/lists).
Body
What to run: email, phone or phone_and_email discover new values through the enrichment waterfall (billed per contact processed, at up to 50 credits per work email — 100 when personal emails are prioritised — and 200 per phone); validate_emails re-verifies the contacts' existing emails (10 credits per address); demographics resolves manually uploaded rows to canonical contacts (2 credits per resolved contact).
email, phone, phone_and_email, validate_emails, demographics Row-filter object narrowing which contacts the waterfall modes process, in the same language as the filters query of GET /business/lists/{listId}/rows; not allowed for validate_emails or demographics and mutually exclusive with contactIds. Text keys (name, title, dept, level, industryName, country, state, personalLocation, companyName, companyIndustry, companyHeadQuartersCountry, companyLocation, website, campaignEngagement, otherLists) take an array of accepted values, e.g. {"companyName":["pomelo"]} or {"country":["argentina"]}, or {"include":[...],"exclude":[...]} — otherLists takes list NAMES, not ids; numberOfEmployees takes headcount ranges the same way but as STRINGS ("51-200", "10001+" or a bare head count "500" — an unquoted JSON number answers 500) and revenue a plain number; keywords (a wildcard match on the job title only) and linkedinUrl take one string; enrichedEmail, enrichedPhone and emailValidity take {"include":[...]} of their statuses; icpMatch takes ["yes"] or ["no"]; customColumns maps a column id to {"dataType":"string","include":[...]}, {"dataType":"boolean","value":true} or {"dataType":"number","rangeMin":1,"rangeMax":10}. Company lists honour companyName, companyIndustry, companyHeadQuartersCountry, website, numberOfEmployees, campaignEngagement and customColumns. Every key is optional; an unknown key or a wrong value shape is rejected rather than ignored. Values inside one key are OR-joined and different keys are AND-ed. VALUES ARE NOT VALIDATED: level, industryName, country, state, website and companyHeadQuartersCountry are matched as whole values and campaignEngagement, icpMatch and enum cells as exact strings, so a value in the wrong vocabulary is accepted and silently matches nothing — each key's own description names its vocabulary and the endpoint that serves it. A rejected filter answers 422 VALIDATION_FAILED.
Show child attributes
Show child attributes
Explicit contacts to process (24-character hex ids, 1-500) for the waterfall modes. Each must be a row of this list (a row id from GET /business/lists/{listId}/rows); any other id answers 422 CONTACT_NOT_IN_LIST. Not allowed for validate_emails or demographics and mutually exclusive with filters.
1 - 500 elements24-character hex id of a contact (the row id from GET /business/lists/{listId}/rows).
Upper bound on contacts processed and billed (1-10000); required unless contactIds is given, and validate_emails/demographics cap it at 5000.
1 <= x <= 10000