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
    • Providing no signers with Seal true allows for automatic sealing.
    • 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

    NameTypeDescription
    SealBooleanRequired.

    Whether to seal the transaction (no signers required). When true, the transaction is automatically completed without requiring signatures.

    ReferenceString

    Custom reference identifier for the transaction

    PostbackUrlString

    URL to receive status notifications about the transaction

    DaysToExpireInteger

    Number of days until the transaction expires. If 0, uses organization default. Maximum value depends on organization settings.

    SendEmailNotificationsBoolean

    Whether to send email notifications to signers and receivers

    SignRequestModeenum:
    • 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)
    Languageenum:
    • de-DE
    • en-US
    • es-ES
    • fr-FR
    • it-IT
    • pl-PL
    • nl-NL

    Language code for transaction interface and emails

    ContextObject

    Custom JSON object for additional transaction data. Only JSON objects are allowed (no arrays or primitives).

    SignersArray<CreateSignerRequest>

    List of signers for the transaction

    ReceiversArray<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

    NameTypeDescription
    IdString

    Unique transaction identifier

    SealBoolean

    Whether the transaction is sealed (no signers required)

    ReferenceString

    Custom reference identifier

    PostbackUrlString

    Webhook URL for status notifications

    DaysToExpireInteger

    Days until the transaction expires.

    SendEmailNotificationsBoolean

    Send e-mail notifications to the sender.

    SignRequestModeenum:
    • 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.
    Languageenum:
    • de-DE
    • en-US
    • es-ES
    • fr-FR
    • it-IT
    • pl-PL
    • nl-NL

    Language code for the Sender email notifications, and transaction receipt.

    Statusenum:
    • 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
    ContextObject

    Custom JSON object for additional transaction metadata that was provided during creation.

    CreatedDateTimeString

    When the transaction was created

    ModifiedDateTimeString

    When the transaction was last modified

    CanceledDateTimeString

    When the transaction was cancelled, if applicable

    FilesObject

    Files attached to the transaction as a key-value mapping. Key is the file ID, value is the file information.

    SignersArray<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.

    ReceiversArray<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.

    CancelationReasonString

    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

    NameTypeDescription
    typeString

    A URI reference identifying the problem type. This property is always present in RFC 7807 responses.

    titleString

    A short, human-readable summary of the problem

    detailString

    A human-readable explanation specific to this occurrence of the problem

    statusInteger

    The HTTP status code

    instanceString

    A URI reference that identifies the specific occurrence of the problem

    MessageString

    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

    NameTypeDescription
    typeString

    A URI reference identifying the problem type. This property is always present in RFC 7807 responses.

    titleString

    A short, human-readable summary of the problem

    detailString

    A human-readable explanation specific to this occurrence of the problem

    statusInteger

    The HTTP status code

    instanceString

    A URI reference that identifies the specific occurrence of the problem

    MessageString

    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

    NameTypeDescription
    typeString

    A URI reference identifying the problem type. This property is always present in RFC 7807 responses.

    titleString

    A short, human-readable summary of the problem

    detailString

    A human-readable explanation specific to this occurrence of the problem

    statusInteger

    The HTTP status code

    instanceString

    A URI reference that identifies the specific occurrence of the problem

    MessageString

    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.