Compatibility contract
The rules, BC-1 to BC-22 in plain words, that keep a working integration recording while laws change, packs are added and API versions move.
Most teams build their integration once, often with an AI coding tool, and may not touch it again for years. The law will change in that time, and you will add and remove states. The contract on this page keeps a working integration recording through all of it.
The short version: a guidance update does not break your existing recording integration. You may still need to change your flow to meet a new legal requirement, and you decide when anything that can block takes effect.
Three version axes
| Axis | What it versions | How it moves | Who decides when it applies |
|---|---|---|---|
| API version | Endpoints, request and response shapes, error codes, webhook payloads | Rarely. Dated versions under /v1. |
You, by pinning |
| SDK version | The server package and browser SDK interfaces | Semantic versions | You, by upgrading |
| Guidance release | Packs, rule parts, obligations, recommendations, strings, notices | Often | Esign Comply for content that cannot block. You for anything that can block. |
The current API version is 2026-11-21. Every response carries it in the Esign-Comply-Version header. Each API key is pinned to the version that was current when the key was created. Send the header on a request to override the pin for that request:
curl https://esigncomply.com/v1/usage \
-H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
-H "Esign-Comply-Version: 2026-11-21"
An unknown version returns 400 invalid_request with param: "Esign-Comply-Version" and the list of supported versions.
The rules
API and SDK versions
| Rule | In plain words |
|---|---|
| BC-1 Independence | A guidance release never changes an endpoint, a request or response schema, an authentication rule, the meaning of an error code, a webhook payload shape or an SDK method. An API version never changes which rules apply. |
| BC-2 API versions | The path stays /v1. Breaking changes ship only under a new dated Esign-Comply-Version. A dated version is supported for at least 24 months after its successor is released, with at least 12 months' notice before removal. |
| BC-3 Additive changes | These may ship at any time without a new version: new endpoints, new optional request fields, new response fields, new values in any enumeration, new webhook event types, new entries in warnings[] and advisories[], new rule IDs, new packs, new supplement types, new fact keys. Ignore fields you do not know and tolerate enumeration values you do not know. SDK types expose enumerations as open strings. |
| BC-4 Fixed within a version | The meaning and type of existing fields, which request fields are required, the error code returned for a given condition, default values, the names in required_steps, and the format of IDs (opaque strings of at most 64 characters). |
| BC-16 Webhooks | An endpoint is pinned to the API version in force when it was created. New event types are sent only to endpoints that subscribe to them or to all events. Handlers ignore event types they do not know. |
| BC-17 SDKs | Server and browser SDKs follow semantic versioning. Each major version is supported for 24 months after its successor. The browser SDK is served from a versioned URL and is never changed in place except for a security fix. |
| BC-18 Deprecation | A feature to be removed is announced in the changelog and by email, marked with Deprecation and Sunset response headers, and listed in the dashboard with the keys still using it. |
For error handling this means: branch on error.type first, and treat an unknown error.code as its type. The type list is closed within a version. New codes may appear for new conditions. See Errors.
Rule changes and adoption
| Rule | In plain words |
|---|---|
| BC-5 Rule changes do not break recording | Each profile has a baseline: the pack versions whose record conditions it has adopted. Only baseline record conditions can refuse to seal, add a required step or require a fact. A record condition that arrives later runs in the advise state: it is evaluated, its result is stored and returned in advisories[], and it never returns an error and never adds to required_steps. |
| BC-6 Adoption | You move pending record conditions to enforce by adopting them, in the dashboard or with POST /v1/profiles/{id}/adopt. Adoption creates a new profile version. POST /v1/profiles/{id}/rollback returns to the previous baseline for 90 days. Esign Comply never adopts on your behalf. |
| BC-7 Test mode shows the future | Test mode always evaluates the latest release with every condition enforced, so you see what adoption would require before it reaches live traffic. POST /v1/jurisdictions/resolve accepts baseline: "current" or "latest" for the same comparison. |
| BC-8 Changes that can only help apply at once | A relaxed or retired record condition stops blocking for every profile at its effective_at. Obligations, recommendations, notices, evidence wording and fixed-string text update for every profile at effective_at, because none of them can stop a call. A changed fixed string is served through required_strings[]. The presence check for the new text stays in advise until adopted, and the earlier text keeps passing meanwhile. |
| BC-9 Adding a state | Enabling a pack on a profile with live traffic needs no code change to keep recording. The pack's obligations, recommendations and notices apply at once. Its record conditions start in advise. State-specific steps appear in required_steps only after adoption. |
| BC-10 Removing a state | Disabling a pack never causes an error. A session whose signer is in that state, or which names the pack explicitly, proceeds under the remaining packs with the warning jurisdiction_not_enabled:<code>, and the record says the pack was not applied. A profile may opt in to strict behavior with strict_jurisdictions: true, which restores the 422 jurisdiction_not_enabled error. |
| BC-12 Facts | A rule in advise that lacks a fact adds fact_missing:<key> and does not fire. 422 jurisdiction_fact_required is returned only for an adopted Block condition. A fact key is never renamed. A replaced key keeps working as an alias. |
How adoption works in practice is in Guidance and adoption.
Tolerant input and stable names
| Rule | In plain words |
|---|---|
| BC-11 Tolerant input | Unknown request fields are ignored and reported as unknown_field:<path> in warnings[]. Unknown keys in context.facts are stored as sent with the warning fact_unrecognized:<key>. Unknown supplement types are stored. None of these is an error. Structural errors still return 400: malformed JSON, a wrong type for a known field, a missing required field. |
| BC-13 Stable identifiers | Rule IDs, pack codes, step names, string slots, supplement types and notice IDs are never reused or renumbered. A retired rule stays in the catalogue with status: "retired" and its last text, so old records and old prompts still resolve. |
| BC-21 Catalogue reads | Read packs, supplement types and fact keys from the catalogue and do not hard-code them. Catalogue responses carry ETag and a five-minute cache lifetime, so a guidance release needs no client change. |
Records and prompts
| Rule | In plain words |
|---|---|
| BC-14 Records are fixed | A sealed record pins the API version, the profile version, the pack versions, the guidance release, and each condition's state (enforce or advise) and result. Nothing published later changes it. |
| BC-15 Prompts | Code built from any prompt Esign Comply has issued keeps working against the API version it was written for. Prompt IDs resolve permanently. Changes are offered as update prompts, never as a required rebuild. Reports sent through the earlier annotation types notice.sent and cancellation.requested are still accepted and stored as supplements. |
Exceptions, proof and contracts
| Rule | In plain words |
|---|---|
| BC-19 Exceptions | Esign Comply may act sooner than BC-2 and BC-5 only to fix a security vulnerability, to follow a court or regulator order, or to stop abuse. It tells affected customers directly and records the event in the changelog. |
| BC-20 Proof | Request and response fixtures from every released API version and every SDK major version are replayed in continuous integration against each application deployment and each guidance release. A guidance release that changes the HTTP status, error code or response schema of any fixture for an unchanged baseline is not published. |
| BC-22 Enterprise | A contract may pin pack versions and a guidance release for an agreed period and set change windows for adoption. |
What you have to do in each case
| Event | Does recording keep working with no code change? | What you receive | What you may choose to do |
|---|---|---|---|
| A state changes a law that Esign Comply covers | Yes | A notice, an update prompt, and advisories on new sessions if a new record condition is not met | Follow the obligation or recommendation. Adopt the new record condition. |
| Esign Comply adds a pack for a new state | Yes | A notice in the public feed and to watchers | Enable the pack |
| You enable another state | Yes | The pack's obligations and recommendations at once. Its record conditions in advise. | Apply the update prompt, test, adopt |
| You disable a state | Yes | The warning jurisdiction_not_enabled:<code> on sessions that would have used it |
Nothing, or set strict behavior |
| A rule is relaxed or retired | Yes | A notice | Nothing |
| A new API version is released | Yes, on the pinned version | A changelog entry | Upgrade when convenient, within the support period |
| You send a field, fact or supplement type Esign Comply does not know | Yes | A warning naming it | Nothing |
"Recording keeps working" is a statement about the API. It is not a statement that your flow meets a new legal requirement. Read each notice: it says separately what changes in Esign Comply's record, what changes in your obligations, and what Esign Comply recommends.
Writing a client that stays compatible
- Read
required_stepsandrequired_stringsfrom each session. Do not hard-code steps or state rules. - Read the pack catalogue, supplement types and fact keys at run time.
- Ignore response fields you do not know. Treat every enumeration as an open string.
- Treat unknown entries in
warnings[]andadvisories[]as information. Log them. - Branch on
error.type, then on the codes you know. - In webhook handlers, ignore event types you do not recognize and return
200. - Do not parse IDs. They are opaque strings of at most 64 characters.
- Send an
Idempotency-Keyon everyPOSTthat creates something, and retry5xxresponses with the same key.
Related
- API conventions for versioning headers, idempotency and the error envelope.
- Guidance and adoption for notices, update prompts, adopt and rollback.
- Jurisdiction packs for selection and warnings.