Idempotency

Overview

This API implements idempotency for specific endpoints to prevent duplicate request processing. Idempotency ensures that making the same request multiple times has the same effect as making it once, which is crucial for operations like creating entities or sending invitations.

How It Works

Aspect	Description
Cached response	The first response is stored and replayed for repeats of the same request
TTL	Cached responses expire after 1 hour (3600 seconds)
UUID Validation	Idempotency keys must be valid UUIDs
Automatic Response	Returns the cached response for a duplicate request without re-processing

What a key is scoped to

A cached response is keyed on your organization, the HTTP method, the route including its version segment, and your key — not on the key alone. Two consequences worth knowing:

The same UUID sent to two different endpoints does not collide. Reusing a key across operations is still bad practice, but it will not replay the wrong response body.
A key is private to your organization. Two customers sending the same UUID never see each other’s response.

Supported Endpoints

Every endpoint that accepts a key advertises an idempotency-key parameter on its reference page. The current set: Agency (/v2/downstream/*) — every write:

POST /v2/downstream/entities
POST /v2/downstream/producers
POST /v2/downstream/producers/{producerId}/entities
POST /v2/downstream/contacts
POST /v2/downstream/compliance-configs
POST /v2/downstream/corporate-registration-filings
POST /v2/downstream/documents

Carrier (/v1/* and /v2/upstream/*):

POST /v1/downstream-entity-associations/add and POST /v2/upstream/downstream-entity-associations/add
POST /v1/downstream-entity-associations/invite and POST /v2/upstream/downstream-entity-associations/invite
POST /v1/policies and POST /v2/upstream/policies
POST /v1/policies/upload and POST /v2/upstream/policies/upload
POST /v1/policies/{policyId}/transactions and POST /v2/upstream/policies/{policyId}/transactions

No other carrier write on v2 supports idempotency keys. On v1 the two deprecated dangerously- association endpoints also accept one; both are absent from v2. Sending one to an endpoint that does not accept it is harmless — the header is ignored — but the request is not protected against a retry.

Headers

Include one of these headers in your requests to enable idempotency:

Header Name	Required	Format	Example
`idempotency-key`	No	Valid UUID v4	`550e8400-e29b-41d4-a716-446655440000`
`x-idempotency-key`	No	Valid UUID v4	`550e8400-e29b-41d4-a716-446655440000`

Usage Guidelines

When to Use Idempotency Keys

Creating new entities or resources

Sending invitations or notifications

Any operation that should not be duplicated

Network retry scenarios

User interface double-click prevention

Behavior

Scenario	Result
First Request	Processes normally and caches the response
Duplicate Requests	Returns the cached response immediately (within 1 hour)
After TTL Expiry	Processes as a new request after 1 hour

Error Handling

Error	Response
Invalid UUID Format	`400 Bad Request` with message: “Invalid idempotency key format. The idempotency-key must be a valid UUID”
Missing Key	Request processes normally without idempotency

Example Usage

Request with Idempotency Key

POST /v2/downstream/contacts
Content-Type: application/json
idempotency-key: 550e8400-e29b-41d4-a716-446655440000

{
  "firstName": "Jon",
  "lastName": "Doe",
  "email": "example@test.com"
}

The body is not part of the key. Sending the same key with a different body within the hour replays the first response and does not process the second request. Use a fresh key for each distinct operation and reuse one only when retrying the identical request.

Generating UUIDs

Use any UUID v4 generator:

const uuid = crypto.randomUUID();

import uuid
key = uuid.uuid4()

{{$guid}}

Best Practices

Generate Unique Keys

Use a fresh UUID for each logical operation

Client-Side Generation

Generate UUIDs on the client side before making requests

Retry Logic

Use the same idempotency key when retrying failed requests

Key Management

Don’t reuse keys across different operations

Testing

Include both scenarios in your tests:

Requests with idempotency keys
Requests without idempotency keys

Postman Variables

You can use Postman’s built-in variable for testing:

{{$guid}}

This generates a new UUID for each request, or create a collection variable for consistent testing.

This implementation ensures reliable API operations and prevents duplicate processing in distributed systems and unreliable network conditions.

Start Here

API Conventions

Tools & Integrations

Support

Overview

How It Works

What a key is scoped to

Supported Endpoints

Headers

Usage Guidelines

When to Use Idempotency Keys

Behavior

Error Handling

Example Usage

Request with Idempotency Key

Generating UUIDs

Best Practices

Generate Unique Keys

Client-Side Generation

Retry Logic

Key Management

Testing

Postman Variables

​Overview

​How It Works

​What a key is scoped to

​Supported Endpoints

​Headers

​Usage Guidelines

​When to Use Idempotency Keys

​Behavior

​Error Handling

​Example Usage

​Request with Idempotency Key

​Generating UUIDs

​Best Practices

Generate Unique Keys

Client-Side Generation

Retry Logic

Key Management

​Testing

​Postman Variables

Overview

How It Works

What a key is scoped to

Supported Endpoints

Headers

Usage Guidelines

When to Use Idempotency Keys

Behavior

Error Handling

Example Usage

Request with Idempotency Key

Generating UUIDs

Best Practices

Testing

Postman Variables