Idempotency guarantees that a given API request is only processed once and the corresponding action is only executed once. This ensures that failures and retries do not result in duplicates.

The Numeral API supports idempotency through the optional addition of a unique ID in the Idempotency-Key HTTP header of your API calls:

curl --request POST \
     --url \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Idempotency-Key: e3b4b580-a816-490a-948a-fc565b14266b' \
     --header 'x-api-key: YOUR_API_KEY' \
     --data '
  "type": "sepa",
  "direction": "credit",
  "amount": 1000,
  "currency": "EUR",
  "connected_account_id": "0353824e-9417-4fab-b11e-49fd2ff0b6db",
  "reference": "Invoice 23516356",
  "receiving_account": {
    "account_number": "FR6130003000404997494726H46",
    "bank_code": "BNPAFRPPXXX",
    "holder_name": "PartnerCo",
    "holder_address": {
      "country": "FR"

We recommend using UUIDs v4 as idempotency keys.