> ## Documentation Index
> Fetch the complete documentation index at: https://developers.circle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CPN API changes and compatibility

> Additive and breaking changes as CPN adds fields, values, events, and capabilities, and how to keep your integration compatible.

The Circle Payments Network (CPN) API evolves as Circle adds corridors, payment
methods, blockchains, compliance rules, and failure conditions. Circle
classifies API changes as backward compatible or breaking. Most
backward-compatible changes are additive: they introduce a resource, field,
value, or capability while preserving documented behavior for existing valid
requests. An Originating Financial Institution (OFI) integration must tolerate
these changes so that new response data or event types don't cause client
failures.

## Backward-compatible and breaking changes

Circle expects OFI integrations to accept the changes in the backward-compatible
column without failing or requiring an immediate update. Breaking changes alter
or remove part of the documented contract and may require integration work.

| Area                    | Backward-compatible change                                                          | Breaking change                                                                                                   |
| ----------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Endpoints and resources | Add an endpoint or resource                                                         | Remove or rename an endpoint or resource                                                                          |
| Requests                | Add an optional parameter when omitting it preserves existing behavior              | Add a required parameter, make an optional parameter required, or change the behavior when a parameter is omitted |
| Responses               | Add a property                                                                      | Remove or rename a property, change its data type, or make an always-present property conditionally omitted       |
| Enum values             | Add a value for a new condition or capability                                       | Remove a value or change what an existing value means                                                             |
| Errors                  | Add an error code for a new failure condition or revise human-readable message text | Change the HTTP status or error code for an existing condition                                                    |
| Webhooks                | Add an event type or a field to an existing payload                                 | Stop emitting a documented event type, remove a field, or change an existing event's meaning                      |
| Validation              | Relax validation so that a previously rejected request is accepted                  | Tighten validation so that a previously accepted request is rejected                                              |

Use the [release notes](/release-notes) and relevant migration guides to
identify changes that require integration work. When a migration includes a
deadline, complete the required work in the communicated timeline.

## Build a tolerant integration

Backward-compatible changes don't require your integration to adopt a new
capability. They do require clients to accept response and event data that they
don't use yet.

### Optional request parameters

A new request parameter is backward compatible only when it's optional and
omitting it preserves existing behavior. Existing requests can retain their
current shape until the integration needs the capability controlled by the new
parameter.

### New response fields

Parse the response fields your integration uses and ignore unfamiliar
properties. Strict deserialization that rejects extra properties can turn an
otherwise successful API response into a client-side failure.

### General enum values

Send only documented enum values in requests. For responses, preserve any
unfamiliar raw value and map it to a neutral fallback instead of rejecting the
entire response. Storage and downstream processing must also accept unfamiliar
values.

Don't infer the meaning of an unfamiliar value or use it to trigger an
irreversible action. Add first-class handling after you confirm the value's
documented meaning.

### Lifecycle statuses

An unfamiliar lifecycle status needs a more conservative fallback than a general
enum value. Keep the resource in its current local state, preserve the raw
status, and route the record for review. Don't interpret an unfamiliar status as
success or failure, and don't release funds or take another irreversible action
based on it.

### Resource and reference IDs

The CPN OpenAPI schemas define system-generated resource IDs as UUID-formatted
strings and reference IDs as strings. Treat each identifier according to its
documented schema and as an opaque value: don't derive business meaning from its
shape or impose an undocumented length limit.

### Error codes

Match errors by their machine-readable code, not their human-readable message. A
new code is backward compatible when it represents a new failure condition;
changing the HTTP status or code for an existing condition is breaking. Preserve
and surface an unfamiliar code so that you can add specific handling without
losing the original failure detail.

### Webhook events

After verifying a webhook signature, record or surface an unsupported event type
for follow-up, then acknowledge it with a `2xx` response. This prevents retries
that can't succeed while preserving the event for later handling. Don't process
the event as a known type. Continue to reject webhooks when
[signature verification](/api-reference/verify-webhook-signatures) fails.