Skip to content
/Builder

Embeddable Builder API (0.1.0)

Authentication

All endpoints in this API require Bearer authentication using an API key. Include the API key obtained from the customer portal in the Authorization header of each request, formatted as follows:

Authorization: Bearer <api_key>
Download OpenAPI description
openapi.json
openapi.yaml
Overview
URL
https://docue.com
E-mail
eb-support@docue.com
Languages
Servers
Production
https://api.builder.docue.com/

Workspaces

Endpoint for fetching information about the authenticated workspace. It can be used to test if the API authentication works.

Operations

Templates

Fetch a list of all available templates. Use this if you want to create a fully customized UI for selecting templates. If you prefer to use our ready-made UI, you can use the Template Browser instead.

Operations

Template browser

Hosted UI for end users to select the appropriate template. Use this if you want to take advantage of our UI.

Operations

Builder

Hosted UI for end users to draft their document.

Operations

Create a new builder session

Request

A builder session is required to start drafting a document with the Embeddable Builder (EB). 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.

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:

ParameterDescription
session_idBuilder session ID
participant_idBuilder participant ID
Security
APIKey
Headers
Acceptstringrequired

Specify the response format.

Value"application/json"
Bodyapplication/json
contractobject(Api.BuilderSession.Payload.ContractPayload.ContractPayload)required
contract.​document_namestringrequired
contract.​languagesArray of stringsrequired
contract.​template_idstringrequired
handlersobject(App.Payload.Primitives.HandlersPayload.HandlersPayload)required
handlers.​cancel_handlerobject(App.Payload.Primitives.HandlerPayload.HandlerPayload)required
handlers.​cancel_handler.​methodstring(App.Enums.HttpMethod)required
Value "GET"
handlers.​cancel_handler.​urlstringrequired
handlers.​delete_handlerobject(App.Payload.Primitives.HandlerPayload.HandlerPayload)required
handlers.​delete_handler.​methodstring(App.Enums.HttpMethod)required
Value "GET"
handlers.​delete_handler.​urlstringrequired
handlers.​error_handlerobject(App.Payload.Primitives.HandlerPayload.HandlerPayload)required
handlers.​error_handler.​methodstring(App.Enums.HttpMethod)required
Value "GET"
handlers.​error_handler.​urlstringrequired
handlers.​success_handlerobject(App.Payload.Primitives.HandlerPayload.HandlerPayload)required
handlers.​success_handler.​methodstring(App.Enums.HttpMethod)required
Value "GET"
handlers.​success_handler.​urlstringrequired
participantobject(App.Payload.Primitives.ParticipantPayload.ParticipantPayload)
ui_languagestring(App.Enums.UiLanguage)
Enum"en-GB""fi""de""pl""sv"
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"
      }
    }
  }'

Responses

Successful response with details about the builder session.

Bodyapplication/json
dataobject(Api.BuilderSession.Data.BuilderSessionCreatedData.BuilderSessionCreatedData)
Response
application/json
{
  "data": {
    "id": "0195c6eb-99ae-73c1-94f0-1763b872735d",
    "url": "https://app.builder.docue.com/browser-session/0195c6eb-99ae-73c1-94f0-1763b872735d#pREXDkBmZSOnl29EzmoICcfx9S19ix6u",
    "participant": { … }
  }
}

Retrieve details of existing builder session

Request

Returns details of the existing builder session.

Security
APIKey
Path
session_idstring(uuid)required

The UUID of the session to retrieve.

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

Specify the response format.

Value"application/json"
curl -i -X GET \
  https://api.builder.docue.com/api/builder/sessions/7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_API Key_HERE>'

Responses

Successfully retrieved the session.

Bodyapplication/json
dataobject(Api.BuilderSession.Data.BuilderSessionData.BuilderSessionData)
Response
application/json
{
  "data": {
    "id": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a",
    "status": "completed",
    "participants": [ … ]
  }
}

Delete builder session

Request

Invalidates the builder session. The session is no longer accessible via the API after deletion. If the end user is still in the builder, they are redirected to the delete handler URL you provided when creating the session.

Security
APIKey
Path
session_idstring(uuid)required

The UUID of the session to delete.

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

Specify the response format.

Value"application/json"
curl -i -X DELETE \
  https://api.builder.docue.com/api/builder/sessions/7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_API Key_HERE>'

Responses

Successfully deleted the session. No content is returned.

Response
No content

Get contract state and signees

Request

Get contract's state and list of signees.

Security
APIKey
Path
session_idstring(uuid)required

The UUID of the session

Example: 7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a
curl -i -X GET \
  https://api.builder.docue.com/api/builder/sessions/7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a/contract \
  -H 'Authorization: Bearer <YOUR_API Key_HERE>'

Responses

Successfully retrieved contract

Bodyapplication/json
dataobject
Response
application/json
{
  "data": {
    "state": { … },
    "signees": [ … ]
  }
}

Update contract state and appearance

Request

Update the contract's state values and appearance using JSON Patch (RFC 6902) operations. The available operations depend on the path, as does the value.

See more detailed description and examples here.

Security
APIKey
Path
session_idstring(uuid)required

The UUID of the session

Example: 7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a
Headers
X-Participantstring(uuid)required

The participant ID for the builder session. This header is required for updating the contract state.

Example: 123e4567-e89b-12d3-a456-426614174000
Bodyapplication/json
operationsArray of objects
curl -i -X PATCH \
  https://api.builder.docue.com/api/builder/sessions/7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a/contract \
  -H 'Authorization: Bearer <YOUR_API Key_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Participant: 123e4567-e89b-12d3-a456-426614174000' \
  -d '{
    "operations": [
      {
        "op": "replace",
        "path": "/document_name",
        "value": "Employment agreement, John Doe"
      }
    ]
  }'

Responses

Successfully patched contract

Bodyapplication/json
dataobject
Response
application/json
{
  "data": {
    "state": { … },
    "signees": [ … ]
  }
}

Finalize contract

Request

Finalize the current builder session contract. Once finalized, the document becomes read-only and can no longer be patched. The document PDF and HTML can still be downloaded.

Security
APIKey
Path
session_idstring(uuid)required

The UUID of the session to finalize.

Example: 7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a
Headers
X-Participantstring(uuid)required

The participant ID for the builder session performing the finalize action.

Example: 123e4567-e89b-12d3-a456-426614174000
curl -i -X POST \
  https://api.builder.docue.com/api/builder/sessions/7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a/contract/finalize \
  -H 'Authorization: Bearer <YOUR_API Key_HERE>' \
  -H 'X-Participant: 123e4567-e89b-12d3-a456-426614174000'

Responses

Successfully finalized contract

Bodyapplication/json
dataobject
Response
application/json
{
  "data": {
    "state": { … },
    "signees": [ … ]
  }
}

Get HTML

Request

Retrieve the rendered HTML of the builder session document. This matches the PDF contents but in HTML format for previewing or custom rendering flows.

Security
APIKey
Path
session_idstring(uuid)required

The UUID of the session.

Example: 7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a
curl -i -X GET \
  https://api.builder.docue.com/api/builder/sessions/7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a/html \
  -H 'Authorization: Bearer <YOUR_API Key_HERE>'

Responses

Successfully retrieved HTML

Bodytext/html
string
Response
No content

Get PDF

Request

Get rendered PDF for the builder session.

Security
APIKey
Path
session_idstring(uuid)required

The UUID of the session

Example: 7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a
curl -i -X GET \
  https://api.builder.docue.com/api/builder/sessions/7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a/pdf \
  -H 'Authorization: Bearer <YOUR_API Key_HERE>'

Re-authenticate existing participant

Request

If you want to re-authenticate an existing participant in an ongoing Builder session, you can use this endpoint.

See details about the url in create builder session.

Security
APIKey
Path
session_idstring(uuid)required

The UUID of the session.

Example: 7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a
participant_idstring(uuid)required

The UUID of the participant to authenticate.

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

Specify the response format.

Value"application/json"
Bodyapplication/json
ui_languagestring(App.Enums.UiLanguage)
Enum"en-GB""fi""de""pl""sv"
curl -i -X POST \
  https://api.builder.docue.com/api/builder/sessions/7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a/participants/123e4567-e89b-12d3-a456-426614174000/authenticate \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_API Key_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "ui_language": "en-GB"
  }'

Responses

Successful response with details about the authenticated participant.

Bodyapplication/json
dataobject(Api.BuilderSession.Participant.Data.ParticipantAuthenticatedData.ParticipantAuthenticatedData)
Response
application/json
{
  "data": {
    "id": "0195c6eb-99ae-73c1-94f0-1763b872735d",
    "url": "https://app.builder.docue.com/browser-session/0195c6eb-99ae-73c1-94f0-1763b872735d#pREXDkBmZSOnl29EzmoICcfx9S19ix6u",
    "participant": { … }
  }
}