Create Contract Builder Session

Start template builder session

Creates a short-lived session token for the document builder UI, allowing
you to configure field placements and signer roles on the template.
Returns 404 if the template does not exist, and 400 if it has not yet
been provisioned for signing.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

Start a document builder session for a contract template version. The endpoint mints a short-lived session token your dashboard uses to launch the embedded document builder, where you configure field placements and signer roles on the template. It returns the template identifiers, the session token, and the browser host to load the builder against.

Authentication & access

  • Requires a client API token: Authorization: Bearer <token>.
  • API credentials need the contracts.templates.write permission. Dashboard users need the OWNER, OPERATIONS, or DEVELOPER role, or a custom role that includes this permission.
  • Contract signing must be enabled for the client. If it is disabled the request returns 403.

Path parameters

  • template_version_id (string, required) - the contract template version to open a builder session for. It must belong to your client.

Template preconditions

The template version must already be provisioned with the signing service. A template that has not yet been provisioned for signing is rejected with 400.

A template needs at least one signer role and one fillable field before it can be sent or attached to a contract flow. After saving your changes in the builder, call Refresh Contract Template Metadata so the new roles and fields are stored on the template.

Response

Returns 200 with a ContractTemplateBuilderSessionResponse:

  • template_id - the local template version ID.
  • signing_template_id - the template ID in the signing service.
  • external_id - the external identifier for the template.
  • token - a short-lived session token for the document builder UI.
  • base_url - the browser host the embedded builder must be loaded against. Use this value as the builder host rather than the API origin.

Error responses

StatusWhen
400Template has not been provisioned for signing yet
403Contract signing is disabled for the client
404Template version not found under this client
503The document builder is not available because contract signing is not configured on the platform

Standard 401 (authentication), 403 (insufficient permission or role), and 429 (rate limit) responses apply to every endpoint and are documented in the Error reference.

Path Params
string
required
Responses

Language
Credentials
Bearer
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json