> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peopledatalabs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Building API workflows with an AI assistant
> How to use ChatGPT, Claude, or another AI assistant to build Person and Company Enrichment and Search workflows, and how to catch common mistakes before they cost you credits.
Many PDL customers use AI assistants such as ChatGPT or Claude to write the scripts that call PDL's APIs. An assistant without the right context will guess with confidence, and a wrong guess against a paid API can mean wasted credits, failed runs, or results you can't trust.
This guide covers the setup that applies to every PDL API, then the details that matter for [each API](#api-specific-guidance).
> [!TIP]
>
> **The short version**
>
> * Give the assistant PDL's documentation, and tell it to use only what's documented.
> * Test in the [Sandbox](#step-2-test-in-the-sandbox) first. It's free on all plans.
> * Cap your spend: start small, set `size` on searches, and set `min_likelihood` on enrichments.
> * Keep your API key out of the chat and out of the code.
> * [Review the code](#step-4-review-the-code-before-you-run-it) before you run it.
***
## Choose the right API
Decide whether you need an **Enrichment** API or a **Search** API, and tell your assistant which one. Assistants sometimes pick the wrong one.
> **Enrichment**
>
> **Use it when:** you already know who or what you're looking for (an email, a LinkedIn URL, a company website) and want the full profile.
>
> **What comes back:** one best-match record, with a likelihood score.
>
> **Credits:** per match. A `404` (no match) is free.
> **Search**
>
> **Use it when:** you want a list of people or companies that match criteria, such as engineers in a given country.
>
> **What comes back:** up to 100 records per request, plus a `total` count of matches.
>
> **Credits:** per record returned.
| API | Endpoint |
| :- | :- |
| [Person Enrichment](https://docs.peopledatalabs.com/docs/person-enrichment-api) | `GET /v5/person/enrich` |
| [Bulk Person Enrichment](https://docs.peopledatalabs.com/docs/bulk-enrichment-api.md) | `POST /v5/person/bulk` |
| [Person Search](https://docs.peopledatalabs.com/docs/person-search-api) | `/v5/person/search` |
| [Company Enrichment](https://docs.peopledatalabs.com/docs/company-enrichment-api) | `GET /v5/company/enrich` |
| [Bulk Company Enrichment](https://docs.peopledatalabs.com/docs/bulk-company-enrichment-api.md) | `POST /v5/company/enrich/bulk` |
| [Company Search](https://docs.peopledatalabs.com/docs/company-search-api) | `/v5/company/search` |
All endpoints live under `https://api.peopledatalabs.com`. Rate limits depend on your plan and the endpoint. Check them in the [API dashboard](https://dashboard.peopledatalabs.com/) or see [Usage Limits](https://docs.peopledatalabs.com/docs/usage-limits.md).
***
## Step 1: Give your assistant the right context
AI assistants learn from a snapshot of the internet. That snapshot can be out of date, or blend PDL with other data providers. **PDL's documentation is the source of truth**, so put it in front of the assistant.
### Which pages to share
* The **reference** and **input parameters** pages for the API you're using
* The [Person Schema](https://docs.peopledatalabs.com/docs/fields) or [Company Schema](https://docs.peopledatalabs.com/docs/company-schema), so it uses real field names
* The [Sandbox APIs reference](https://docs.peopledatalabs.com/docs/sandbox-apis-reference.md), so it can test without spending credits
### How to share them
Every page on this site is available as Markdown, which assistants read more reliably than a web page.
| Method | What you get |
| :- | :- |
| Add `.md` to the end of a page URL | The page as plain Markdown, such as `https://docs.peopledatalabs.com/docs/fields.md` |
| **Copy page** menu, at the top of each page | Copy the page as Markdown, or open it directly in ChatGPT or Claude |
| [`/llms.txt`](https://docs.peopledatalabs.com/llms.txt) | A list of every page on the site, linked to its Markdown version. Useful when the assistant can browse and needs to find pages on its own. |
| [`/llms-full.txt`](https://docs.peopledatalabs.com/llms-full.txt) | Every page in one file. It's several megabytes, too large for a chat. Use it only with coding agents or tools that search files. |
### Start with a setup prompt
Pick your API below to generate a setup prompt with the right links. Paste it at the start of a new chat, then follow it with a task prompt from [API-specific guidance](#api-specific-guidance).
Which API are you using?
If your assistant can't open links, paste the text of each page into the chat.
> [!WARNING]
>
> Contact lists often contain personal data. Check your company's policy on what you can paste into an AI assistant. Share sample rows rather than full files when you can.
***
## Step 2: Test in the Sandbox
The [Sandbox APIs](https://docs.peopledatalabs.com/docs/sandbox-apis) mirror the production Person and Company APIs, but return **synthetic data** and don't use credits. All plans have access.
* Sandbox endpoints use the same paths on a different host: `https://sandbox.api.peopledatalabs.com/v5/person/enrich`.
* The Sandbox allows 5 requests per minute. Ask the assistant to pause between test requests.
* PDL's SDKs have a sandbox setting. See [Sandbox API examples](https://docs.peopledatalabs.com/docs/sandbox-apis-examples.md) for Python, JavaScript, Ruby, and Go.
* Because the data is synthetic, **real-world values often won't match**. A search for a real city or company may return nothing. That doesn't mean the query is broken.
See the [Sandbox APIs reference](https://docs.peopledatalabs.com/docs/sandbox-apis-reference.md) for the sample datasets and which endpoints are available.
***
## Step 3: Control your costs
Most surprises come from code that sends more requests, or returns more records, than you intended. Ask your assistant to build in these safeguards:
* **Start small.** Run 5 to 10 records first, check the output, then scale up.
* **Search: always set `size`.** It defaults to 1 and maxes out at 100. Credits equal the number of records returned.
* **Search: check `total` first.** Every response reports how many records match. If that number surprises you, refine the query before you pull everything.
* **Search: stop on purpose.** Paginate with `scroll_token`, and stop when you have what you need, or when it comes back `null` or you get a `404`.
* **Enrichment: set `min_likelihood` on purpose.** The default is `2`, which favors finding a match over being certain.
* **Enrichment: use bulk for lists.** Bulk endpoints take up to 100 records per request. A 5,000-row list takes 50 requests instead of 5,000, and you still pay only per match.
* **Save as you go.** Write results to a file after each batch, so a failure midway doesn't mean paying twice.
* **Respect rate limits.** Pause or slow down on a [`429` response](https://docs.peopledatalabs.com/docs/errors) instead of retrying right away.
**Example:** a Person Search reports a `total` of 25,000, and you need 500 records. With `size` set to 100, that's 5 requests and 500 credits. A script that follows `scroll_token` to the end makes 250 requests and uses 25,000 credits. Ask your assistant to state its stopping condition before you run anything.
***
## Step 4: Review the code before you run it
You don't have to read every line. Ask the assistant to walk you through each item below, or copy the checklist as a prompt and paste it into a fresh chat with the code.
Search
Enrichment
of checked
Checklist progress
Paste it into a fresh chat with the assistant's code.
***
## Common mistakes to watch for
PDL's solutions engineers see these mistakes most often in AI-generated code. If a run fails or returns something odd, check this table first.
| What the assistant does | What's actually true | Applies to |
| :- | :- | :- |
| Uses query types like aggregations, `nested`, `fuzzy`, or boosting | Search accepts only `term`, `terms`, `exists`, `bool`, `match`, `range`, `match_phrase`, `wildcard`, `prefix`, and `match_all`. | Search |
| Sends both `query` and `sql` | Send one or the other, never both. PDL recommends `query` for most uses. | Search |
| Invents or guesses field names | Search runs against the raw dataset, so field names must be exact. Check the [Person Schema](https://docs.peopledatalabs.com/docs/fields) or [Company Schema](https://docs.peopledatalabs.com/docs/company-schema). | Search |
| Assumes Search returns everything | `size` defaults to 1 and caps at 100 per request. Use `scroll_token` to get the next batch. | Search |
| Uses `from` to paginate | `from` is deprecated. Use `scroll_token`. | Search |
| Puts thousands of values in a `terms` list | Arrays are capped at 1,000 elements on Person Search and 100 on Company Search. | Search |
| Uses many wildcards or `LIKE` clauses | Wildcards are limited to 20 per request. | Search |
| Searches for `"Software Engineer"` with capital letters | PDL stores text in lowercase. Query for `"software engineer"`. | Search |
| Sends one request per row of a list | Bulk enrichment takes up to 100 records per request, at the same credit cost. | Enrichment |
| Treats a `404` from Enrichment as an error | It means no match was found. It's a normal outcome, and it's free. | Enrichment |
| Accepts every enrichment match as correct | Each match has a likelihood from 1 to 10. Low scores mean less confidence. Set `min_likelihood` to fit how accurate you need to be. | Enrichment |
| Says the query is broken because the Sandbox returned nothing | Sandbox data is synthetic. Real names and places often won't match. | Both |
***
## API-specific guidance
Each tab covers what the API needs, what to watch for, and a task prompt to paste after your setup prompt. For parameters and defaults, follow the reference links at the bottom of each tab.
**Person Enrichment**
[Person Enrichment](https://docs.peopledatalabs.com/docs/person-enrichment-api) finds the **one** person that best matches the details you provide. For lists, use [Bulk Person Enrichment](https://docs.peopledatalabs.com/docs/bulk-enrichment-api.md).
**Minimum inputs:** one of these combinations. More data points mean a better chance of a match.
* **A unique identifier:** `profile`, `email`, `phone`, `email_hash`, `lid`, or `pdl_id`
* **A name plus one more detail:** `name` (or `first_name` + `last_name`), plus `company`, `school`, a location field, or `birth_date`
**Watch for:**
* A **name alone** isn't enough.
* Using results for email outreach? Use only `recommended_personal_email` and `work_email`. See [Email Data for Outreach](https://docs.peopledatalabs.com/docs/email-data-for-outreach.md).
```text Task prompt wrap theme={null}
Write a workflow that enriches a spreadsheet of contacts with these columns: full name, company, LinkedIn URL.
Use the LinkedIn URL as profile when it's present; otherwise use name plus company.
Send rows through the Bulk Person Enrichment endpoint, up to 100 per request.
Set min_likelihood to 4, and save each result's likelihood next to the record.
Treat a no-match result as normal, not an error.
Use data_include so only the fields I need come back.
Test with 5 rows in the Sandbox first.
```
> **[Reference](https://docs.peopledatalabs.com/docs/reference-person-enrichment-api.md)**
> **[Input parameters](https://docs.peopledatalabs.com/docs/input-parameters-person-enrichment-api.md)**
**Person Search**
[Person Search](https://docs.peopledatalabs.com/docs/person-search-api) finds **many** people who match criteria you define, such as job role, location, or company. You describe them with an Elasticsearch `query` or a `sql` string, but not both. The query runs directly against the Person Dataset, so **field names and values must be exact**.
**Watch for:**
* **SQL needs subfields.** `WHERE experience IS NOT NULL` fails, but `WHERE experience.title.name IS NOT NULL` works.
* **Job titles are tricky.** See [Searching by job\_title](https://docs.peopledatalabs.com/docs/searching-by-job-title.md) for why a role and subrole search usually beats exact matching.
* **Names need standardizing.** Use the [Cleaner APIs](https://docs.peopledatalabs.com/docs/cleaner-apis) to turn company, school, or location names into values PDL recognizes.
* **Try queries by hand first.** The [API Playground](https://dashboard.peopledatalabs.com/tools/api-playground) is free with a PDL account.
```text Task prompt wrap theme={null}
Build a Person Search query for people in the United States whose job_title_role is engineering and job_title_sub_role is software, and who have a work_email.
Use only the allowed Elasticsearch query types.
Set size to 10 and show me the query before you run it.
Report the total number of matches and the most credits it would cost to retrieve all of them.
Use scroll_token if we need more.
```
> **[Reference](https://docs.peopledatalabs.com/docs/reference-person-search-api.md)**
> **[Input parameters](https://docs.peopledatalabs.com/docs/input-parameters-person-search-api.md)**
**Company Enrichment**
[Company Enrichment](https://docs.peopledatalabs.com/docs/company-enrichment-api) finds the **one** company that best matches the details you provide. For lists, use [Bulk Company Enrichment](https://docs.peopledatalabs.com/docs/bulk-company-enrichment-api.md).
**Minimum inputs:** at least one of `pdl_id`, `name`, `ticker`, `website`, or `profile` (a social URL such as LinkedIn).
**Watch for:**
* **Names are weak matches.** `website`, `ticker`, and `profile` match more reliably. A name-only request typically scores between 2 and 5.
* **`pdl_id` wins.** If you send it with other inputs, the API uses only the ID.
* **Low scores are often wrong.** At a likelihood of `2`, there may be only a 10 to 30% chance the match is right. For accuracy-sensitive work, use `6` or higher.
* **The Sandbox has no bulk company endpoint.** Test with single requests, then switch to bulk.
```text Task prompt wrap theme={null}
Write a workflow that enriches a list of companies.
Use the company website when I have it, and fall back to name if I don't.
Set min_likelihood to 4 and turn on include_if_matched.
Save the likelihood and matched fields with each result, and flag any company that only matched on name.
Treat a no-match result as normal.
Test with 5 single requests in the Sandbox, then use the Bulk Company Enrichment endpoint for the full list.
```
> **[Reference](https://docs.peopledatalabs.com/docs/reference-company-enrichment-api.md)**
> **[Input parameters](https://docs.peopledatalabs.com/docs/input-parameters-company-enrichment-api.md)**
**Company Search**
[Company Search](https://docs.peopledatalabs.com/docs/company-search-api) finds **many** companies that match criteria you define. Like Person Search, you send an Elasticsearch `query` or a `sql` string, but not both, and field names and values must be exact.
**Watch for:**
* **Person fields don't work here.** The two datasets have different schemas, so check each field against the [Company Schema](https://docs.peopledatalabs.com/docs/company-schema).
* **Arrays cap at 100 elements**, much lower than Person Search.
* **Names need standardizing.** The [Cleaner APIs](https://docs.peopledatalabs.com/docs/cleaner-apis) can standardize company names and locations before you search.
```text Task prompt wrap theme={null}
Build a Company Search query for companies in a specific industry and country.
Before writing the query, look up the exact field names and allowed values in the Company Schema and tell me which fields you plan to use.
Use only the allowed Elasticsearch query types.
Set size to 10, show me the query before you run it, and report the total number of matches and the most credits it would cost to retrieve them all.
```
> **[Reference](https://docs.peopledatalabs.com/docs/reference-company-search-api.md)**
> **[Input parameters](https://docs.peopledatalabs.com/docs/input-parameters-company-search-api.md)**
***
## Resources
> **[Sandbox APIs reference](https://docs.peopledatalabs.com/docs/sandbox-apis-reference.md)**
>
> Sample datasets and how each Sandbox endpoint behaves.
> **[Bulk Person Enrichment](https://docs.peopledatalabs.com/docs/bulk-enrichment-api.md)**
>
> Enrich up to 100 people in one request.
> **[Person Schema](https://docs.peopledatalabs.com/docs/fields)**
>
> Exact field names and values for person records.
> **[Company Schema](https://docs.peopledatalabs.com/docs/company-schema)**
>
> Exact field names and values for company records.
> **[Searching by job\_title](https://docs.peopledatalabs.com/docs/searching-by-job-title.md)**
>
> How to search job titles with wildcards and the role/subrole taxonomy.
> **[API Playground](https://dashboard.peopledatalabs.com/tools/api-playground)**
>
> Build and test queries by hand before you script them.
## Related topics
- [Guides](https://docs.peopledatalabs.com/learn/guides.md)
- [November 2024 Release Notes](https://docs.peopledatalabs.com/changelog/november-2024-release-notes-v281.md)
- [Connect Your PDL API Key to Clay](https://docs.peopledatalabs.com/docs/clay-byok.md)
- [Example Job Posting Record](https://docs.peopledatalabs.com/docs/example-job-posting-record.md)
- [Verify Enrichment Workflows](https://docs.peopledatalabs.com/docs/salesforce-integration-setup-verify-enrichment-workflows.md)