Building API workflows with an AI assistant

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.

The short version

Give the assistant PDL’s documentation, and tell it to use only what’s documented.
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 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	`GET /v5/person/enrich`
Bulk Person Enrichment	`POST /v5/person/bulk`
Person Search	`/v5/person/search`
Company Enrichment	`GET /v5/company/enrich`
Bulk Company Enrichment	`POST /v5/company/enrich/bulk`
Company Search	`/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 or see Usage Limits.

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.

The reference and input parameters pages for the API you’re using
The Person Schema or Company Schema, so it uses real field names
The Sandbox APIs reference, so it can test without spending credits

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

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

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 or 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 Search
Company Enrichment
Company Search

Person Enrichment finds the one person that best matches the details you provide. For lists, use Bulk Person Enrichment.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.

Task prompt

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

Input parameters

Person Search 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 for why a role and subrole search usually beats exact matching.
Names need standardizing. Use the Cleaner APIs to turn company, school, or location names into values PDL recognizes.
Try queries by hand first. The API Playground is free with a PDL account.

Task prompt

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

Input parameters

Company Enrichment finds the one company that best matches the details you provide. For lists, use Bulk Company Enrichment.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.

Task prompt

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

Input parameters

Company Search 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.
Arrays cap at 100 elements, much lower than Person Search.
Names need standardizing. The Cleaner APIs can standardize company names and locations before you search.

Task prompt

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.

Guides

Best Practices

Recipes

Tutorials

Choose the right API

Enrichment

Search

Step 1: Give your assistant the right context

Start with a setup prompt

Step 2: Test in the Sandbox

Step 3: Control your costs

Step 4: Review the code before you run it

Common mistakes to watch for

API-specific guidance

Reference

Input parameters

Reference

Input parameters

Reference

Input parameters

Reference

Input parameters

Resources

Sandbox APIs reference

Bulk Person Enrichment

Person Schema

Company Schema

Searching by job_title

API Playground

​Choose the right API

Enrichment

Search

​Step 1: Give your assistant the right context

​Which pages to share

​How to share them

​Start with a setup prompt

​Step 2: Test in the Sandbox

​Step 3: Control your costs

​Step 4: Review the code before you run it

​Common mistakes to watch for

​API-specific guidance

Reference

Input parameters

Reference

Input parameters

Reference

Input parameters

Reference

Input parameters

​Resources

Sandbox APIs reference

Bulk Person Enrichment

Person Schema

Company Schema

Searching by job_title

API Playground

Choose the right API

Step 1: Give your assistant the right context

Which pages to share

How to share them

Start with a setup prompt

Step 2: Test in the Sandbox

Step 3: Control your costs

Step 4: Review the code before you run it

Common mistakes to watch for

API-specific guidance

Resources