Create Contract Template

Upload a contract template

Uploads a document file to create a new contract template version that is
usable immediately. Use the builder session endpoint to configure field
placements if the document has none yet. Set ad_hoc when the document is
only being sent once, so it does not show up as a reusable template.

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

Upload a document to create a new contract template version. The file is validated and stored, a template version is created with status published, and the document is registered with the signing service so its signer roles and fields can be detected. The template can be used right away; there is no separate publish step. Returns the created template version, including its detected roles, fields, and variable placeholders.

This is a multipart form upload, not a JSON request.

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.

Request body (multipart/form-data)

FieldTypeRequiredNotes
filefileYesThe source document to upload.
nametextNoDisplay name for the template. When omitted, the uploaded filename (or Contract Template) is used.
ad_hocbooleanNoDefault false. Set to true when the document is a one-off for a single send. One-off templates are left out of List Contract Templates unless include_ad_hoc=true is passed.

File constraints

  • Only PDF and DOCX documents are accepted; the extension must be .pdf or .docx.
  • The file content must actually match the declared type (the file must start with a PDF or DOCX file signature).
  • The file must be non-empty and must not exceed the maximum upload size of 10 MB (10485760 bytes).
  • A DOCX that contains [[variable]] placeholders is set up so the variables can be filled in on each send. They are returned in detected_variables.

Before you send

A template needs at least one signer role and one fillable field (for example a signature) before it can be sent or attached to a contract flow; otherwise those requests return 400. If the uploaded document has none, add them in the document builder with Start Template Builder Session, then call Refresh Contract Template Metadata to load them into the template.

Response

200 - The template version was created with status published. The payload is the template version, including:

  • id, name, status (published), file_type, and published_at.
  • is_ad_hoc - true when the template was uploaded with ad_hoc=true.
  • external_id, signing_template_id, and signing_template_slug.
  • the source file metadata under source_file.
  • roles - signer roles detected in the document.
  • fields - fields detected in the document.
  • detected_variables - variable placeholders found in the document.
  • variables_fillable - whether [[variable]] placeholders can be filled in when this template is sent. It is false for a DOCX uploaded without placeholders (nothing to fill). If an older DOCX reports false but does contain placeholders, sending it returns 400 until you re-upload it.

Error responses

StatusWhen
400Missing filename; unsupported file extension (not PDF or DOCX); empty file; file content does not match the declared PDF/DOCX type
403Contract signing is disabled for the client
413Uploaded file exceeds the maximum allowed size
422The multipart form failed validation (e.g. the file part is missing)
502The signing service rejected or failed the request while registering the document
503The signing service is temporarily unavailable

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

Body Params
string
required
boolean
Defaults to false

Mark this upload as a one-off for a single send; it stays out of template listings unless include_ad_hoc is set

Responses

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