All terms
API & Integration
Idempotency Key
An idempotency key is a unique client-generated value sent with an API request so that if the same request is retried, the server recognizes the key and processes the operation only once - preventing duplicate side effects such as creating a resource or charging a payment twice.
Also known asidempotency-key header
In depth
What Idempotency Key means.
An operation is idempotent if performing it multiple times has the same effect as performing it once. Reads are naturally idempotent; operations that create or change state, like submitting a job or a payment, are not. An idempotency key makes such an operation safe to retry: the client generates a unique value (often a UUID), sends it with the request - commonly in an Idempotency-Key header - and the server records the outcome against that key.
If a request fails midway or a response is lost to a network error, the client can safely resend it with the same key. The server sees that the key has already been processed and returns the original result instead of performing the operation again. This solves a fundamental problem of unreliable networks: without it, a client can never be sure whether a timed-out request actually took effect, and retrying risks creating duplicates.
Implementations vary in details - how long keys are retained, whether the key must be paired with an identical request body, and how concurrent requests with the same key are handled - but the contract is constant: the same key yields the same single result. Idempotency keys are especially important for payment APIs and for any system, such as webhook handlers, that must tolerate retries without double-processing.
How biz collect relates
Idempotency Key in biz collect.
biz collect supports idempotency keys on requests that start work, so retrying a search after a timeout or network blip does not launch a duplicate job or double-spend credits. The client supplies a unique key, and a retry with that same key returns the original job rather than creating a new one.
This matters most for automated and agentic callers, which retry aggressively and cannot tell a lost response from a failed operation. Together with signed webhooks and a stable JSON schema, idempotency-key support is part of what makes biz collect reliable to integrate into unattended pipelines.
Go deeper
Where this concept shows up across biz collect:
Idempotency Key
Frequently asked questions.
When should I send an idempotency key?
Send one on requests that create or change state and that you might retry - for example starting a job or a payment. Read-only requests are already idempotent and do not need a key.
What happens if I reuse the same idempotency key?
The server recognizes the key as already processed and returns the original result instead of performing the operation again, so a retry cannot create a duplicate. This is exactly what makes retries safe.
Still have questions? Talk to us.
Turn the concept into real data.
Sign up free with 200 signup credits, no credit card. POST a city plus keywords and get an enriched, structured list of businesses back as JSON.
No credit card required200 signup credits20 daily login credits