Idempotent requests

The API supports idempotency so you can safely retry requests without performing the same operation twice. When creating or updating an object, include an idempotency key. This is a unique value the server uses to identify and handle repeated attempts of the same request. So, if a connection error occurs, you can safely repeat the request without creating a second object.

To make an idempotent request, generate an Idempotency-Key and include it in the request header. You can create keys however you prefer, but we recommend using UUIDv4 or another high-entropy random string to avoid collisions.

When to use idempotency keys

Use idempotency keys for POST requests that create objects:

curl --request POST \
     --url https://api.gravv.xyz/v1/customers \
     --header 'Api-Key: <Api Key>' \
     --header 'Idempotency-Key: 979879887678789_attempt_1' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "first_name": "john",
  "middle_name": "william",
  "last_name": "doe",
  "email": "johndoe@gmail.com",
  "phone": "+14123456789",
  "type": "individual",
  "gender": "male",
  "date_of_birth": "2024-04-16",
  "external_id": "individual_12345",
  "address": {
    "address_line1": "1800 N Pole St",
    "address_line2": "Suite 202",
    "city": "Orlando",
    "postal_code": "32801",
    "state": "US-FL",
    "country": "US"
  }
}
'