Create a new builder session

Embed API

API Reference

Create a new builder session

Request

A builder session is required to start drafting a document in the Builder through the Embed API. Each session is isolated and contains all document-related data. Once the session ends, all data is deleted from our servers.

To create a session, you need:

A template ID - Get this from our Template Listing API or let the end-user pick one via the hosted Template Browser UI.
A list of languages - The languages must match the languages available for the selected template. The language determines the final document's language that the end-user drafts. Currently, only one language can be provided.
A document name - Acts like a file name. It's shown in the builder UI and can be edited by the end-user.

Participant details

You can provide end-user details, such as display name and email, for your reference. These will be required later for collaboration features like commenting, but they are not currently in use. You can use the External ID field to store your internal user ID, which you can later use to match our participants with your users if needed.

Trial mode

You can optionally enable trial mode by providing trial configuration in the request payload. Trial mode configures trial-related texts and CTA shown in the Builder UI. Trial sessions cannot be finalized with POST /api/builder/sessions/{session_id}/contract/finalize.

HTML support in trial fields:

heading_text: HTML supported (sanitized). Allowed tags: strong, b, wbr.
finalize_content: HTML supported (sanitized). Allowed tags: strong, b, wbr, br, li, ul, h2, h3, h4, p.
heading_cta_text, preview_text, finalize_title, finalize_cta_text: plain text only (HTML not supported).

Finalization confirmation

You can optionally provide finalization settings to control the confirmation dialog shown before finalization. Omit finalization to use the default dialog.

confirmation_enabled controls whether confirmation dialog is shown before finalization.
confirmation_text: HTML supported. Allowed tags: strong, b, wbr.
If confirmation_enabled is true and confirmation_text is null, the Builder UI falls back to its default confirmation message.
If trial mode is enabled (trial is not null), finalization settings are ignored.

For more details and an example of the default dialog, see the Finalize confirmation dialog guide.

Redirect URL

After creating a session, you'll get a one-time URL to send the end-user to our hosted builder UI. Opening the link creates a secure session with access to that document only.

The redirect URL is valid for 15 minutes.

Handlers

You need to provide handlers that redirect the end user back to your service after drafting.

Success handler The user is redirected to this URL after completing the drafting session and filling in all the required information. The document is then considered "ready" and cannot be altered. Please note that the endpoint may be called multiple times if users navigates back to our builder via browser history.

Cancel handler The user is redirected to this URL after canceling the drafting session. The builder session remains intact. If the user navigates back to our UI using browser history, they can resume drafting. Therefore, it is possible for this handler to be called multiple times.

Delete handler The user is redirected to this URL after the document is deleted. Document can be deleted via API and end-users can delete the document through the UI. Once deleted, the document cannot be altered, but it remains accessible via the API for a certain period before being permanently deleted. If the user navigates back to the builder after deletion, they will be automatically redirected to this handler. Consequently, this endpoint may be called multiple times.

Error handler The user is redirected to this URL when an unexpected error occurs.

Handler url parameters

Handler URLs are appended (existing parameters will remain unchanged) with the following query parameters:

Parameter	Description
`session_id`	Builder session ID
`participant_id`	Builder participant ID

Security

APIKey

Acceptstringrequired

Specify the response format.

Value:"application/json"

Bodyapplication/json

contractobject(Api.BuilderSession.Payload.ContractPayload.ContractPayload)required

handlersobject(App.Payload.Primitives.HandlersPayload.HandlersPayload)required

participantobject(App.Payload.Primitives.ParticipantPayload.ParticipantPayload)

ui_languagestring(App.Enums.UiLanguage)

Enum:"en-GB""fi""de""pl""sv"

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 POST \
  https://api.builder.docue.com/api/builder/sessions \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_API Key_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "contract": {
      "template_id": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a",
      "document_name": "Employment agreement",
      "languages": [
        "en-GB"
      ]
    },
    "participant": {
      "email": "john.doe@example.org",
      "display_name": "John Doe"
    },
    "ui_language": "en-GB",
    "handlers": {
      "success_handler": {
        "url": "https://example.com",
        "method": "GET"
      },
      "error_handler": {
        "url": "https://example.com",
        "method": "GET"
      },
      "delete_handler": {
        "url": "https://example.com",
        "method": "GET"
      },
      "cancel_handler": {
        "url": "https://example.com",
        "method": "GET"
      }
    },
    "finalization": {
      "confirmation_enabled": true,
      "confirmation_text": "<strong>Please review carefully.</strong> This action cannot be undone."
    }
  }'

Responses

Successful response with details about the builder session.

Bodyapplication/json

dataobject(Api.BuilderSession.Data.BuilderSessionCreatedData.BuilderSessionCreatedData)

Response

{
  "data": {
    "id": "0195c6eb-99ae-73c1-94f0-1763b872735d",
    "url": "https://app.builder.docue.com/browser-session/0195c6eb-99ae-73c1-94f0-1763b872735d#pREXDkBmZSOnl29EzmoICcfx9S19ix6u",
    "participant": { … }
  }
}