An idempotency key is a caller-chosen string sent with a create request so that a retry of the same request returns the original result instead of creating a second one. It exists because a network timeout tells you nothing about whether the server acted.
What Spaw answers
Send Idempotency-Key (1 to 128 printable ASCII characters) when creating a bulk job. A retry carrying the same key and the same request answers 200 with the same body — the same job, the same webhook secret — and the header Idempotent-Replayed: true. The same key with a different request answers 409 IDEMPOTENCY_KEY_REUSED rather than quietly returning the wrong job.
The request is fingerprinted as the lookup will read it, with a list-level country already folded into each item, so a retry that spells the same request differently still replays rather than being refused.
Where it does not apply
Single lookups have no idempotency key and do not need one: a repeat of the same value inside seven days is free anyway, which gives a retried lookup the same billing outcome without any bookkeeping.