Compose and send a contract in one step
Publishes the template, builds a sequential signing workflow from the given
signers (optionally gated on a successful transaction), and sends the
contract request - atomically.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Compose and send a contract in a single call. The endpoint publishes the chosen template, builds a sequential signing workflow from the signers you supply (optionally inserting a payment gate that holds signing until a linked transaction succeeds), publishes that workflow, and creates the contract request that delivers the contract to the signers. All of these steps run atomically: if any step fails the whole operation is rolled back, so no orphaned template or workflow is left behind. On success it returns the created contract request, including its participants and their signing status.
Authentication & access
- Requires a client API token:
Authorization: Bearer <token>. - The caller must hold the
contracts.requests.writepermission and have the OWNER or OPERATIONS role. - The client must have contract signing enabled. If the feature is disabled the request returns
403.
Request body
| Field | Type | Notes |
|---|---|---|
template_version_id | string, required | ID of the contract template version to send. |
signers | array, required (min 1) | Ordered list of signers. Each entry's role must match a template signer role, and together the signers must cover every template signer role exactly once. |
payment_gate | object, optional | When set, signing is held until a linked transaction succeeds. payment_gate.after_role must match one of the signers' roles. |
save_as_flow | boolean, default false | Persist the ad-hoc setup as a reusable workflow instead of an internal ad-hoc one. |
flow_name | string, optional (max 255) | Name for the saved workflow when save_as_flow is true. Defaults to an auto-generated Ad-hoc: <template name> label. |
project_id | string, required | ID of the project this contract belongs to. |
transaction_id | string, optional | ID of a payment transaction to link to this contract. |
variables | object, optional | Template variable values applied to this contract. |
email_notifications | object, optional | Per-event email notification and attachment toggles for the workflow created by this send. |
Each signer (signers[])
signers[])| Field | Type | Notes |
|---|---|---|
role | string, required (1-255) | Signer role name as defined in the template. |
source | enum, required | Who fills this signer. One of: client_signing_profile (auto-sign), user, business_customer, or external. |
user_id | string | Required when source is user. |
business_customer_id | string | Required when source is business_customer. |
external | object | Required when source is external; provides the external signer's name, email, and optional phone. |
field_values | object, optional | Pre-filled template field values for this signer. |
Signer preconditions
- If any signer uses the
client_signing_profilesource (auto-sign), a signing profile must already be configured for the client. If none exists the request returns422. - Each
usersigner must reference a user under your client that passes its verification policy, and eachbusiness_customersigner must reference a business customer that passes its verification policy. Pending, on-hold, rejected, or otherwise ineligible subjects are rejected with403.
Template preconditions
The referenced template version is published as part of this call. It must be provisioned for signing, must not be archived, and must have at least one signer role and at least one fillable field; otherwise the request returns 400.
Response
Returns 200 with the created contract request. The payload includes the request id, the workflow_id and template_version_id that were used, overall status, the current_stage_index and current_participant_key, any linked transaction_id and project_id, applied variables and metadata, and the full list of participants with each one's signing status and (when available) signing URL.
Error responses
| Status | When |
|---|---|
400 | Duplicate signer role assignment; signers do not cover every template signer role exactly once; payment_gate.after_role does not match any signer; template is archived or not provisioned for signing; template has no signer roles or no fillable fields |
403 | Contract signing disabled for the client; a user or business_customer signer fails its verification requirement |
404 | Template version, signer user, signer business customer, project, or linked transaction not found under this client |
422 | Request body failed validation (e.g. signer source/subject mismatch, missing required external signer details); auto-sign requested without a configured signing profile |
Standard 401 (authentication), 403 (insufficient permission or role), and 429 (rate limit) responses apply to every endpoint and are documented in the Error reference.