Create Transaction

Method: POST

Path: /api/transaction

Create a new transaction for document signing. A transaction contains signers, receivers, and configuration for the signing process. After creating a transaction, you can upload files and start the signing process.

Important Notes:

If Seal is false, at least one signer must be provided
Signers with AllowDelegation enabled cannot have authentications
If any signer has SendSignRequest enabled, SignRequestMode defaults to 2
Authentication array requires explicit versioning header (Accept: application/json;version=1)
The Type property in authentication/verification objects is case-sensitive and must be capitalized

Request Body (required)

The request body for creating a transaction

Content-Type: application/json

Schema: CreateTransactionRequest

Properties

Name	Type	Description
Seal	Boolean	Required. Whether to seal the transaction (no signers required). When true, the transaction is automatically completed without requiring signatures.
Reference	String	Custom reference identifier for the transaction
PostbackUrl	String	URL to receive status notifications about the transaction
DaysToExpire	Integer	Number of days until the transaction expires. If 0, uses organization default. Maximum value depends on organization settings.
SendEmailNotifications	Boolean	Whether to send email notifications to signers and receivers
SignRequestMode	enum: `0` `1` `2`	Mode for sign request delivery: 0: No sign requests 1: Send immediately 2: Send when ready (default when signers have SendSignRequest enabled)
Language	enum: `de-DE` `en-US` `es-ES` `fr-FR` `it-IT` `pl-PL` `nl-NL`	Language code for transaction interface and emails
Context	Object	Custom JSON object for additional transaction data. Only JSON objects are allowed (no arrays or primitives).
Signers	Array<CreateSignerRequest>	List of signers for the transaction
Receivers	Array<CreateReceiverRequest>	List of receivers who get copies of completed documents

Example:

{
  "Seal": false,
  "Reference": "CONTRACT-2024-001",
  "PostbackUrl": "https://example.com/webhook/signhost",
  "DaysToExpire": 30,
  "SendEmailNotifications": true,
  "SignRequestMode": 2,
  "Language": "en-US",
  "Context": {
    "department": "HR",
    "contract_type": "employment"
  },
  "Signers": [
    {
      "Email": "john.doe@example.com",
      "SendSignRequest": true,
      "SignRequestMessage": "Please review and sign the attached employment contract.",
      "Language": "en-US",
      "Verifications": [
        {
          "Type": "Scribble",
          "RequireHandsignature": true
        }
      ]
    }
  ],
  "Receivers": [
    {
      "Email": "hr@example.com",
      "Message": "The employment contract has been signed and is attached.",
      "Language": "en-US"
    }
  ]
}

Responses

200

Transaction created successfully

Content-Type: application/json

Schema: Transaction

Properties

Name	Type	Description
Id	String	Unique transaction identifier
Seal	Boolean	Whether the transaction is sealed (no signers required)
Reference	String	Custom reference identifier
PostbackUrl	String	Webhook URL for status notifications
DaysToExpire	Integer	Days until the transaction expires.
SendEmailNotifications	Boolean	Send e-mail notifications to the sender.
SignRequestMode	enum: `1` `2`	Sign request delivery mode 1: Send immediately 2: Send sequentially when ready (default when signers have SendSignRequest enabled) Note: Ignored if `SendSignRequest` is set to false.
Language	enum: `de-DE` `en-US` `es-ES` `fr-FR` `it-IT` `pl-PL` `nl-NL`	Language code for the Sender email notifications, and transaction receipt.
Status	enum: `5` `10` `20` `30` `40` `50` `60` `70`	Current transaction status: 5: Waiting For Document - Transaction created, documents being processed/prepared 10: Waiting For Signer - Documents ready, waiting for signers to sign 20: In Progress - A signer is currently in the process of signing 30: Signed - All signers have successfully signed the transaction 40: Rejected - One or more signers rejected the transaction 50: Expired - Transaction expired before all signers could complete 60: Cancelled - Transaction was cancelled by the creator 70: Failed - Transaction failed due to system errors or validation issues
Context	Object	Custom JSON object for additional transaction metadata that was provided during creation.
CreatedDateTime	String	When the transaction was created
ModifiedDateTime	String	When the transaction was last modified
CanceledDateTime	String	When the transaction was cancelled, if applicable
Files	Object	Files attached to the transaction as a key-value mapping. Key is the file ID, value is the file information.
Signers	Array<Signer>	List of signers attached to this transaction, including their configuration, current status, verification methods, and signing progress. Each signer represents an individual who needs to sign the document or has already completed the signing process.
Receivers	Array<Receiver>	List of receivers who will receive copies of the completed signed documents. Receivers are notified via email once the transaction is successfully completed and all required signatures have been obtained.
CancelationReason	String	The reason for the cancellation of the transaction, if applicable. This is provided when the transaction is cancelled via the DELETE endpoint.

400

Bad request - validation error

Content-Type: application/json

Schema: ErrorResponse

Properties

Name	Type	Description
type	String	A URI reference identifying the problem type. This property is always present in RFC 7807 responses.
title	String	A short, human-readable summary of the problem
detail	String	A human-readable explanation specific to this occurrence of the problem
status	Integer	The HTTP status code
instance	String	A URI reference that identifies the specific occurrence of the problem
Message	String	Deprecated (Legacy Format Only): Contains the error message in the old response format. This property appears alone in legacy error responses and is mutually exclusive with the RFC 7807 properties above. Will be phased out as we complete our transition to RFC 7807.

Example:

{
  "Message": "Invalid request data provided."
}

401

Unauthorized

Content-Type: application/json

Schema: ErrorResponse

Properties

Name	Type	Description
type	String	A URI reference identifying the problem type. This property is always present in RFC 7807 responses.
title	String	A short, human-readable summary of the problem
detail	String	A human-readable explanation specific to this occurrence of the problem
status	Integer	The HTTP status code
instance	String	A URI reference that identifies the specific occurrence of the problem
Message	String	Deprecated (Legacy Format Only): Contains the error message in the old response format. This property appears alone in legacy error responses and is mutually exclusive with the RFC 7807 properties above. Will be phased out as we complete our transition to RFC 7807.

500

Internal server error

Content-Type: application/json

Schema: ErrorResponse

Properties

Name	Type	Description
type	String	A URI reference identifying the problem type. This property is always present in RFC 7807 responses.
title	String	A short, human-readable summary of the problem
detail	String	A human-readable explanation specific to this occurrence of the problem
status	Integer	The HTTP status code
instance	String	A URI reference that identifies the specific occurrence of the problem
Message	String	Deprecated (Legacy Format Only): Contains the error message in the old response format. This property appears alone in legacy error responses and is mutually exclusive with the RFC 7807 properties above. Will be phased out as we complete our transition to RFC 7807.

#Create Transaction

#Request Body (required)

#Properties

#Responses

#200

#Properties

#400

#Properties

#401

#Properties

#500

#Properties

#Create Transaction

#Request Body (required)

#Properties

#Responses

#200

#Properties

#400

#Properties

#401

#Properties

#500

#Properties

Create Transaction

Request Body (required)

Properties

Responses

200

Properties

400

Properties

401

Properties

500

Properties

Create Transaction

Request Body (required)

Properties

Responses

200

Properties

400

Properties

401

Properties

500

Properties