26.1.0 - API Changelog | Circularo Developers

At a glance

26.1.0 brings one change that touches every integration and several that touch specific areas.

The one to plan for: the error catalog was rewritten. Every error type identifier is new, and the HTTP status changed on a large number of failure paths. The error body shape is unchanged, but any client that branches on error.type or on specific status codes needs to be reviewed.

Also in this release:

Security improvements — search and aggregation payloads are restricted, and personal data in audit logs is redacted for non-admins.
Template restructure — 18 share-related fields moved into a nested shareSettings object.
KYC identity matching — shares can restrict accepted document types and require the signer's identity data to match.
PDF/A control — new forcePdfA flag; signed PDFs are no longer silently converted (and de-signed).
Document title search — new analyzers make title search diacritics-insensitive with prefix matching; the documentTitle.@en / .@ar sub-fields were removed.
Workflow preparation persistence — documents and drafts can now carry preparationDraft and shareSettings.

1. Breaking changes

1.1 Errors and status codes

Change	What changed	What you need to do
Error `type` vocabulary fully replaced	The old `STATUS:` / `ROUTING:` identifiers (~14 values) are replaced by 12 namespaces: `SYSTEM`, `DATABASE`, `INTEGRATION`, `AUTH`, `SHARE_AUTH`, `VALIDATION`, `RESOURCE`, `DELEGATION`, `DOCUMENT`, `SHARE`, `SIGNATURE`, `SUBSCRIPTION`. Ad-hoc types `ELASTICSEARCH_ERROR`, `ERROR` and `REMOTE_SERVICE_ERROR` are gone. No old identifier survives. The response body shape is unchanged.	Remap every `error.type` check.
HTTP status changed on many failure paths	Main patterns: reference-not-found `404 → 400` (`VALIDATION:REFERENCE_NOT_FOUND`), state conflicts `400 → 409` (`DOCUMENT:STATE_CONFLICT`), insufficient role `400 → 403` (`AUTH:ACCESS_INSUFFICIENT_ROLE`), invalid input `500 → 400` (`VALIDATION:INPUT_INVALID`), and some internal/state failures `4xx → 500`.	Review status-based retry and branching logic. Several "not found" cases are now 400, and several 4xx are now 5xx.
`410` and `422` newly reachable	Both statuses can now be returned. `412 PRE_CONDITION_FAILED` was renamed to `412 PRECONDITION_FAILED`.	Handle 410 and 422.
Error messages sanitized	Database and search-engine derived errors now return generic catalog messages (`Invalid database query`, `Database mapping error`, `Resource modified`, `Unexpected system error`). Status and shape unchanged.	Don't parse error message strings — use `type`.
Bulk response items changed	Each item gains a machine-readable `type`. Per-item statuses changed, e.g. version mismatch `404 → 409` `DOCUMENT:VERSION_CONFLICT`; several `400 → 403` or `500`.	Branch on the per-item `type` instead of the status.
Search backend unavailability returns `503`	Previously reported as `401`.	Treat 503 as retryable, not as "re-login".

Error body

The body shape is unchanged. details is present only for errors that carry structured information (e.g. per-field validation results):

JSON

{
    "status": 400,
    "type": "VALIDATION:REFERENCE_NOT_FOUND",
    "message": "Some of provided groups doesnt exists.",
    "requestId": "9f2c41d7a4b34e5f8c1d0e6a7b25f913",
    "details": null
}

Before / after examples

1 — A referenced entity in the request body does not exist

PUT /documents/{id}/rights with an unknown group id.

	26.0.0	26.1.0
`status`	`404`	`400`
`type`	`STATUS:NOT_FOUND`	`VALIDATION:REFERENCE_NOT_FOUND`

The rule: the resource addressed by the URL still yields 404, but a bad reference inside the payload is now a client input error, so it returns 400. This single pattern accounts for the majority of the changed statuses.

2 — The resource addressed by the URL does not exist

GET /templates/{id} with an unknown id.

	26.0.0	26.1.0
`status`	`404`	`404` — unchanged
`type`	`STATUS:NOT_FOUND`	`RESOURCE:NOT_FOUND`

The status is unchanged, but the type string is different — a client matching on type alone still breaks.

3 — The operation conflicts with the current state

PUT /documents/{version} changing submitted files after the workflow has started.

	26.0.0	26.1.0
`status`	`400`	`409`
`type`	`STATUS:BAD_REQUEST`	`DOCUMENT:STATE_CONFLICT`
`message`	`Submitted files can only be changed before workflow is started.`	unchanged

4 — The caller's role is not sufficient

	26.0.0	26.1.0
`status`	`400` or `403`	`403`
`type`	`STATUS:FORBIDDEN`	`AUTH:ACCESS_INSUFFICIENT_ROLE`

Namespaces let you branch on a whole class of failures — for example, everything under AUTH:* is an authentication or authorization problem, and everything under VALIDATION:* is a client-correctable input problem, regardless of the specific identifier.

1.2 Request and response changes

Change	Endpoint / field	What changed	What you need to do
Template entity restructured	`POST` / `PUT` / `GET /templates`, `POST /templates/search`	18 top-level fields (`password`, `passwordProtection`, `expirationTime`, `kycFactors`, `message`, `remindersStartDays`, …) moved into a nested `shareSettings` object.	Move these under `shareSettings` for both writes and reads. Old-shape requests still return 200 and the settings are silently discarded — this will not show up as an error.
Endpoints removed	`PUT /documents/read`, `PUT /documents/unread`	Removed; read state is now implicit on main-file download/export.	Callers get 404. Documents can no longer be marked unread.
Query field removed	`GET /share/{shareId}/validate`	`markAsRead` removed, along with its side effect.	Remove the parameter.
`customFields` now requires an entitlement	`POST /documents`, document edit/update	Requires the new right `allow_documents_custom_fields` (via ACL `document_custom_fields` or `administration`), otherwise 403. Existing groups are not backfilled by the upgrade.	Have the right granted before upgrading, or `customFields` requests start failing with 403.
Stricter checkbox / radio annotation text	Document sign & annotate, share sign	`annotation_check` text must start with `✓` (U+2713) or U+2800. Grouped `annotation_radio` must start with `◉` (U+25C9) or `◎` (U+25CE); legacy `✓`/U+2800 still accepted.	Free-form or empty text for these subtypes now returns 400.
`aggregations` removed	`POST /{contacts,enums/{name},files,plans,stamps,subscriptions,subscriptions/revisions}/search`	Both the request field and the response property are gone.	Aggregation support on these seven endpoints is no longer available.
`usePdfA` no longer echoes the request	Document/file create, convert, join	With `usePdfA: true` and `forcePdfA` unset, an already-signed PDF is left unconverted and `usePdfA` is persisted as `false` (previously the conversion destroyed the signature).	Don't assume `usePdfA` echoes what you sent; use `forcePdfA` to opt into converting signed files.
Document title sub-fields removed	Document search	`documentTitle.@en` and `documentTitle.@ar` were deleted. Title and full-text fields moved to new analyzers, so title search is now diacritics-insensitive with prefix matching.	Queries targeting `documentTitle.@en` / `.@ar` break. Relevance and match sets change — re-check saved queries and expected result sets.
Enum keyword size limit	Enum record create / update / import	Values above 32 766 bytes are rejected with 400 naming the field (previously an opaque search-engine failure).	Cleaner error; oversized values are no longer accepted.
Registration no longer reports conflicts	`POST /users/register`	An existing active or suspended account returns success with no side effect instead of an error. A not-yet-activated account is refreshed in place (activation tokens issued earlier are invalidated). Per-address rate limiting applies (429 possible) and every response is delayed 0–1500 ms.	Flows keying off "user already exists" / "not activated" errors must change.
Group rights validation	`PUT /documents/{id}/rights`	Unknown or unavailable groups are now rejected with 400 and a generic message ("One or more groups were not found."), instead of 404 listing the group names. Organization-wide grants are blocked when the new `allowAddRightsToOrganization` setting is off.	Status and error shape change; the response no longer tells you which groups failed.
OAuth login resolution changed	`GET /oauth/{strategy_name}` and callback	When a token is supplied but the authenticated profile e-mail differs, the token's user is discarded and a fresh login proceeds unless `connect` or `link` is set (new optional `connect` query field, also implied by `prompt=consent`). A login-CSRF nonce cookie (5 min) must match the stored state, and OAuth `state` is now single-use.	Integrations relying on "use the session token's user" must send `connect=true`. Callbacks opened in a different browser now fail; replays return 400.
SMS reminders can return `402`	`POST /transactions/{id}/remind`, `POST /transactions/{id}/recipients/{id}/remind`	SMS-type reminders now check the subscription's SMS capacity.	Handle 402.

1.3 Security improvements

Change	Scope	What changed	What you need to do
Aggregation and sort clauses restricted	`/search`, `/search/reports`, `/export`, `POST /templates/search`, `POST /users/search`	`top_hits`, `script`, `scripted_metric` and any `*_script` clause are rejected.	Previously accepted payloads now return 400.
Audit-log data redacted and query-restricted	`GET /logs/{id}`, `POST /logs/search`	`connection.ip`, `connection.location`, `notification.recipients`, `notification.response` and `notification.messageId` are stripped from responses and rejected as query/aggregation targets below organization admin. Settings-change details (`generic.changes`) are readable by system admin only. Callers whose role cannot be resolved are treated as below admin.	Non-admin consumers lose those properties and queries. Use an organization-admin account where you need them.
CSV export escaping	CSV exports, reports exporter	Cells starting with `=`, `+`, `-`, `@`, tab, CR or LF are prefixed with `'` (genuine signed numbers excluded). XLSX is unaffected.	Downstream CSV parsers will see a leading apostrophe on those cells.

2. New and additive

Area	What's new
Certificate of Fulfillment	`GET /documents/{id}/audit` gains `cof` (boolean, default `false`); when true a Certificate of Fulfillment is generated (the filename changes accordingly).
KYC identity matching	`POST /share`, `PUT /share`, `PUT /share/delegate` gain `kycDocumentTypes` (`idCard`, `passport`, `driverLicense`, `residencePermit`) and `kycExpectedData` (`dateOfBirth`, `documentNumber`, `nationality`). Responses expose the accepted document types and a PII-free form of the expected data (`*Required` booleans only) — sender PII is never echoed back.
PDF/A control	New `forcePdfA` request field on six document/file endpoints, and a new `pdfASkippedDueToSignature` response field on file upload / file info responses.
Workflow preparation persistence	New optional nullable `preparationDraft` and `shareSettings` on `POST /documents`, `PUT /documents/{version}`, `PUT /documents/edit/{version}`, `POST /share` and drafts; returned on document reads.
Template bulk mapping	New optional `bulkMapping` array (`mapping`, `template`) on template endpoints, for per-template bulk-import column mappings.
Template share notification	`PUT /templates/share` gains `notify` and `message`; new `templateShared` notification type.
New annotation subtypes	`annotation_box_field`, `annotation_metadata`, `annotation_check_group`.
Localized display names	Document definitions gain an optional `displayName` array (`language`, `value`) at definition, field and form-section level.
Group ACLs clearable	`PUT` group `acl` now accepts an empty array or `null`.
Subscription response additions	`lastResetDate`, `nextResetDate` and `usage.kyc` added. `GET /stripe/products` gains `transactionsPerItem`.
New settings flags	`allowShareWithExternalUsers` and `allowAddRightsToOrganization` (both default `true`), `signatureEnvelope`, and `registration.oAuthHidden`.
E-mail sub-addressing	E-mail and username validators accept a single `+` tag per RFC 5233 (local part only, non-empty detail, no leading `+`). `+` addresses are now valid platform-wide.
Signature field `zIndex`	The `min(0)` restriction was removed, so negative stacking values are accepted.

3. Behaviour changes worth knowing

Area	What changed	Why it matters
Read state is now implicit	Downloading a main file, exporting to PDF or exporting a file archive marks the document as read for the caller (including share `viewed` state, the share-viewed notification and history). Share file retrieval does the same.	Share owners now receive "viewed" notifications triggered by file retrieval rather than by an explicit call.
Annotation substitution	`{{{ path }}}` now substitutes globally (multiple placeholders per annotation) and resolves nested paths; dates render in the signer's format; unresolved paths leave the literal `{{{...}}}` in the output. Text for subtypes `FULL_NAME`, `COMPANY`, `PHONE`, `MAIL` and `ROLE` is unconditionally overwritten from the signer's profile.	Client-supplied text for those five subtypes is discarded, and renders blank where the profile value is empty.
KYC result verification stricter	Provider approval alone is no longer sufficient — document type and expected identity data are checked, returning `SHARE_AUTH:VERIFICATION_FAILED` with `errors: [DOCUMENT_TYPE_MISMATCH \\| DOCUMENT_FIELDS_MISMATCH \\| EXPECTED_DATA_MISSING \\| EXPECTED_DATA_MISMATCH]`, no password issued and attempts not reset. KYC result tokens are now single-use.	Handle the new error codes, and don't re-query a finished result token.
`verifiedWith.value` for KYC	Now derived from the KYC verification provider, and becomes `provider-sessionId` when a session id exists.	Consumers parsing this as a bare provider name receive a concatenated value.
`POST /share` restrictions	A new action share is rejected when the workflow's first step already carries a share state (409 `DOCUMENT:STATE_CONFLICT`). Share-based signing with a `shareId` that is not in `waitingFor` returns 403 `AUTH:ACCESS_DENIED`.	Sharing after signing, and several previously permitted share/sign combinations, now fail.
Share signing metering	Share-initiated signatures no longer consume the sharer's signing-transaction quota.	Billing-visible metering change.
Share expiration notifications	The fixed 72-hour window is replaced by a tiered rule: shares valid for 3 days or more are notified within 24 h, shorter ones within 2 h. Already-expired shares are excluded and the remaining-hours value is accurate.	Different notification timing.
Rejection notifies other recipients	On final rejection, active VIEW shares in the same share group receive a new `shareRejectedOthers` notification. All existing users are opted in.	Participants learn why a workflow stopped.
Reports	Pending recipients now report `date: null` (`dateOfReceivingTheAction` still carries the date), waiting/unused rows are sorted, and final-state detection was fixed so previously blank rows are populated.	Blank date cells for pending rows and different ordering.
Clone clears signature configuration	`POST /documents/{id}/clone` sets `signatureProvider` and `signatureType` to `null`.	Clones use the cloner's resolved provider.
Session list capped	`POST /users/search` `activeSessions` returns at most the 100 most recently used sessions per user.	Much cheaper searches; clients counting sessions may undercount for heavy users.
Download and stream errors	Storage failures now propagate as real 5xx errors instead of a misleading 404 or a truncated/hanging download; client aborts destroy the source stream. Missing records still return 404.	Failures are detectable instead of silent.
Rate limit on e-mail-triggering endpoints	`PUT /users/resetPassword` and activation resend apply a per-recipient limit (3 requests, refilling roughly one per 20 minutes) with `Retry-After`.	New 429 responses for repeated requests to the same address.
External sharing gate	The `allow_external_users` right was removed; external sharing is now controlled by the setting `allowShareWithExternalUsers`, which defaults to `true`.	Tenants that deliberately withheld the right gain external sharing after the upgrade unless the setting is turned off.
Signing and preparation fixes	Timestamp components no longer trip the non-image-signature check; annotate-only merged sub-files are certified and marked signed; the signing certificate is applied on all preparation paths; sign-data page remapping on merged documents was fixed; out-of-sync merged files now fail with a clear 409.	Fewer spurious failures and correct placement on merged documents.