# Migrate from People Data Labs v5 to CompanyEnrich V2
You are migrating this codebase from the People Data Labs (PDL) v5 API to the CompanyEnrich V2 API.
## Sources
Read the mapping file first. It is authoritative for endpoints, inputs, fields, values, and search patterns.
- Mapping: https://docs.companyenrich.com/migrations/people-data-labs.json
- Guide: https://docs.companyenrich.com/docs/migrate-from-people-data-labs.md
- Field mapping: https://docs.companyenrich.com/docs/migrate-from-people-data-labs-field-mapping.md
- Search translation: https://docs.companyenrich.com/docs/migrate-from-people-data-labs-search.md
- Credits: https://docs.companyenrich.com/docs/credits.md
- API specification: https://docs.companyenrich.com/openapi/v2.json
- SDKs: https://docs.companyenrich.com/docs/python-sdk.md, https://docs.companyenrich.com/docs/javascript-typescript-sdk.md, https://docs.companyenrich.com/docs/ruby-sdk.md, https://docs.companyenrich.com/docs/php-sdk.md
If you cannot read the mapping file, stop and ask the user to add it to the repository.
## Rules
1. Use only the mappings in the mapping file and the endpoints in the API specification. If a PDL field, input, or query has no entry, do not guess: leave the PDL code in place and add a `TODO(companyenrich-migration)` comment that names it.
2. Do not change code until the user approves the migration report from step 2.
3. Do not make PDL requests. Do not make paid CompanyEnrich requests. If the user has set `COMPANYENRICH_API_KEY`, you may call `GET /v2/me`, `POST /v2/companies/search/count`, `POST /v2/people/search/count`, and the lookups for filter values (autocomplete, the industry list, and the `geo` endpoints), which are free. Any other live call needs the user's explicit approval and a credit budget.
4. Read the CompanyEnrich key from the `COMPANYENRICH_API_KEY` environment variable. Never hardcode, print, log, or commit an API key.
5. Keep the PDL integration and its configuration. Put each CompanyEnrich path behind a feature flag or configuration switch, using the project's existing convention if there is one.
6. Request only the expansions for fields the code reads. Each expansion adds credits per record.
7. Translate a search query only when every condition has a pattern. Never drop a condition, and never replace filters with a semantic query.
8. Use the official CompanyEnrich SDK for the repository's language. Use HTTP only when no SDK exists for it.
9. Do not run database migrations or backfills. Write migration files for the user to review.
## Step 1: Inventory
Find every use of PDL:
- SDK clients: Python `peopledatalabs` (`PDLPY`), JavaScript `peopledatalabs` (`PDLJS`), and PDL clients in other languages.
- HTTP requests to `api.peopledatalabs.com/v5`.
- Configuration: PDL API keys, environment variables, and settings.
- Reads of PDL response fields: every `pdl` name in the mapping file's `fields`, plus `status`, `likelihood`, `data`, `total`, and `scroll_token`.
- Stored PDL data: models, columns, and serializers with PDL field names, PDL IDs, or PDL enum values such as sizes, revenue ranges, and job levels.
- Tests, fixtures, and mocks for PDL.
## Step 2: Write the migration report, then stop
Write `pdl-migration-report.md` at the repository root, unless the user names another place. Include:
1. A table of call sites with: file and line, PDL endpoint and inputs, fields read, classification, CompanyEnrich replacement, expansions needed, and notes. Classify each call site as:
- **moves**: the endpoint entry has status `mapped` or `partial`, every input the call sends has a mapping, every field the code reads has a mapping other than `none`, and every search condition has a pattern. `lossy` and `transformed` mappings still move. List them in the notes.
- **needs redesign**: the call can move, but behavior the code relies on changes. For example, the code branches on `likelihood`, relies on `required`, or compares, scores, or stores values whose labels or definitions change, such as size ranges. A search query with a condition that has no pattern also needs redesign, and stays on PDL until the user decides.
- **keep PDL**: the endpoint or an input the call sends has no equivalent, or the code needs a field whose fidelity is `none`.
A domain lookup that passes `min_likelihood` but never reads the score still moves. CompanyEnrich looks the company up by its domain, so there is no score to set. Note the dropped parameter.
2. Billing behavior that changes for each call: empty searches are charged one result's base price, each expansion adds credits, and work emails are a separate call.
3. Stored data that changes, and the ID plan: add CompanyEnrich ID columns next to PDL IDs and re-key company data on its domain.
4. Open questions, such as which current job to use when a person has several, and the feature flag name.
Stop and ask the user to approve, change, or exclude call sites.
## Step 3: Rewrite approved call sites
- Replace each call with the CompanyEnrich endpoint from `endpoints`, and map its inputs with `inputs`.
- Convert field reads with `fields`. A row with `in: workEmail` comes from `GET /v2/people/{personId}/email`, a separate call. A row with `expand` needs that expansion in the request.
- Convert enum values with `values`.
- A person can have several current experiences, marked with `isCurrent`. Use the one with `isMatched` set: after an email lookup, that is the job at the email's company. If none or several qualify, follow the policy the user approved. Do not silently take the first one.
- CompanyEnrich returns the record as the response body, with no `status`, `likelihood`, or `data` wrapper.
- No match returns `404` and is not charged. The SDKs raise a not-found error. `402` can mean no credits or a plan without the feature, so do not retry it.
- Remove `likelihood`, `min_likelihood`, and `required` logic. Where behavior depended on it, add a TODO and list it in the report.
- Enrich lists of domains with `POST /v2/companies/enrich/batch`, 50 per request, or a bulk job for up to 10,000.
- Page searches with `pageSize` (1 to 100) and `cursor`, taken from `nextCursor`.
- CompanyEnrich returns text in source casing and social URLs with `https://`. Normalize explicitly where the code compares strings.
## Step 4: Translate searches
For each PDL query, split it into conditions and map each one with the `search` patterns. If any condition has no pattern, or its pattern maps to `null`, keep the PDL query and add a TODO. Patterns with `STATE_ID` or `CITY_ID` need an ID from the free `geo` endpoints. Without a key, leave a TODO that names the place to look up. An OR across different fields becomes separate searches only if the user approves, because each search is charged. Add a test that asserts the exact filter your code builds.
## Step 5: Stored data
Write, but do not run, migrations that add columns for CompanyEnrich IDs and values next to the PDL columns. Keep the original PDL values, and do not overwrite PDL columns with CompanyEnrich data. A stored PDL value converted with `values` has a CompanyEnrich label but is still PDL data. Keep it apart from values the API returns, or record where each value came from. Do not backfill records through the API without approval.
## Step 6: Tests
- Mock HTTP for every new CompanyEnrich call: `httpx.MockTransport` through the Python SDK's `http_client`, a stub `fetch` for the JavaScript SDK, or a stub server through `base_url` or `baseUrl` for Ruby and PHP. Start from the records under `fixtures` in the mapping file, and build other responses from the response schemas in the API specification.
- Cover a match, `404`, `402`, `429`, an empty search, and a call site that stays on PDL.
- Run the project's test suite. Tests must not call live APIs.
## Step 7: Final report
Update `pdl-migration-report.md` with the files changed, the call sites that moved, the ones that stay on PDL and why, the remaining TODOs, the expansions each call requests, how to switch the feature flag, and a link to the parity check: https://docs.companyenrich.com/docs/migrate-from-people-data-labs.md#verify-parity-on-your-own-data