Create Contract Request

Time	Status	User Agent
Retrieving recent requests…

Create a contract signing request from a published signing workflow. The endpoint resolves the workflow's published snapshot and template, validates and verifies every signer subject, persists the request and its participants, hands the document to the signing provider 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>.
The caller must hold the contracts.requests.write permission and have the OWNER or OPERATIONS role.
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 published signing workflow this request is created from.
`project_id`	string, required	The project this contract belongs to; must be owned by your client.
`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.
`variables`	object	Template variable values applied to this request.
`participant_overrides`	object	Per-participant overrides (`name`, `email`, `phone`, `field_values`) keyed by participant key.
`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 (422 at validation, re-checked as 400 in the service):

Legacy single subject - set exactly one of user_id or business_customer_id. Every user / business_customer participant in the workflow resolves to that single subject. Providing neither or both is rejected.
Per participant - supply participant_subjects, keyed by the workflow's participant keys. Each entry must carry exactly one of user_id, business_customer_id, or external ({name, email, phone?}), and it must match the workflow participant's declared source:
- source user requires user_id;
- source business_customer requires business_customer_id;
- source external requires external details;
- 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).

Every named user / business_customer subject must pass its verification policy before the request can be created. A subject whose verification is required, pending, on-hold, or rejected is rejected with 403.

Preconditions

The workflow must be in published state with a published snapshot; otherwise 400.
The workflow's template version must be published; otherwise 400.
If the workflow 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 400 listing the blockers.

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), active_signing_url when available, the applied variables and metadata, and created_at / updated_at.

Error responses

Status	When
`400`	Workflow not published; template not published; `participant_subjects` combined with `user_id`/`business_customer_id`; neither or both of `user_id`/`business_customer_id` on the legacy path; a `participant_subjects` entry is missing the subject its source requires, references an unknown participant key, or wrongly targets a client-signing-profile participant; a participant requires auto-sign but cannot be auto-signed
`403`	Contract signing disabled for the client; a named user or business customer subject has not satisfied its verification requirement
`404`	Workflow, 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`/`project_id`, subject-shape rules violated, a `participant_subjects` entry with not exactly one of `user_id`/`business_customer_id`/`external`)

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