# Idempotency

Async POST endpoints accept an optional `Idempotency-Key` header. Same key on a retry returns the same job's current state instead of dispatching a new one.

Supported on:

- `POST /api/public/v1/search/`
- `POST /api/public/v1/deep-search/`
- `POST /api/public/v1/agentic-search/`
- `POST /api/public/v1/enrich/phone/`

Sync enrichment endpoints (`/enrich/email/`, `/enrich/professional-url/`, `/enrich/professional-profile/`) do not support `Idempotency-Key`. The header is ignored if sent.

## Header

```
Idempotency-Key: <your-key>
```

- Max 255 characters. Anything longer is truncated server-side.
- Use a UUID, a request hash, or any client-generated unique value.
- Reuse the same value across retries of a single logical request.
- Generate a new value for each new logical request.

## Behavior

- **First call** with a given key — creates a job, returns `202` with `{id, status: "pending", created_at}`.
- **Replay with same key** — returns the same job's current state. No new dispatch, no new credit reservation.
- **Different key** — creates a separate job, separate billing.

## Scope

Keys are scoped to `(api_key, idempotency_key)`. Two different API keys on the same account using the same idempotency value get two separate jobs.

## Body mismatch on replay

If you replay with the same `Idempotency-Key` but a different request body, we return the **original** job's state (not the new request).

**Agentic Search is an exception:** reusing a key with a different validated body returns `409 conflict`, including changes to `webhook_url`. An unchanged replay returns the original job without another credit reservation. Use a new idempotency key for each new logical request, including requests to different endpoints.

## When to use

- Network retries
- Crash recovery

## Without an Idempotency-Key

Each `POST` creates a new job and new credit reservation. Two identical POSTs back-to-back with no key produce two separate jobs and two separate charges.

## See also

- [People Search](https://docs.clodo.ai/api-reference/endpoint/people-search), [Deep Search](https://docs.clodo.ai/api-reference/endpoint/deep-search), [Agentic Search](https://docs.clodo.ai/api-reference/endpoint/agentic-search), [Phone Enrichment](https://docs.clodo.ai/api-reference/endpoint/phone-enrichment) for the endpoint-specific request shapes.
- [Async Polling](https://docs.clodo.ai/guides/async-polling) for fetching state of an existing job.