B2B Contact Enrichment API - Accounts, People, Discovery

Fill in the records you have, or find the people you do not have yet. Enrich a contact or an account into a full firmographic and technographic profile, or hand over a list of accounts and get back the people inside them who match a persona. One flat row per person.

What this actor does

• Enriches accounts and contacts in one pass. A record carrying a name and a company comes back with the job title, standard seniority level, department, job functions, email, phone and public professional profile for the person, and the industry, sub-industry, headcount, revenue, ownership, SIC and NAICS codes, ticker, social profiles and full address for the company.
• Discovers contacts inside an account. Give it accounts rather than people and it returns the individuals inside them, ranked against personas configured on your account, with the seniority levels, departments, job functions and countries you asked for. One account can yield up to a hundred contacts.
• Filters at the provider, not just afterwards. The persona criteria, the seniority levels and the requirement for a verified email or a direct dial are sent with the discovery request, so they narrow what the provider returns and what it charges for. The remaining filters run after the answer and trim the dataset instead.
• Flags the people who have left. Every enriched person carries a verification status saying whether they are still where the record says, along with how that was established. On an eighteen-month-old list this is worth more than any other field, because a moved contact is a guaranteed bounce and a wasted touch. One switch drops them.
• Reports what it validated on the way in. The email and phone you supplied come back with their own validation verdicts, and the company address comes back normalised, so an enrichment pass doubles as a hygiene pass on the data you already had.
• Returns technographics as columns. Installed technologies, website technologies and custom technology categories arrive as flat lists rather than buried in a nested analytics object, which is the difference between a filterable table and a JSON blob.
• Runs at whichever pace fits. The single record mode answers in the request and starts writing rows immediately, at the provider's published thirty transactions per second. The bulk modes submit five hundred records at a time, take a polling location, and wait, which is the only sensible way to move tens of thousands of records.
• Follows the polling location the provider gives it. That location arrives as a path carrying the API version the job was accepted under, which is not always the version it was submitted to. The actor reads it rather than rebuilding it, and refuses anything that is not a plain relative path.
• Waits properly rather than guessing. A job still running answers with a non-final status and no body at all. That is never read as an empty result.
• Drops records that cannot match before spending on them. The provider's own minimum is a company name for an account, or a first and last name plus a company or an email for a person. Records missing that are dropped locally rather than sent, refused and charged for.
• Never charges for a miss. Only rows carrying a resolved person or account are billed.

Input

Field	What it does
mode	Enrich one at a time, enrich in bulk, or discover contacts.
records	The records to work on, one JSON object per line.
companies	Shorthand for account runs: one website or name per line.
personas	Up to five personas to rank discovered contacts by.
minimumPersonaScore	How well a contact must match before it is returned.
resultsPerAccount	Contacts returned per account, up to one hundred.
contactLevels	Seniority levels to find. Sent with the request.
contactDepartments	Departments to find. Sent with the request.
contactJobFunctions	Job functions to find. Sent with the request.
contactCountries	Countries to find contacts in.
contactStates	States or provinces to find contacts in.
contactRegions	Regions to find contacts in.
requireVerifiedEmail	Only return contacts with a verified address.
requireDirectPhone	Only return contacts with a direct dial.
requireCompanyPhone	Only return contacts with a company phone.
enrichmentStatuses	Keep only rows enriched to this degree.
keepJobLevels	Keep only rows at these seniority levels.
matchConfidence	Keep only rows matched with this confidence.
industries	Keep only rows in these industries.
minCompanySize	Keep only companies at or above this headcount.
minCompanyRevenue	Keep only companies at or above this revenue.
requireEmail	Drop rows with no email resolved.
requirePhone	Drop rows with no phone resolved.
requireLinkedin	Drop rows with no professional profile resolved.
requireStillEmployed	Drop people who have left the company on record.
batchSize	Records per request in the bulk modes, up to five hundred.
requestsPerMinute	Pace the run under your plan's rate limit.
skipNotFound	Leave unmatched records out of the dataset.
maxResults	Hard cap on rows, and therefore on spend and run time.
apiKey	Your own API token. Stored as a secret.

Example output

{
  "found": true,
  "mode": "discover",
  "query": "example.com",
  "externalId": "row-0",
  "enrichmentStatus": "Person & Company Enriched",
  "personFullName": "Jane Doe",
  "personTitle": "VP of Demand Generation",
  "personDepartment": "Marketing",
  "personLevel": "VP Level",
  "personEmail": "jane.doe@example.com",
  "personEmailValidation": "VALID",
  "personPhone": "+1 805 555 1234",
  "personPhoneValidation": "VALID",
  "personLinkedinUrl": "https://www.linkedin.com/in/example",
  "personVerificationStatus": "Verified",
  "personVerificationSource": "Social & Email",
  "personCountry": "United States",
  "personState": "California",
  "personJobFunctions": ["Demand Generation", "Marketing Operations"],
  "personScore": 82.5,
  "personScoreProfile": "Marketing Decision Maker",
  "companyName": "Example Corp",
  "companyId": "ls-000000",
  "companyWebsite": "example.com",
  "companyIndustry": "Software",
  "companySubIndustry": "Marketing Software",
  "companySizeRange": "201-500",
  "companySizeExact": 340,
  "companyRevenueRange": "$50-100 Million",
  "companyRevenueExact": 72000000,
  "companyCountry": "United States",
  "companyMatchLevel": "HIGH",
  "companyInstalledTechnologies": ["Salesforce", "Marketo"],
  "error": null,
  "raw": { }
}

Frequently asked questions

What is the difference between enrichment and discovery?

Enrichment takes a record you already have and fills in what is missing. Discovery runs in the opposite direction: you supply accounts and it returns the people inside them, so one input row can produce up to a hundred output rows. Enrichment is what you run over a CRM export; discovery is what you run when you know which companies you want to reach and not who at them.

How do personas work?

Personas are configured on your account with the provider, and you name them here. Discovery ranks every contact it finds inside an account against those personas and returns a score, and the minimum persona score decides how weak a match may be before it is not returned at all. Raising that score returns fewer, better contacts and spends fewer credits, which is usually the right trade when the alternative is paying for a hundred rows and keeping five.

Which filters save me money and which just tidy the output?

The discovery criteria are sent with the request: personas, minimum score, seniority levels, departments, job functions, locations, the contacts-per-account cap, and the requirements for a verified email or a direct dial. Those change what the provider returns and therefore what it charges for. Everything else runs after the answer arrives and trims the dataset and your Apify spend but not your provider credits. When cost matters, tighten the first group.

What does the verification status tell me?

Whether the person is still at the company the record says they are. It comes back as verified, not verified, or moved, along with the source that established it. On any list older than a year or so this is the highest-value field in the response, because the alternative to knowing is discovering it through bounces and unanswered calls. The drop-people-who-have-moved-on switch removes them in one step.

Why does the country filter behave differently from the others?

Because sending it empty is not the same as not sending it. This provider treats an explicitly blank country as a request for contacts with no country on file, which returns nearly nothing and looks like a broken filter. The actor therefore leaves the property off entirely unless a run actually named a country.

When should I use bulk instead of single?

Single sends one record per request and gets the answer back in the response, so rows start appearing straight away and a short run finishes in seconds. It is limited to the provider's thirty transactions per second. Bulk submits up to five hundred records at once and waits for a job to finish, which is far fewer requests and the only sensible approach past a few thousand records, at the cost of nothing appearing until each batch completes. Discovery is always submitted as a job.

What minimum input does a record need?

An account needs a company name or website. A person needs a first and last name together with one of a company name, a company website or an email address, and a bare email with no company will not match unless the address is on the provider's personal-email matching list. Records that fall short of that are dropped before the request rather than sent, refused and charged for. Supplying a company website rather than a company name raises the match confidence considerably, since names are ambiguous and domains are not.

Do I need my own API key?

Yes. This actor does not include data access. You use your own API token from Leadspace, which is the provider whose B2B enrichment API this actor calls, issued to you with a program id. Your own plan, credit allocation and terms apply. Paste the token into the apiKey field, where it is stored as an Apify secret. Note that these tokens are rotated on a schedule and expire, so a token that worked last year may simply have aged out rather than been revoked.

What happens when a record matches nothing?

It is written with found: false and an explanation, and never billed. Records the provider refused for want of required fields are written the same way, carrying the provider's own reason. Records in a submitted batch that the provider never mentions at all are also written as misses, so the dataset stays a faithful account of what was asked rather than only of what came back. Set skipNotFound to true to leave all of them out.

How much does a run cost?

Pricing is pay per result: you are charged for each person or account resolved into the dataset, and never for misses, for rows dropped by the filters, or for duplicates. Watch the cap in the discovery mode in particular, since one account expanded into a hundred contacts is a hundred rows and a hundred charges. Apify platform usage is included in the per-result price. Your own API provider's credit allocation is separate and billed by them.

Keyword map

B2B data enrichment API, contact enrichment API, account enrichment, lead enrichment API, firmographic data API, technographic data API, company data API, contact discovery API, buyer persona targeting, ideal customer profile, ICP scoring, job title enrichment, seniority level data, department data, verified business email, direct dial phone number, LinkedIn profile enrichment, job change detection, contact still employed, CRM data hygiene, lead routing data, account based marketing data, sales intelligence API, prospect list building, bulk enrichment API