Skip to content
/Template browser

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

Create a new browser session

Request

To use our template browser for selecting the correct template, create a new browser session and redirect the end user to our app. Our app will then redirect the user back to your app to the URL defined in the handlers.

By creating a new browser session, you receive a redirect URL to send the end user. You also obtain a browser session ID, which allows you to retrieve the selected template, language, and the document title provided by the end user.

The redirect URL is a secure link to our hosted app. It contains a one-time authorization token to authenticate the end user securely. Our app exchanges the token for a session cookie, granting access to this specific browser session only.

The session expires after 15 minutes if the user has not been redirected to the URL.

Handlers

When creating a browser session, you must provide handler URLs.

Success handler The user is redirected to this URL after successfully selecting the template and other details. Please note that the user may be redirected to this URL multiple times if they navigate back to the session using the browser's history.

Cancel handler The user is redirected to this URL when they intentionally cancel the template selection by clicking the "back button" in the header. They can continue using the template browser if they navigate back to the session using the browser's history; therefore, this may be called multiple times.

Delete handler The user is redirected to this URL when the browser session expires or is deleted via the API. In many cases, it is acceptable to use the same endpoint as in the cancel handler. This may be called multiple times.

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

Handler url parameters

The handler URL is appended (existing query parameters will remain intact) with the following query parameters:

ParameterDescription
session_idTemplate browser session ID
template_idID of the selected template (only on success)
document_nameName the end-user choosed for the document (only on success)
languages[0]Primary language of the document (only on success)
languages[1]Secondary language of the document (only on success, optional)

For example, if you have defined success handler:

"success_handler": {
  "endpoint": "https://example.com?handler=success",
  "method": "GET"
}

The user will be redirected to URL:

https://example.com?handler=success&session_id=0195c6eb-99ae-73c1-94f0-1763b872735d&template_id=0195c6eb-99ae-73c1-cc3a-1763b8743333d&language[0]=en-GB&document_name=Employment%20Agreement

In most cases, you want to immediately start a new builder session using the provided data and redirect the user back to our UI.

Security
APIKey
Headers
Acceptstringrequired

Specify the response format.

Value"application/json"
Bodyapplication/json
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
ui_languagestring(App.Enums.UiLanguage)
Enum"en-GB""fi""de""pl""sv"
curl -i -X POST \
  https://api.builder.docue.com/api/browser/sessions \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_API Key_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "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 browser session.

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

Retrieve details of existing browser session

Request

Returns details of the existing browser session. This information can serve as the source of truth when the user is redirected to your success handler.

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/browser/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.BrowserSession.Data.BrowserSessionData.BrowserSessionData)
Response
application/json
{
  "data": {
    "id": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a",
    "status": "completed",
    "state": { … }
  }
}

Delete browser session

Request

Invalidates the browser session. The session remains accessible through the API for a limited time before it is permanently deleted. If the end user is still viewing the page, they will be redirected to the delete handler URL you specified.

There is no need to delete completed sessions; they will be automatically pruned after a certain period.

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/browser/sessions/7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_API Key_HERE>'

Responses

Successfully deleted the session.

Bodyapplication/json
dataobject(Api.BrowserSession.Data.BrowserSessionData.BrowserSessionData)
Response
application/json
{
  "data": {
    "id": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a",
    "status": "deleted",
    "state": null
  }
}

Builder

Hosted UI for end users to draft their document.

Operations