Create contract request
Initiates a new contract signing request from a published workflow (and
its published template); the request is sent to the configured signers.
Returns 404 if the workflow, template, project, or transaction is not
found, and 422 if the request shape is invalid (mixing legacy
user_id/business_customer_id with participant_subjects, or a
missing/invalid subject for a participant). Returns 400 if the workflow
or its template is not currently published.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Create a contract signing request from a contract flow. The endpoint resolves the contract flow's definition and template, validates every signer subject, persists the request and its participants, hands the document to the signing service to mint per-signer submitters, and advances the request to its first actionable state. It returns the created contract request with its participants and any available signing URLs.
Authentication & access
- Requires a client API token:
Authorization: Bearer <token>. - API credentials need the
contracts.requests.writepermission. Dashboard users need the OWNER or OPERATIONS 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
| Field | Type | Notes |
|---|---|---|
workflow_id | string, required | The contract flow this request is created from. |
project_id | string, optional | The project this contract belongs to; must be owned by your client and must not be archived. |
user_id | string, optional | Legacy single-subject path: the registered user signing this contract. |
business_customer_id | string, optional | Legacy single-subject path: the business customer signing this contract. |
transaction_id | string, optional | A payment transaction to link to this contract. One payment funds one live contract: a transaction already linked to another contract request is refused unless that request ended canceled, declined or expired. |
variables | object | Template variable values applied to this request. |
participant_overrides | object | Per-participant overrides keyed by participant key. Each entry may set name (max 255), email, field_values (merged over the contract flow's values), and expire_after_hours (1-2160; replaces the contract flow's signing window for this request, ignored for auto-signing participants). |
participant_subjects | object | Per-participant signer subjects keyed by participant key. |
metadata | object | Arbitrary metadata attached to the request. |
Signer subjects
A request can name its signers in one of two mutually exclusive ways. Providing both is rejected with 422:
- Legacy single subject - set exactly one of
user_idorbusiness_customer_id. Everyuser/business_customerparticipant in the contract flow resolves to that single subject. Providing neither or both is rejected with422. This path cannot be used when the contract flow has anexternalparticipant, or has bothuserandbusiness_customerparticipants (400). - Per participant - supply
participant_subjects, keyed by the contract flow's participant keys. Every participant exceptclient_signing_profileones needs an entry; a missing entry is rejected (400). Each entry must carry exactly one ofuser_id,business_customer_id, orexternal({name, email}), and it must match the contract flow participant's declared source:- source
userrequiresuser_id; - source
business_customerrequiresbusiness_customer_id; - source
externalrequiresexternaldetails; - a participant whose source is the client's own signing profile must not appear in
participant_subjects. - An entry for an unknown participant key is rejected (
400).
- source
Verification status is not checked when creating the request: a named user / business_customer subject in any verification state can be a signer.
Every signer needs a valid email address. A business_customer signer without a contact email and no email override, or a signer email that is not a valid address, is rejected (400).
Preconditions
- The contract flow must not be archived; otherwise
400. Contract flows are usable as soon as they are saved; there is no publish step. - The contract flow's template version must not be archived; otherwise
400. - If the contract flow contains a participant that auto-signs (the client's signing profile, or a stage configured for auto-sign) but that participant cannot actually be auto-signed, the request is rejected with
400listing the blockers. - Signers that sign at the same time must share one
expire_after_hours. Aparticipant_overridesvalue that splits such a group is rejected (400).
Delivery
When the request is created, link signers whose turn it is get the signing invitation email (unless the contract flow turns invitation emails off), and the contract flow's view-only (CC) recipients get their read-only view link. If the signing service returns an error after the request has been created (for example while auto-signing the first stage), the request is kept and returned in its current state instead of being rolled back. It moves on when the next signing event arrives; if nothing is pending (for example a failed auto-sign), call Reconcile Contract Request to retry.
Response
200 - the contract request was created. The body is the contract request, including its id, workflow_id, template_version_id, resolved status, current_stage_index / current_participant_key, the full participants list (each with its signing status, and a signer_url when delivery is link-based and it is that participant's turn to sign), active_signing_url when available, the applied variables and metadata, completion_extra_emails, cc_recipients (each with email, view_url and view_expires_at), and created_at / updated_at. completed_document_url and audit_log_url are always null in this response.
Error responses
| Status | When |
|---|---|
400 | Contract flow archived; template archived; project archived; the legacy path used with a contract flow that has an external participant or both user and business_customer participants; a participant_subjects entry is missing, lacks the subject its source requires, references an unknown participant key, or wrongly targets a client-signing-profile participant; a signer has no valid email address; signers signing in parallel end up with different expire_after_hours; a participant requires auto-sign but cannot be auto-signed; the transaction is already linked to another live or completed contract request; the template's document cannot fill in its variables (re-upload the template) |
403 | Contract signing is disabled for the client |
404 | Contract flow, template, project, named user, named business customer, or linked transaction not found under this client |
422 | Request body failed validation (e.g. missing workflow_id, subject-shape rules violated, a participant_subjects entry with not exactly one of user_id/business_customer_id/external, expire_after_hours out of range) |
502 | The signing service returned an error or an invalid response |
503 | The signing service is temporarily unavailable or not configured |
Standard 401 (authentication), 403 (insufficient permission or role), and 429 (rate limit) responses apply to every endpoint and are documented in the Error reference.