Create Contract Request

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.

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

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.write permission. 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

FieldTypeNotes
workflow_idstring, requiredThe contract flow this request is created from.
project_idstring, optionalThe project this contract belongs to; must be owned by your client and must not be archived.
user_idstring, optionalLegacy single-subject path: the registered user signing this contract.
business_customer_idstring, optionalLegacy single-subject path: the business customer signing this contract.
transaction_idstring, optionalA 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.
variablesobjectTemplate variable values applied to this request.
participant_overridesobjectPer-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_subjectsobjectPer-participant signer subjects keyed by participant key.
metadataobjectArbitrary 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_id or business_customer_id. Every user / business_customer participant in the contract flow resolves to that single subject. Providing neither or both is rejected with 422. This path cannot be used when the contract flow has an external participant, or has both user and business_customer participants (400).
  • Per participant - supply participant_subjects, keyed by the contract flow's participant keys. Every participant except client_signing_profile ones needs an entry; a missing entry is rejected (400). Each entry must carry exactly one of user_id, business_customer_id, or external ({name, email}), and it must match the contract flow 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).

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 400 listing the blockers.
  • Signers that sign at the same time must share one expire_after_hours. A participant_overrides value 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

StatusWhen
400Contract 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)
403Contract signing is disabled for the client
404Contract flow, template, project, named user, named business customer, or linked transaction not found under this client
422Request 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)
502The signing service returned an error or an invalid response
503The 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.

Body Params
string
required

ID of the signing workflow to create this request from

ID of the registered user (legacy single-subject path)

ID of the business customer (legacy single-subject path)

ID of the project this contract belongs to

ID of a payment transaction to link to this contract

variables
object

Template variable values for this request

participant_overrides
object

Per-participant overrides keyed by participant key

participant_subjects
object

Per-participant signer subjects keyed by participant key

metadata
object

Arbitrary metadata to attach to the request

Responses

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