Skip to main content
This guide is for engineers who call the People Data Labs (PDL) v5 API and are moving some or all of those calls to the CompanyEnrich V2 API. It maps each PDL endpoint, lists the behavior that changes in your code, and shows how to check the result on your own data before you switch traffic.
PDL behavior on these pages was checked against PDL’s public v5 documentation on November 13, 2026. CompanyEnrich behavior comes from the V2 API reference. The full mapping is also available as JSON at /migrations/people-data-labs.json.

Field mapping

Every PDL company and person field, with its CompanyEnrich counterpart.

Search queries

Translate Elasticsearch and SQL queries into filters.

With a coding agent

Instructions a coding agent follows to migrate your codebase.

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.
1

Get an API key

Create a key at app.companyenrich.com/access-keys and export it as COMPANYENRICH_API_KEY. Check it with GET /v2/me, which is free:
2

Install the SDK

The Python SDK needs Python 3.10 or later. There are also SDKs for JavaScript, Ruby, and PHP.
3

Replace the call

4

Update the fields you read

The field mapping covers every other field.
5

Handle no match

PDLPY returns a response with status 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:
See Migrate with a coding agent for what the agent does and the rules it follows.

Endpoint mapping

Company

People

Supporting APIs

Request and response differences

Authentication

Response shape

Match confidence

PDL scores every enrichment match with a likelihood 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, the require filter keeps only companies that have a given feature, such as a LinkedIn profile or a revenue range.
Remove 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

In Python, PDLPY returns a response for every status. The CompanyEnrich SDK raises a typed exception for each non-2xx status, such as 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 404 and 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, and workforce. 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}/email costs 10 credits only when it finds an email your account has not accessed before.
  • Responses report their cost. Read x-credit-cost and x-credit-remaining from the response headers.

Pagination

On CompanyEnrich, 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 in x-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 covers company.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.
What it does:
  • Returns a PDLPY-style response. It has .ok, .status_code, .json(), and .text. .native holds the CompanyEnrich record unchanged.
  • Returns only mapped fields. Reading a PDL field that has no CompanyEnrich source, such as likelihood or id, raises KeyError. Read the CompanyEnrich ID from response.native["id"].
  • Rejects inputs it cannot map, before any request. ticker, pdl_id, location inputs, min_likelihood, required, data_include, person profile, phone, lid, and email_hash raise UnsupportedInput. So does a website with a path, or a website sent together with name or profile.
  • Ignores pretty and titlecase. Text keeps its source casing.
  • Picks one current job. Person job_* fields come from the current experience at the email’s company, the one with isMatched set. If no current experience matched, the adapter uses the first one.
  • Batches bulk requests. company.bulk accepts website-only requests, sends them in batches of 50, and returns one result per request in order, with your metadata.
  • Adds paid fields only when you ask. PDLCompat(expand=["financial"]) fills ticker and total_funding_raised. keywords fills tags, naicsCodes fills naics, and workforce fills employee_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
Written for 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.
1

Check your key and plan

Call GET /v2/me. It is free and returns your balance and plan capabilities.
2

Size your searches for free

Send each translated query to the company or people count endpoint and compare total with PDL’s total.
3

Pick a sample

Take 100 to 200 company responses you already stored from PDL. Using stored responses means you spend no PDL credits. CompanyEnrich charges 1 credit per company found, plus any expansions.
4

Compare the fields you read

Run the script below on the sample. It enriches the domains in batches of 50 and sorts each field into 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.
5

Check searches and people

For each translated search, run the count, then a preview if your plan includes it, then one page. For person lookups, test work emails you already know.
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-cost per 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, and required.
  • Queries that need OR across different fields, wildcards, exists on 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.
You can run both APIs side by side and route each call by the endpoint mapping.

What you can add after migrating

Semantic company search

Search companies with a plain-language description instead of a query.

Similar companies

Find lookalikes of up to 10 seed domains.

Company headcount

Headcount by department, with monthly history.

MCP server

Give AI agents access to the same data.

Common questions

No. Store the CompanyEnrich ID alongside the PDL ID, and re-key company data on its domain.
No. CompanyEnrich enriches a person by work email with POST /v2/people/enrich. Keep PDL for LinkedIn, phone, and hash lookups.
No. Searches take a filter object. See Translate People Data Labs search queries.
Send the same filter to the free count endpoint. Search responses do not include a total.
No. Batch and bulk enrichment work on every plan.
PDL lowercases text unless you send titlecase=true. CompanyEnrich returns the source casing. Lowercase values yourself if your code compares strings.