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.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
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.writepermission. 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)
| Field | Type | Required | Notes |
|---|---|---|---|
file | file | Yes | The source document to upload. |
name | text | No | Display name for the template. When omitted, the uploaded filename (or Contract Template) is used. |
ad_hoc | boolean | No | Default 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
.pdfor.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 indetected_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, andpublished_at.is_ad_hoc-truewhen the template was uploaded withad_hoc=true.external_id,signing_template_id, andsigning_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 isfalsefor a DOCX uploaded without placeholders (nothing to fill). If an older DOCX reportsfalsebut does contain placeholders, sending it returns400until you re-upload it.
Error responses
| Status | When |
|---|---|
400 | Missing filename; unsupported file extension (not PDF or DOCX); empty file; file content does not match the declared PDF/DOCX type |
403 | Contract signing is disabled for the client |
413 | Uploaded file exceeds the maximum allowed size |
422 | The multipart form failed validation (e.g. the file part is missing) |
502 | The signing service rejected or failed the request while registering the document |
503 | The 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.