> For the complete documentation index, see [llms.txt](https://developers.docstudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.docstudio.com/guides/api-versioning.md).

# API versioning

This document explains how to use DocStudio API versions safely and maintain compatible integrations.

DocStudio API endpoints can include a version in the request URL. Many platform endpoints use the `/api/v1` path. The version separates API contracts and helps maintain integrations when behavior changes.

Use this guidance before changing templates, payloads, or production integration logic. This page does not define a release policy. Check the API reference and **Swagger UI** for endpoint behavior, parameters, schemas, and available operations.

### Use the current contract as the source of truth

Use [Swagger UI](https://api.docstudio.com/swagger-ui/index.html) for the current endpoint contract and documented routes.

Verify request formats, headers, response schemas, and supported values before each release. Do not infer these details from another endpoint or an older integration.

### API version in endpoint URLs

Many DocStudio API endpoints use `/api/v1` in the request path. Check the documented path before implementing each request.

```http
POST /api/v1/envelope/send
GET /api/v1/mailbox/{mailboxUuid}
POST /api/v1/template
POST /api/v1/envelope/attachment
```

The `v1` segment identifies the API version. Use the path documented in the API reference or **Swagger UI**. Do not remove or change the version unless your environment documents another version.

Not every endpoint follows the same path pattern. The authorization endpoint uses `/api/login`, not `/api/v1/login`.

```http
POST /api/login
```

Check each endpoint URL before implementation. Do not infer a URL from another endpoint or its version.

### Use documented endpoints only

Use public endpoints from the API reference or **Swagger UI**. Do not use internal routes, browser requests from **DevTools**, temporary backend endpoints, or undocumented test URLs.

Undocumented routes can change without warning or require different permissions. They can also return unstable responses or disappear after platform updates.

When you add a new API call to an integration, save these details in your integration documentation:

{% columns %}
{% column %}

* endpoint URL
* HTTP method
* required headers
* path parameters
* query parameters
  {% endcolumn %}

{% column %}

* request body format
* expected response fields
* expected status codes
* required mailbox or account context
  {% endcolumn %}
  {% endcolumns %}

This record makes future reviews faster after product or API changes. Keep it with the integration configuration and release notes.

### Request compatibility

Request compatibility means sending the format required by an endpoint. Send JSON when required. Build valid XML before passing it through the JSON `data` field.

Upload binary files in the required format. Do not wrap them in JSON unless the endpoint requires it. Small format changes can break rigid integrations.

The upload response returns `attachmentId`. Pass this value as `attachmentUuid` in envelope XML. Use the same mailbox context for file upload and the following envelope request.

Use [Uploading files and external documents](/guides/files-and-external-documents.md) for the upload flow and file-field rules.

Before changing request logic, check:

{% columns %}
{% column %}

* endpoint URL
* HTTP method
* required headers
* path and query parameters
  {% endcolumn %}

{% column %}

* request body format
* required XML attributes
* accepted enum values
* mailbox or account context
  {% endcolumn %}
  {% endcolumns %}

### Response compatibility

Response compatibility means safely reading the data your integration needs. Read fields required for the flow. Ignore unrelated fields unless they affect business logic.

Avoid parsing that fails only because a response contains an additional field. Test the integration after API or template changes.

Use stable identifiers and business-relevant values. Save the envelope UUID after sending an envelope. Use it for status checks, downloads, audit trails, and follow-up actions.

```json
{
  "uuid": "89499ba2-287d-404c-87b0-342dc5b01b6a"
}
```

Store `uuid` because it identifies the created envelope. Use it for later requests instead of an informational response field.

### Distinguish response fields from envelope metadata

Some responses include object fields such as creation dates, archive state, or template update timestamps. Use these fields for display, debugging, or synchronization when needed.

Do not treat these object fields as core business logic without a clear requirement. The reusable values for envelope requests are the template UUID, template version, role IDs, document IDs, and field names.

Use these template values in envelope requests:

* `uuid` for the template UUID
* `version` for the template version
* role IDs, document IDs, and field names from the template

Reuse the template identifiers and field structure for template-based envelope requests. Do not substitute response fields for required template identifiers.

Envelope metadata is different from object fields returned in an API response. Use envelope metadata for external references and automation data. Follow [Metadata](/guides/envelope-metadata.md) for its format, limits, and security rules.

### Distinguish API and template versions

API and template versions are different concepts. The API version is part of an endpoint path, such as `/api/v1`.

The template version identifies a template structure. Keep both versions explicit in integration configuration.

```xml
<envelope templateUuid="{templateUuid}" templateVersion="{templateVersion}">
  ...
</envelope>
```

The template version validates envelope data against the selected template. Keep role IDs, document IDs, field names, field groups, and validation rules aligned with that version.

Refresh this identifier set after each template update. Do not combine values from different template versions.

### Treat template changes as compatibility changes

Template-based integrations depend on template structure. A template update can break an envelope flow even when the endpoint stays unchanged.

A template change can affect:

{% columns %}
{% column %}

* template version
* role IDs, order, and types
* document IDs
* field names and types
* required fields
  {% endcolumn %}

{% column %}

* field validation rules
* dynamic table structure
* dictionary configuration
* signature field configuration
* external document configuration
  {% endcolumn %}
  {% endcolumns %}

Review the integration before using an updated template in production. Verify its template UUID and template version.

Verify role IDs, document IDs, field names, and field values. Keep every identifier aligned with the selected template version.

### Update templates safely

Update templates through a controlled flow. Test each change before production use.

{% stepper %}
{% step %}

#### Test the template structure

Update the template in a test environment or mailbox. Read the updated structure and compare its reusable identifiers.

Check required fields, field names, document IDs, and role IDs. Update the integration configuration where needed.
{% endstep %}

{% step %}

#### Test the envelope flow

Send a test envelope from the updated template. Check field values and recipient role assignments.

Complete the flow when required. Check statuses, downloads, audit trails, metadata, and callbacks used by the integration.
{% endstep %}
{% endstepper %}

Do not update a production template without testing it. Template changes often cause request validation errors and incorrect field mapping.

### Identify potentially compatible changes

Some changes are usually easier for integrations to handle because they do not require existing requests to change.

Examples of potentially backward-compatible changes:

* adding an optional response field or request parameter
* adding an optional filter or metadata key
* adding a new endpoint without changing existing endpoints
* updating examples without changing endpoint behavior

Test every affected flow. Compatibility depends on response parsing, schema validation, and unknown-value handling.

Do not treat a change as safe without a completed test flow. Integration behavior determines the actual compatibility impact.

### Identify potentially breaking changes

A breaking change can cause an integration to fail, send incorrect data, lose access, or process a response incorrectly. Its impact depends on the requests and automation used by the integration.

#### API contract changes

Check these changes before updating API client code:

{% columns %}
{% column %}

* removing an endpoint
* changing an endpoint URL or HTTP method
* changing required fields or headers
* changing authentication or permissions
* changing accepted enum values or response fields
  {% endcolumn %}

{% column %}

* changing request body or XML structure
* changing field value formats
* changing file upload behavior
* changing pagination behavior
  {% endcolumn %}
  {% endcolumns %}

#### Template structure changes

Check these changes before sending an envelope from an updated template:

* changing the template version without updating integration identifiers
* renaming or removing template fields
* changing document IDs, role IDs, or role order
* changing required fields, validation rules, or field groups

#### Runtime configuration changes

Check these changes before deployment:

* changing mailbox or account access
* changing callback endpoint configuration
* changing statuses used by follow-up automation
* mixing template or environment identifiers

Treat these changes carefully before production release. Update the integration and run test requests.

Verify the complete workflow from authentication through the final follow-up action. Do not rely on endpoint-level testing alone.

### Handle unknown fields and values safely

Integrations should be strict enough to detect real errors, but flexible enough to ignore data they do not use. If a response contains an unknown field, the integration should not fail unless that field conflicts with the expected processing logic.

For enum-like values such as statuses, roles, domain statuses, or verification methods, handle known values explicitly and log unknown values safely. Do not silently process an unknown status as if it were a completed or successful state.

Example approach:

* process known success states
* process known waiting, error, and cancellation states
* log unknown values and pause automatic processing

This is safer than assuming that every unfamiliar value means success. Review the logged value before enabling automatic processing.

### Keep environments separate

Do not mix identifiers between environments. Template UUIDs, template versions, mailbox UUIDs, envelope UUIDs, dictionary UUIDs, account UUIDs, and domain UUIDs can be different between staging, testing, and production.

A request can fail or affect the wrong data if an integration uses production identifiers in staging or staging identifiers in production.

Store environment-specific values separately:

{% columns %}
{% column %}

* base API URL
* API token
* account UUID
* mailbox UUIDs
* template UUIDs
  {% endcolumn %}

{% column %}

* template versions
* dictionary UUIDs
* callback URLs
* metadata keys
  {% endcolumn %}
  {% endcolumns %}

Review these values before deployment. The request format can be correct while identifiers target the wrong environment.

Environment mix-ups are therefore difficult to debug. Keep each environment configuration isolated.

Keep the mailbox context consistent within one integration flow. This is required when an uploaded attachment is referenced by a later envelope request.

Record the mailbox context with the attachment identifier. Check both values before sending the envelope.

### Use configuration for reusable identifiers

Do not scatter reusable identifiers across source code. Store stable integration values in configuration so they can be reviewed and updated without changing unrelated code.

Good candidates for configuration include:

{% columns %}
{% column %}

* base API URL
* mailbox UUIDs
* template UUIDs
* expected template version
* dictionary UUIDs
  {% endcolumn %}

{% column %}

* callback endpoint URLs
* metadata keys
* polling filters
* page size
  {% endcolumn %}
  {% endcolumns %}

Do not store API tokens in unsafe configuration files. Store tokens in secure server-side secret storage, not in source code or public configuration.

Limit access to token storage to the services that need it. Rotate a token immediately after suspected exposure.

### Confirm callback contracts separately

This guide covers compatibility rules for callback-based integrations. Callbacks are currently documented for envelope forms.

Confirm the request method, headers, payload schema, authentication, signature validation, and retry behavior in [Swagger UI](https://api.docstudio.com/swagger-ui/index.html). Follow [Envelope callbacks](/guides/envelope-callbacks.md) for the form lifecycle and callback processing flow.

### Test compatibility before production release

Before releasing integration changes to production, test the complete workflow that the integration uses.

Minimum test checklist:

{% columns %}
{% column %}

* Authenticate successfully.
* Use documented endpoint paths.
* Use the correct API version.
* Use the correct mailbox or account.
* Upload required attachments.
  {% endcolumn %}

{% column %}

* Send or fill the envelope.
* Check field values.
* Check recipient roles.
* Save the envelope UUID.
* Check envelope status.
  {% endcolumn %}

{% column %}

* Download the archive when required.
* Read audit trails when required.
* Check metadata and callbacks when used.
* Confirm error handling.
  {% endcolumn %}
  {% endcolumns %}

Testing one endpoint is insufficient for most integrations. Test connected template-based envelope flows together.

### Document integration assumptions

Maintain a short internal note for every integration. This is especially important for templates, metadata, callbacks, file uploads, and mailbox polling.

Document these assumptions:

{% columns %}
{% column %}

* endpoints and API version
* template and version strategy
* expected role IDs
* expected document IDs
* expected field names
  {% endcolumn %}

{% column %}

* mailbox UUIDs
* metadata keys
* statuses triggering follow-up actions
* errors stopping the flow
* expected callbacks
  {% endcolumn %}

{% column %}

* environment-specific values
* deployment configuration
* ownership of template updates
  {% endcolumn %}
  {% endcolumns %}

This note clarifies what can break after platform or template changes. It also defines the required regression tests.

### Avoid common mistakes

Common versioning and compatibility mistakes include:

{% columns %}
{% column %}

* using undocumented browser routes
* assuming identical URL structures
* removing `/api/v1` from a documented path
* changing versions without **Swagger UI**
* confusing API and template versions
  {% endcolumn %}

{% column %}

* retaining old template identifiers
* renaming fields filled by the integration
* using optional metadata as core logic
* failing on unknown optional fields
* accepting unknown statuses as successful
  {% endcolumn %}

{% column %}

* mixing staging and production identifiers
* testing authentication only
* skipping the complete envelope flow
  {% endcolumn %}
  {% endcolumns %}

### Troubleshoot compatibility issues

If an integration stops working after an API, template, or configuration change, check these points first:

{% columns %}
{% column %}

* The endpoint URL and HTTP method match the API reference.
* The API version and required headers are correct.
* The request body and XML remain valid.
* The mailbox and account belong to the correct environment.
* Uploaded files pass `attachmentId` as `attachmentUuid`.
* The integration handles changed response fields safely.
* The returned error code matches the request failure.
  {% endcolumn %}

{% column %}

* The template UUID and version are correct.
* Role and document IDs match the template version.
* Field names still exist in the selected document.
* Required fields and validation rules are satisfied.
* Unknown statuses and enum values are logged.
* The full workflow passed after the change.
  {% endcolumn %}
  {% endcolumns %}

Use [Common API Error Codes](/error-codes/error-handling-and-api-error-codes.md) to interpret documented error responses. Keep request and response logs without tokens or other secrets.

Record the endpoint, status code, and correlation data needed for investigation. Remove sensitive values before sharing logs.

### Related topics

{% columns %}
{% column %}

* [API overview](/introduction/api-overview.md)
* [Core concepts](/introduction/core-concepts.md)
* [Authentication and application tokens](/introduction/authentication-and-application-tokens.md)
  {% endcolumn %}

{% column %}

* [Working with XML payloads](/guides/xml-payloads.md)
* [Working with templates and reusable IDs](/guides/templates-and-reusable-ids.md)
* [Uploading files and external documents](/guides/files-and-external-documents.md)
  {% endcolumn %}

{% column %}

* [Pagination, filtering, and sorting](/guides/list-responses.md)
* [Envelope callbacks](/guides/envelope-callbacks.md)
* [Send your first envelope](/introduction/send-your-first-envelope.md)
  {% endcolumn %}
  {% endcolumns %}