Versioning

Versioning scheme#

SignCare uses path-based versioning:

/api/v1/pan/verify
/api/v2/bank/verify        ← hypothetical v2 example

The version segment lives in the path right after /api/. You pin to a specific version by including it in your request URL.

Current versions#

Most Core endpoints are on v1. WealthSync uses v2 broadly with some newer endpoints on v3.

What counts as a breaking change#

Breaking changes get a new version. The following are considered breaking:

• Removing a field from a response
• Changing the type or meaning of an existing field
• Renaming a field
• Making a previously optional request field required
• Changing authentication requirements
• Changing the shape of error responses in incompatible ways

What's NOT a breaking change#

These happen on existing versions without bumping:

• Adding a new field to a response (always expect unknown fields — don't strict-validate)
• Adding a new optional field to requests
• Adding a new endpoint under the same version
• Adding new enum values to an existing field (see below — design defensively)
• Performance improvements, bug fixes that don't change contracts

Good:

const status = response.status;
if (status === 'VALID') { /* ... */ }
else if (status === 'INVALID') { /* ... */ }
else { /* unknown — treat as uncategorized */ }

Bad:

// A new enum value in a future release will throw here.
assert(['VALID', 'INVALID'].includes(status));

Deprecation process#

When we plan to remove or change something, we:

1. Announce via email to your registered technical contact.
2. Mark the endpoint as deprecated: true in the OpenAPI spec (visible in the docs).
3. Provide a migration guide pointing at the replacement endpoint.
4. Return a Sunset HTTP header on deprecated endpoints indicating the removal date:

   Sunset: Wed, 01 Oct 2026 00:00:00 GMT
   Deprecation: true
   Link: </core/some-endpoint>; rel="successor-version"

   Copy
5. Keep the deprecated endpoint live for 12 months minimum after announcement.

Migration guides#

When an endpoint is deprecated, its documentation page links to the successor with a diff-style migration guide showing:

• Field-by-field request changes
• Field-by-field response changes
• Any new capabilities in the successor
• A sample curl for the new endpoint

Staying informed#

To get advance notice of deprecations and new features:

• Ensure your account's technical contact email is current (update via portal or support).
• Subscribe to the SignCare changelog (ask your account manager for access).
• Follow our release notes in the SignCare portal.

Checking your version usage#

We track which API versions each API Key calls. Your account manager can share a report showing:

• Version distribution across your traffic
• Any deprecated endpoints you're still using
• Recommended migration targets

Ask for a "version audit" before any major deprecation deadline.