# Integration best practices

Everything on this page is optional - the API works fine call-by-call. But
these are the patterns that separate an integration that is fast, cheap and
robust from one that burns credits and retries blindly. If you are building
an automated integration or an AI agent on top of the API, start here.

## Retries and idempotency

Every v2 endpoint uses `POST`, but do not let the verb mislead you:

- **Search endpoints are read-only.** People Search, Company Search and
  Enums never change anything and never spend credits - retry them freely.
- **Enrich endpoints are safe to retry too.** Revealing an email or phone
  your workspace already unlocked is free, so replaying a successful
  People Enrich or Email Finder call does not double-charge you.
- Follow the per-status guidance on [Errors](https://getprospect.com/api-docs/errors.md): retry
  `408` after a few minutes and `5xx` with exponential backoff; never
  retry `400`, `401` or `402` unchanged - they will fail the same way
  again.

## Do not guess names or values

Request bodies are strictly validated: an unknown field anywhere in the
body fails the whole request with `400` rather than being ignored. The two
bulk endpoints are the one exception - an unknown field inside an item
moves that item to the `invalid` bucket instead of failing the batch.

Enum-backed filters accept exact, case-sensitive values only. Read them
from [Enums](https://getprospect.com/api-docs/enums.md) (or `GET /v2/enums` at integration time)
instead of inventing close-enough strings - `"vp"` matches nothing,
`"VP"` does. The full request and response shapes are machine-readable in
the [OpenAPI specification](https://getprospect.com/api-docs/openapi.json), and every docs page
has a markdown twin (append `.md` to its URL) indexed in
[llms.txt](https://getprospect.com/llms.txt).

## Control your spend

Searching is free; credits are only spent when contact data is revealed.
The cheap pattern is always: **search broadly, reveal narrowly.**

- Search with `enrich_email` off (the default on search). Every result
  already includes `has_email` and `email_status` for free.
- Narrow to the people worth paying for - for example, filter
  `contact_details.email.status` to `valid` so you only ever reveal
  addresses that exist.
- Reveal on the final subset only: re-run the narrowed search with
  `enrich_email: true`, or enrich the shortlist via
  [People Bulk Enrich](https://getprospect.com/api-docs/people-bulk-enrich.md).
- Have a list of LinkedIn URLs? Look them up for free first with
  [People Search](https://getprospect.com/api-docs/people-search.md)'s `person.linkedin_url` filter
  and only enrich the people it returns.
- When the balance hits zero, credit-gated endpoints return
  `402 Payment Required` with `X-Limit-Reached: true` - treat that as a
  hard stop, not a retryable error.

## Prefer bulk endpoints over loops

Enriching a list by looping the single endpoints works, but
[People Bulk Enrich](https://getprospect.com/api-docs/people-bulk-enrich.md) and
[Company Bulk Enrich](https://getprospect.com/api-docs/company-bulk-enrich.md) do up to 50 lookups
per request, keep partial failures contained (one bad item never fails the
batch), and echo your `identifier` on every outcome so results correlate
back to your rows without guesswork.

## Pagination and result caps

Search results come 25 per page by default and up to 100 with `per_page`;
a query reaches 25,000 results either way (page 1000 at 25 per page, page
250 at 100). Follow the stop conditions on [Pagination](https://getprospect.com/api-docs/pagination.md),
and if a search reports more matches than the cap, tighten the filters and
run several narrower queries (for example, split by country or headcount
range) rather than trying to page past the window.

## Pacing

Real API keys have no hard rate limit today - the practical limit is your
credit balance. Still, keep concurrency modest (a handful of requests in
flight), let the bulk endpoints replace request storms, and back off on
`5xx` instead of hammering.