Field mapping
Search queries
With a coding agent
Check the fit first
Switch company enrichment in five minutes
This is the shortest path: one enrichment call by website, moved to the V2 API with the Python SDK.Get an API key
COMPANYENRICH_API_KEY. Check it with GET /v2/me, which is free:Install the SDK
Replace the call
Update the fields you read
Handle no match
404. The CompanyEnrich SDK raises NotFoundError. Neither API charges for it.What takes longer
Migrate with a coding agent
A coding agent can do the inventory, the rewrite, and the tests. Give it this prompt in your repository:Endpoint mapping
Company
People
Supporting APIs
Request and response differences
Authentication
Response shape
Match confidence
PDL scores every enrichment match with alikelihood from 1 to 10 and drops matches below min_likelihood, which defaults to 2. With required, a response counts as a match only when it contains the fields you list, and you are not charged otherwise.
CompanyEnrich has no score:
- Enrichment by domain looks up that domain.
- Enrichment by properties requires every property you send to match. If several companies match, it returns the highest-ranked one.
- Enrichment has no
required. In a search, therequirefilter keeps only companies that have a given feature, such as a LinkedIn profile or a revenue range.
likelihood checks from your code. Where you relied on min_likelihood for name lookups, send a domain, or add a social profile such as linkedinUrl to the name.
Status codes
NotFoundError, PaymentRequiredError, and RateLimitError.
Billing behavior that affects your code
These differences change how you write retries, guards, and tests. Prices for each endpoint are in Credits.- No match is free on both APIs. Enrichment that finds nothing returns
404and is not charged. - An empty search is charged. PDL charges per record returned, so a search with no results costs nothing. CompanyEnrich charges one result’s base price, such as 1 credit for a filter search. Check a new query with the free count endpoint first.
- Extra company fields are expansions. The base record excludes
financial,keywords,naicsCodes,technologies, andworkforce. Each one you request adds 1 credit per company returned, so request only the ones your code reads. - There is no charge guard like
required. A returned record is charged even when a field you need is empty. - Work emails are a separate call.
GET /v2/people/{personId}/emailcosts 10 credits only when it finds an email your account has not accessed before. - Responses report their cost. Read
x-credit-costandx-credit-remainingfrom the response headers.
Pagination
nextCursor is omitted on the last page, and a cursor expires 24 hours after the first page. The Python SDK pages for you with search_all(). A cursor or scroll token from one API does not work in the other, so restart any paging job from the first page.
Rate limits
PDL limits each key per endpoint. CompanyEnrich applies a global limit of 500 requests per minute per IP address and a per-route limit from your plan, reported inx-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-window. The SDKs wait and retry on 429. See Rate limits.
Text, URLs, and dates
IDs
PDL IDs and CompanyEnrich IDs are separate. Company IDs are UUIDs, and person IDs are 64-bit integers. During the migration, store the CompanyEnrich ID next to the PDL ID and re-key company data on its domain.Keep your PDL call sites: Python adapter
The adapter below runs PDLPY-style calls against CompanyEnrich, so you can test CompanyEnrich without rewriting call sites first. It coverscompany.enrichment, company.bulk, and person.enrichment. Treat it as a bridge: once your code works, move each call to the SDK and remove the adapter.
- Returns a PDLPY-style response. It has
.ok,.status_code,.json(), and.text..nativeholds the CompanyEnrich record unchanged. - Returns only mapped fields. Reading a PDL field that has no CompanyEnrich source, such as
likelihoodorid, raisesKeyError. Read the CompanyEnrich ID fromresponse.native["id"]. - Rejects inputs it cannot map, before any request.
ticker,pdl_id, location inputs,min_likelihood,required,data_include, personprofile,phone,lid, andemail_hashraiseUnsupportedInput. So does awebsitewith a path, or awebsitesent together withnameorprofile. - Ignores
prettyandtitlecase. Text keeps its source casing. - Picks one current job. Person
job_*fields come from the current experience at the email’s company, the one withisMatchedset. If no current experience matched, the adapter uses the first one. - Batches bulk requests.
company.bulkaccepts website-only requests, sends them in batches of 50, and returns one result per request in order, with yourmetadata. - Adds paid fields only when you ask.
PDLCompat(expand=["financial"])fillstickerandtotal_funding_raised.keywordsfillstags,naicsCodesfillsnaics, andworkforcefillsemployee_count. Each expansion adds 1 credit per company. - Leaves retries to the SDK, which does not repeat a paid request after an unclear failure.
pdl_compat.py
pdl_compat.py
companyenrich 1.0.1 and Python 3.10 or later.
Verify parity on your own data
Before you move production traffic, measure CompanyEnrich on records you already have. This publishes nothing and makes no PDL requests.Check your key and plan
GET /v2/me. It is free and returns your balance and plan capabilities.Pick a sample
Compare the fields you read
equal, differ, only PDL, only CompanyEnrich, or both empty. Fields marked lossy in the field mapping differ by definition, so leave them out or compare them by hand.Check searches and people
compare.py
compare.py
Cut over
- Put the CompanyEnrich path behind a feature flag and keep PDL as the fallback until the parity results meet the thresholds you set.
- Store CompanyEnrich IDs next to PDL IDs.
- Log
x-credit-costper call while both paths run. - Move reads first, then writes to stored records, then remove the adapter and the PDL client.
When to keep PDL
Keep PDL, or another source, for these workloads:- Person enrichment by LinkedIn URL, phone, email hash, or name with a company or location, and the Identify API.
- Personal emails and phone numbers.
- Bulk person enrichment in one request.
- Match controls:
likelihood,min_likelihood, andrequired. - Queries that need OR across different fields, wildcards,
existson any field, or person locations below country level. - Corporate hierarchy, SIC codes, skills, certifications, job postings, IP enrichment, the cleaner APIs, the changelog, and flat-file data.
What you can add after migrating
Semantic company search
Similar companies
Company headcount
MCP server
Common questions
Can I keep using my PDL IDs?
Can I keep using my PDL IDs?
Can I enrich a person by LinkedIn URL?
Can I enrich a person by LinkedIn URL?
POST /v2/people/enrich. Keep PDL for LinkedIn, phone, and hash lookups.Does CompanyEnrich accept Elasticsearch or SQL queries?
Does CompanyEnrich accept Elasticsearch or SQL queries?
filter object. See Translate People Data Labs search queries.Is there a likelihood score?
Is there a likelihood score?
How do I get the total number of results?
How do I get the total number of results?
Do batch and bulk enrichment need a specific plan?
Do batch and bulk enrichment need a specific plan?
Why is the text in a different case?
Why is the text in a different case?
titlecase=true. CompanyEnrich returns the source casing. Lowercase values yourself if your code compares strings.