# Embeddable Builder API #### 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 ``` Version: 0.1.0 ## Servers Production ``` https://api.builder.docue.com ``` ## Security ### APIKey API authentication using bearer token. Type: http Scheme: bearer Bearer Format: API Key ## Download OpenAPI description [Embeddable Builder API](https://developers.docue.com/_bundle/embeddable-builder-api/openapi.yaml) ## Workspaces Endpoint for fetching information about the authenticated workspace. It can be used to test if the API authentication works. ### Get current workspace - [GET /api/workspaces/current](https://developers.docue.com/embeddable-builder-api/openapi/workspaces/getcurrentworkspace.md) ## 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. ### List available templates - [GET /api/templates](https://developers.docue.com/embeddable-builder-api/openapi/templates/gettemplates.md) ### Get a single template - [GET /api/templates/{template_id}](https://developers.docue.com/embeddable-builder-api/openapi/templates/gettemplatebyid.md) ## Template browser Hosted UI for end users to select the appropriate template. Use this if you want to take advantage of our UI. ### Create a new browser session - [POST /api/browser/sessions](https://developers.docue.com/embeddable-builder-api/openapi/template-browser/createbrowsersession.md): 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: | Parameter | Description | | --------------- | -------------------------------------------------------------- | | session_id | Template browser session ID | | template_id | ID of the selected template (only on success) | | document_name | Name 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: json "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. ### Retrieve details of existing browser session - [GET /api/browser/sessions/{session_id}](https://developers.docue.com/embeddable-builder-api/openapi/template-browser/getbrowsersession.md): 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. ### Delete browser session - [DELETE /api/browser/sessions/{session_id}](https://developers.docue.com/embeddable-builder-api/openapi/template-browser/deletebrowsersession.md): 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. ## Builder Hosted UI for end users to draft their document. ### Create a new builder session - [POST /api/builder/sessions](https://developers.docue.com/embeddable-builder-api/openapi/builder/createbuildersession.md): 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: | Parameter | Description | | --------------- | ---------------------------------------------------- | | session_id | Builder session ID | | participant_id| Builder participant ID | ### Retrieve details of existing builder session - [GET /api/builder/sessions/{session_id}](https://developers.docue.com/embeddable-builder-api/openapi/builder/getbuildersession.md): Returns details of the existing builder session. ### Delete builder session - [DELETE /api/builder/sessions/{session_id}](https://developers.docue.com/embeddable-builder-api/openapi/builder/deletebuildersession.md): 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. ### Get contract state and signees - [GET /api/builder/sessions/{session_id}/contract](https://developers.docue.com/embeddable-builder-api/openapi/builder/getbuildersessioncontract.md): Get contract's state and list of signees. ### Update contract state and appearance - [PATCH /api/builder/sessions/{session_id}/contract](https://developers.docue.com/embeddable-builder-api/openapi/builder/patchbuildersessioncontract.md): 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. ### Finalize contract - [POST /api/builder/sessions/{session_id}/contract/finalize](https://developers.docue.com/embeddable-builder-api/openapi/builder/finalizebuildersessioncontract.md): 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. ### Get HTML - [GET /api/builder/sessions/{session_id}/html](https://developers.docue.com/embeddable-builder-api/openapi/builder/getbuildersessionhtml.md): Retrieve the rendered HTML of the builder session document. This matches the PDF contents but in HTML format for previewing or custom rendering flows. ### Get PDF - [GET /api/builder/sessions/{session_id}/pdf](https://developers.docue.com/embeddable-builder-api/openapi/builder/getbuildersessionpdf.md): Get rendered PDF for the builder session. ### Re-authenticate existing participant - [POST /api/builder/sessions/{session_id}/participants/{participant_id}/authenticate](https://developers.docue.com/embeddable-builder-api/openapi/builder/reauthenticateparticipant.md): 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.