Compatibility & deprecation policy
This policy defines which changes SignedOff can make inside /api/v1, what integrators must tolerate, and how we announce changes that require client work.
Effective July 22, 2026 · Last updated July 22, 2026
The short version
Existing documented v1 requests should keep working. We may add optional fields, endpoints, parameters, headers, and enum values. We will not remove or rename fields, make new inputs required, or change documented meanings without a deprecation process or a new major API version.
Versioning scope
The major API version is carried in the URL. This policy applies to REST endpoints under /api/v1 and to v1 webhook payloads.
A future incompatible API surface will normally use a new major path such as /api/v2. OpenAPI info.version identifies the published specification release; it does not replace the URL major-version contract.
API keys are not version-specific unless a future migration guide explicitly says otherwise.
Compatible changes within v1
| Change | Client requirement |
|---|---|
| New endpoints or operations | No action unless you choose to adopt them. |
| New optional request parameters or body fields | Continue omitting fields you do not use. |
| New optional response fields or headers | Ignore unknown fields and headers. |
| New enum values | Use an unknown/default branch; do not assume the documented set is permanently exhaustive. |
| Broader limits, coverage, or accepted input formats | No action unless the changelog calls out changed semantics. |
| New webhook event types | Only process subscribed events, and retain an unknown-event fallback. |
Fields, enums, nullability, and omission
- A response field documented as required and non-null will remain present and non-null within v1.
- A field documented as nullable may contain either a value or explicit
null. - An optional field may be omitted. If it is also nullable, clients must accept either omission or explicit
null. - New optional response fields may appear at any time. Clients must ignore fields they do not recognize.
- Enum additions are compatible v1 changes and will be listed in the changelog. Clients must preserve or safely handle unknown string values instead of failing exhaustive parsing.
- Do not send undocumented request fields. Unknown request input is not covered by compatibility guarantees.
Changes treated as breaking
These changes require a deprecation process or a new major version:
- Removing or renaming an endpoint, parameter, response field, enum value, webhook field, or event type.
- Making an optional request input required or narrowing an accepted input type.
- Making a required non-null response field nullable or omittable.
- Changing a field's type, units, documented meaning, authentication requirement, or billing behavior.
- Changing documented ordering, pagination, idempotency, or delivery guarantees.
Deprecation process
- We publish the change and migration guidance in the API changelog.
- Where an HTTP operation is affected, responses will carry a
Deprecationheader, a datedSunsetheader, and a deprecationLinkwhen technically applicable. - Generally available features receive at least 90 calendar days between public deprecation notice and removal or incompatible behavior.
We may accelerate a change when required to address an active security issue, legal obligation, abuse, or an upstream government portal change outside SignedOff's control. We will still publish the reason and migration path as soon as practical.
Beta and preview features
A capability explicitly labeled beta, preview, or experimental is excluded from the 90-day guarantee until it becomes generally available. Preview changes will still be documented in the changelog, and SignedOff will avoid unnecessary churn. Billing and security changes are never silently exempted by a preview label.
Integration checklist
Ignore unknown response fields, use fallback branches for enums and webhook events, treat cursors as opaque, and rely only on ordering guarantees stated in the endpoint documentation.