API versioning

RCM uses URL-based major versioning. Each public endpoint is prefixed with /v1/, /v2/, or /v3/. Within a major version, additive changes (new optional fields, new endpoints, new event types) are routine and don't bump the version. Breaking changes are bumped to a new major.

What counts as additive (won't break you)

• A new endpoint at a new path.
• A new optional field in a request body.
• A new field in a response body. Your client must ignore unknown fields — see Best practices below.
• A new optional query parameter.
• A new webhook event type. Your receiver must not 5xx on event types it doesn't recognise — return 2xx and move on.
• A new value in an enum-like response field (status codes, support_file_code catalogue entries). Treat unknown values as "I don't know, log it" rather than throwing.

What counts as breaking (will bump the version)

• Removing or renaming an endpoint, field, or parameter.
• Changing a field's type (string → int, etc.).
• Changing the meaning of an existing enum value.
• Tightening a previously permissive validation rule in a way that rejects requests that used to succeed.
• Restructuring a response (moving a field from top-level into a nested object).

When we ship a breaking change, the old endpoint and the new endpoint coexist for at least 6 months before the old one is removed. We never remove an endpoint without a Sunset header period.

Deprecation signalling

Deprecated endpoints emit these HTTP response headers:

Header	Example	Meaning
Deprecation	true	This endpoint is on the way out.
Sunset	Tue, 01 Sep 2026 00:00:00 GMT	Date after which the endpoint will be removed (RFC 8594).
Link	</v3/accounts/origin-events/change-of-payer>; rel="successor-version"	Where to migrate to.

Your client should:

1. Log a warning when you see Deprecation: true in a response. Include the endpoint and the Sunset date.
2. Plan a migration to the URL in the Link header well before the Sunset date.
3. Don't break on the headers being present — they're informational, not errors.

Currently deprecated endpoints

Old endpoint	Status	Migrate to	Sunset
PUT /v1/accounts/origin-events/{originEventId}/agreement-codes/{agreementCode}	Deprecated	PUT /v3/accounts/origin-events/change-of-payer	1 Sep 2026
PUT /v2/accounts/origin-events/{originEventId}/agreement-codes/{agreementCode}	Deprecated	PUT /v3/accounts/origin-events/change-of-payer	1 Sep 2026

This list will grow over time. We'll never remove an endpoint without 6+ months of advance notice.

Best practices for your client

• Ignore unknown fields in JSON responses. Parsing libraries default to this in most languages; if yours doesn't, configure it explicitly (@JsonIgnoreProperties(ignoreUnknown = true) in Jackson, extra="ignore" in Pydantic, etc.).
• Handle unknown enum values by treating them as "other" rather than throwing. We may add new status codes, event types, document types, or reason codes without warning.
• Pin your client to a specific major version at the URL level — never strip the /v1/ prefix or rely on URL rewriting that bumps versions automatically.
• Subscribe to changelog updates in the documentation site to catch deprecations before they hit production.

How we communicate changes

• The changelog page of this site is updated for every release.
• Deprecation events also produce email notifications to the technical contacts registered for each client_id. Make sure your team's email is current with OSIGU support.