Skip to main content
Human guide: work with your agent → Inspect one People Data Labs action before starting provider-backed work. Your first result is a verified input and output contract.

​
Provider-specific requirements

Use People Data Labs when you need explicit, auditable structured filters.

​
Reading results

Use the exact declared getters from describe <tool-id> or describe: company enrichment declares company_name and company_domain. contact enrichment declares contact getters. search actions declare list getters. Do not invent getters for other profile fields. toolResponse.rawV2 preserves the complete parsed and scrubbed provider/tool adapter envelope. The checked-in company enrichment sample is { data: { status: 200, data: { name, website, ... } } }, so that sample’s company is at rawV2.data.data. Other responses or execution surfaces can have a different wrapper. Inspect the original retained response, then assert the exact field path and type before bulk execution. Missing an expected profile field at a guessed path is an extraction error, not proof PDL returned no data. view: "data" does not flatten rawV2. schema and extractor provenance do not establish its observed nesting.

​
Choosing and calling tools

  • Normalize noisy input first with clean helpers before running expensive search/enrich operations.
  • Use autocomplete and narrow incrementally to avoid over-constraining initial queries.
  • Treat Person Search size as a spend cap: every returned profile is billed. Start with size: 1, inspect total and field coverage, then request only the number of profiles the user can use.
  • For surgical gap-fill, prefer size: 3-5. Do not default to pages of 30, 40, or 100 after earlier providers have already returned candidates. post-response deduplication cannot recover the PDL spend.
  • Put must-have fields into the search itself, for example work_email IS NOT NULL, personal_emails IS NOT NULL, mobile_phone IS NOT NULL, or an Elasticsearch exists clause. Use the matching dataset slice where appropriate.
  • For peopledatalabs_person_search / peopledatalabs_company_search SQL: use SELECT * only and DO NOT include a LIMIT clause — PDL rejects any SQL with LIMIT as HTTP 400. Pass the size input parameter (1–100) to control how many records come back.
  • required and min_likelihood are Person Enrichment controls, not Person Search inputs. Use peopledatalabs_enrich_contact when you already know the approximate person and need one strict match.
  • Enrichment accepts data_include. Use comma-separated fields to include data, or a leading - to exclude data. To suppress the data payload, pass the literal two-character quote pair "". A bare empty value is ignored and returns the full record. Projection does not reduce usage. Use required and min_likelihood to control which matches are billable.
  • Bulk person and company enrichment preserve these controls. Person bulk details may override shared controls per request. Company bulk controls apply to every domain in the batch.
  • Deduplicate and normalize inputs before bulk enrichment. peopledatalabs_bulk_people_enrichment and peopledatalabs_bulk_organization_enrichment bill per matched row. Repeated matches remain billable. Strip URL schemes, www., and trailing slashes. Reconcile name-based and domain-based rows to one identifier per entity. Exact-string deduplication alone is insufficient. Deepline batch item keys do not merge these variants. Responses correspond to input positions, so the batch cannot safely deduplicate them for you.
  • For personal-email-only use cases, require personal_emails before billing by passing PDL’s required=personal_emails parameter. The default Person Enrichment API bills per matched person profile, even if no personal email is present.
  • PDL documents x-call-credits-spent as the per-call charge response header. Deepline parses that header into meta.creditsSpent and prefers it for billing before any fallback estimate.
  • In changed-company email recovery, treat PDL as the fallback after LeadMagic and Crust.
  • If earlier, cheaper steps already returned a usable email, skip PDL for that row.

​
Find an applicable action

Confirm your effective workspace, then search the live catalog:
Search returns candidates. Check the returned provider and operation rather than selecting a similar title automatically.

​
Inspect the selected contract

Replace <returned-tool-id> with the identifier returned by discovery:
These commands do not execute the selected provider action. Read its required inputs, supported access mode, pricing unit, outputs, and limits. A connection does not establish that every action supports BYOK. Follow the provider-specific requirements above and the live action contract.

​
Prepare one reviewed input

Use one authorized record that matches the inspected schema. Preserve its source identity and define the result you will accept. Open the action reference for its payload and response shape. Provider-backed execution can incur usage or external effects. For reusable logic, follow Write Plays. For direct-call recovery, use Tool execution recovery.
Continue only when the workspace, provider, required fields, acceptance rule, and applicable price are understood. Keep unavailable access separate from no-result evidence.