Idempotency

Safely retry POST requests without creating duplicate records. Send the same Idempotency-Key header on retries and PGI will return the original response without processing the request a second time.

When to use it

Network interruptions, process restarts, and load-balancer timeouts can leave you unsure whether a POST request reached PGI and was processed. Without idempotency, retrying that request creates a duplicate record.

Use Idempotency-Key on any POST that creates a resource and must not be created twice:

Submitting an application (POST /api/v2/applications/)
Binding a policy (POST /api/v2/bind/)
Filing a claim (POST /api/v2/claims/)
Opening a support ticket or message (POST /api/v2/support/tickets/)
Uploading a document (POST /api/v2/applications/{id}/documents/)
Running a pre-approval score (POST /api/v2/score/)

GET requests are already idempotent The Idempotency-Key header has no effect on GET requests. You only need it for POST operations that create or mutate state.

Header format

Idempotency-Key: 6f7b94e2-1c3a-4f85-a91d-3c8d7e2b05f4

The value can be any string up to 255 characters. We recommend a UUID v4 generated before the request is first sent. Store the key alongside the pending request in your system so you can re-use it on retries.

Key generation In Python: import uuid; key = str(uuid.uuid4())
In JavaScript: const key = crypto.randomUUID()

How it works

On the first request with a given key, PGI processes the request and stores the response body and status code, keyed by (Idempotency-Key, partner).
On any subsequent request with the same key and identical request body, PGI returns the cached response immediately without processing the request again.
If you send the same key with a different body, PGI returns 409 Conflict.
After 24 hours the record expires and the key can be reused for a different operation.

Key scope is per partner Idempotency keys are scoped to your API key. Two different partners using the same key value will not collide.

24-hour cache window

PGI stores idempotency records for 24 hours after the original request. After expiry, sending the same key again will be treated as a new request. Expired records are purged nightly.

409 Conflict behavior

If you reuse an active key with a different request body, PGI returns:

{
  "error": "Idempotency-Key reused with different body"
}

This protects you from accidentally retrying the wrong operation with a stale key. Generate a new key if you need to submit a different request.

Example request and response

First request (creates application)

POST /api/v2/applications/ HTTP/1.1
Authorization: Bearer pk_live_abc123def456ghi789jkl012mno345
Content-Type: application/json
Idempotency-Key: 6f7b94e2-1c3a-4f85-a91d-3c8d7e2b05f4

{
  "form_data": {
    "q0_country": "Canada",
    "q15_business_legal_name": "Maple Leaf Technologies Inc.",
    "q42_pgi_limit": "250000",
    ...
  }
}

{
  "application_id": "D4E5F6A1B2C3789012345678EF",
  "status": "received",
  "message": "Application received. Pending quote from underwriters."
}

Retry (identical body, same key) -- replays cached response

POST /api/v2/applications/ HTTP/1.1
Authorization: Bearer pk_live_abc123def456ghi789jkl012mno345
Content-Type: application/json
Idempotency-Key: 6f7b94e2-1c3a-4f85-a91d-3c8d7e2b05f4

{
  "form_data": { ... identical body ... }
}

{
  "application_id": "D4E5F6A1B2C3789012345678EF",
  "status": "received",
  "message": "Application received. Pending quote from underwriters."
}

Same application ID, same status. Only one Application record was created in the database.

Previous Webhooks Next Sandbox Access