Update existing builder session

Embed API

API Reference

Update existing builder session

Request

Updates mutable builder session settings.

Currently the endpoint supports updating:

trial mode configuration. Set trial to null to disable trial mode.
finalization confirmation settings. Set finalization to null to clear custom finalization behavior. For trial and finalization field definitions, constraints, and HTML support rules, see Create a new builder session. See also the Finalize confirmation dialog guide.

Security

APIKey

Path

session_idstring, (uuid)required

The UUID of the session to update.

Example:7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a

Acceptstringrequired

Specify the response format.

Value:"application/json"

X-Participantstring, (uuid)required

Participant ID of a user in this builder session.

Example:123e4567-e89b-12d3-a456-426614174000

Bodyapplication/json

trialBuilderSessionTrial (object) or null

Any of:

Trial mode configuration shown in the Builder UI. When trial mode is enabled, the session cannot be finalized. Only heading_text and finalize_content support sanitized HTML. Other text fields are plain text only.

finalizationBuilderSessionFinalization (object) or null

Any of:

Finalization confirmation settings for the finalize dialog. confirmation_enabled is required whenever finalization is provided. These settings are ignored while trial mode is enabled (trial is not null).

curl -i -X PATCH \
  https://api.builder.docue.com/api/builder/sessions/7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_API Key_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Participant: 123e4567-e89b-12d3-a456-426614174000' \
  -d '{
    "trial": {
      "cta_url": "https://example.com/trial",
      "heading_text": "<strong>Free trial</strong> - Upgrade to unlock full preview, downloads, and e-signing.",
      "heading_cta_text": "Explore plans",
      "preview_text": "Unlock full preview",
      "finalize_title": "Finish and use your document",
      "finalize_content": "<h3>Your document is ready.</h3><p>Upgrade to:</p><ul><li>View the full document</li><li>Download it as a PDF</li><li>Send it for signing</li></ul>",
      "finalize_cta_text": "Explore plans"
    },
    "finalization": {
      "confirmation_enabled": true,
      "confirmation_text": "<strong>Please review carefully.</strong> This action cannot be undone."
    }
  }'

Responses

Successfully updated the session.

Bodyapplication/json

dataobject(BuilderSessionData)

Response

{
  "data": {
    "id": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a",
    "status": "pending",
    "trial": { … },
    "finalization": { … },
    "participants": [ … ]
  }
}