Quick Create Envelope

POST/openapi/v1/envelopes/quick-create

Create and send an envelope in a single call. The envelope immediately enters the signing workflow. By default, signing invitations are sent to recipients via email.

Associations

Tabs[].DocumentId corresponds to Documents[].DocumentId, and Tabs[].RecipientId corresponds to Signers[].RecipientId. The three are associated via flat ID references. Tabs[].RecipientId must reference a Signers[].RecipientId; referencing CarbonCopies is not allowed.

Sequential Signing

Set BasicInfo.SigningOrderType=sequential and assign a different SigningOrder to each signer (starting from 1, consecutive). The system will send signing invitations in that order.

Validation Rules

Every document must contain at least one signing tab assigned to a signer.
Every signer must have at least one tab in at least one document.

Request Parameters

Header Parameters

AuthorizationRequiredstring

Bearer <access_token>

X-Operator-User-IdRequiredstring

Operator user ID (required; this user will be the envelope sender)

Request Body

application/json

BasicInfoRequiredobject

Envelope basic info (required)

⌃Sub-properties

EnvelopeTitleRequiredstring

Envelope title, max 100 characters (required)

SigningOrderTypeRequiredstring

Signing order type (required). parallel = all signers receive invitations at once; sequential = invitations are sent one by one according to Signers[].SigningOrder.

parallelsequential

EnvelopeDescriptionOptionalstring

Envelope description / remarks (optional)

ExpirationRequiredobject

Expiration settings (required)

⌃Sub-properties

ExpiresAtRequiredstring(date-time)

Signing deadline in RFC3339 format, e.g., 2024-02-15T23:59:59Z. The envelope is automatically voided after this time

EmailNotificationOptionalobject

Email notification settings (optional)

⌃Sub-properties

EmailSubjectOptionalstring

Signing invitation email subject (optional, defaults to envelope's EnvelopeTitle)

EmailMessageOptionalstring

Email body shown to recipients (optional)

DocumentsRequiredarray<object>

Document list, 1-10 items (required)

⌃Sub-properties

DocumentIdRequiredstring

Client-generated temporary ID, unique within the request, referenced by Tab.DocumentId. Only letters, digits, hyphens (-), underscores (_); max 64 characters.

FileIdRequiredstring

File resource ID returned by the UploadFile endpoint (required)

NameOptionalstring

Document display name (optional; defaults to the original uploaded filename)

OrderRequiredinteger

Document display order, consecutive integers starting from 1, must be unique (required)

SignersRequiredarray<object>

Signer list, at least 1 item (required)

⌃Sub-properties

RecipientIdRequiredstring

Client-generated temporary ID, unique within the request, referenced by Tab.RecipientId. Only letters, digits, hyphens (-), underscores (_); max 64 characters.

NameRequiredstring

Name (required)

EmailRequiredstring(email)

Email (required)

SigningOrderOptionalinteger

Signing order, consecutive integers starting from 1. Required and must be unique when SigningOrderType=sequential; ignored when parallel (optional).

CarbonCopiesOptionalarray<object>

Carbon-copy recipient list (optional)

⌃Sub-properties

RecipientIdRequiredstring

Client-generated temporary ID, unique within the request, referenced by Tab.RecipientId. Only letters, digits, hyphens (-), underscores (_); max 64 characters.

NameRequiredstring

Name (required)

EmailRequiredstring(email)

Email (required)

TabsOptionalarray<object>

Signing tab list, at least 1 item (required); linked to signers via Tab.RecipientId

⌃Sub-properties

TabIdOptionalstring

Client-generated temporary ID (optional), unique within the request

TabTypeRequiredstring

Tab type. signHere=handwritten signature; stamp=stamp; initialHere=initial; dateSigned=sign date (auto-filled); text=text field; checkbox=checkbox; date=date (filled by signer).

signHerestampinitialHeredateSignedtextcheckboxdate

RecipientIdRequiredstring

Owning signer ID, must match Signers[].RecipientId. Referencing CarbonCopies is not allowed.

DocumentIdRequiredstring

Owning document ID, corresponds to Documents[].DocumentId

PositionRequiredobject

Tab position (required)

⌃Sub-properties

PositionTypeRequiredstring

Positioning mode (required). `absolute` = absolute coordinates; `anchor` = keyword-based positioning.

absoluteanchor

PageNumberOptionalinteger

Page number (starts from 1). Required for `absolute` mode. Optional for `anchor` mode; omit or set to 0 to search the whole document.

XPositionOptionalnumber(double)

X coordinate, unit: pt. Required for `absolute` mode; must NOT be set for `anchor` mode.

YPositionOptionalnumber(double)

Y coordinate, unit: pt. Required for `absolute` mode; must NOT be set for `anchor` mode.

WidthOptionalnumber(double)

Width, unit: pt (optional; 0 = auto)

HeightOptionalnumber(double)

Height, unit: pt (optional; 0 = auto)

AnchorStringOptionalstring

Anchor keyword text. Required for `anchor` mode; must NOT be set for `absolute` mode.

AnchorXOffsetOptionalnumber(double)

X offset relative to the anchor keyword, unit: pt (optional, default 0). Only valid in `anchor` mode.

AnchorYOffsetOptionalnumber(double)

Y offset relative to the anchor keyword, unit: pt (optional, default 0). Only valid in `anchor` mode.

MatchWholeWordOptionalboolean

Whether to match the keyword as a whole word, default false. Only valid in `anchor` mode. - `false` (fuzzy): A tab is placed at every occurrence of the keyword in the PDF (other characters may surround it). - `true` (whole-word): Only matches occurrences with no surrounding characters.

RelativeLocationOptionalstring

Keyword position alignment mode (optional) - anchor mode only, defaults to center alignment if not specified. Available values: Middle (center), Below (directly below), Right (directly right), LowerRight (lower right corner), UpperRight (upper right corner)

MiddleBelowRightLowerRightUpperRight

KeywordIndexesOptionalarray<integer>

Keyword indexes (optional) - anchor mode only. When the PDF contains multiple occurrences of the same keyword, specify which ones to use by index. Index starts from 0, e.g. [0,2] means use the 1st and 3rd keyword positions

TabLabelOptionalstring

Tab label / description (optional)

ValueOptionalstring

Preset value (optional, applicable to text / date types)

RequiredOptionalboolean

Whether required; defaults to true (optional)

ReadOnlyOptionalboolean

Whether read-only; defaults to false (optional)

TooltipOptionalstring

Tooltip text (optional)

StyleOptionalobject

Font style (optional, applicable to text / date types)

⌃Sub-properties

FontFamilyOptionalstring

Font family, default Arial. Options: Arial / SimSun / SimHei / Microsoft YaHei / Times New Roman / Courier New

FontSizeOptionalinteger

Font size, default 12, unit pt

FontColorOptionalstring

Font color in hexadecimal, default #000000

BoldOptionalboolean

Whether bold, default false

ItalicOptionalboolean

Whether italic, default false

TextAlignOptionalstring

Text alignment, default left

leftcenterright

OutEnvelopeIdOptionalstring

External business ID for idempotency control (optional). If an envelope with the same OutEnvelopeId already exists, the original envelope ID is returned.

WatermarkOptionalobject

Watermark configuration (optional). When omitted, the envelope has no watermark.

⌃Sub-properties

SubTypeRequiredstring

Watermark type: CUSTOM_WATERMARK = custom text / PERSON_INFO_WATERMARK = visitor info (only for view/sign stage; not supported for download)

CUSTOM_WATERMARKPERSON_INFO_WATERMARK

TextOptionalstring

Custom text. Required when SubType=CUSTOM_WATERMARK; length 1-50.

ScopeViewOptionalboolean

Whether to overlay watermark in view / online signing stage.

ScopeDownloadOptionalboolean

Whether to overlay watermark on downloaded PDF.

StyleOptionalobject

Render parameters (optional).

⌃Sub-properties

FontOptionalstring

Font (default: 黑体). Allowed values: 黑体 / 宋体 / 仿宋

黑体宋体仿宋

FontSizeOptionalinteger

Font size (pt). Range 6-72, default 20.

OpacityOptionalnumber(double)

Opacity. 0 = fully transparent, 1 = fully opaque. Range 0-1, default 0.1.

RotateOptionalinteger

Rotation angle in degrees, clockwise. Range 0-359, default 45.

DensityOptionalinteger

Tile density (effective only when Position=None): 1 = sparse / 2 = standard (default) / 3 = dense

PositionOptionalstring

Watermark position: None = tiled (default) / LeftTop / LeftBottom / RightTop / RightBottom / Center

NoneLeftTopLeftBottomRightTopRightBottomCenter

Request Example

{
  "BasicInfo": {
    "SigningOrderType": "sequential",
    "Expiration": {
      "ExpiresAt": "2024-02-15T23:59:59Z"
    },
    "EnvelopeTitle": "Procurement Contract 2024-Q1"
  },
  "EmailNotification": {
    "EmailSubject": "Please sign the procurement contract",
    "EmailMessage": "Please review and sign this contract. Thank you."
  },
  "Documents": [
    {
      "DocumentId": "doc1",
      "FileId": "SGf1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6",
      "Name": "procurement-contract.pdf",
      "Order": 1
    }
  ],
  "Signers": [
    {
      "RecipientId": "r1",
      "Name": "Alice",
      "Email": "alice@example.com",
      "SigningOrder": 1
    },
    {
      "RecipientId": "r2",
      "Name": "Bob",
      "Email": "bob@example.com",
      "SigningOrder": 2
    }
  ],
  "CarbonCopies": [
    {
      "RecipientId": "cc1",
      "Name": "Carol",
      "Email": "carol@example.com"
    }
  ],
  "Tabs": [
    {
      "TabType": "signHere",
      "RecipientId": "r1",
      "DocumentId": "doc1",
      "Position": {
        "PositionType": "absolute",
        "PageNumber": 3,
        "XPosition": 100,
        "YPosition": 200,
        "Width": 120,
        "Height": 40
      }
    },
    {
      "TabType": "signHere",
      "RecipientId": "r2",
      "DocumentId": "doc1",
      "Position": {
        "PositionType": "anchor",
        "AnchorString": "Party A Signature",
        "AnchorXOffset": 80,
        "AnchorYOffset": -10,
        "MatchWholeWord": true,
        "RelativeLocation": "Right",
        "KeywordIndexes": [
          0
        ],
        "Width": 120,
        "Height": 40
      }
    }
  ]
}

Response Parameters

Response.Data

EnvelopeIdOptionalstring

Envelope ID

OutEnvelopeIdOptionalstring

External business ID (returned if provided when creating, otherwise empty)

StatusOptionalstring

Result of this API call. Values: - `success`: Call succeeded; the envelope has been initiated - `partial`: Some recipients failed to be processed - `failed`: All processing failed Note: emails are delivered by the system in the background, so signers may receive them with a delay of a few seconds to a few minutes. To check the envelope's latest state (e.g. whether it has been signed), call the envelope detail endpoint.

CreatedAtOptionalstring(date-time)

Creation time, RFC3339 format

Response Example

{
  "Response": {
    "RequestId": "req-abc123",
    "Error": null,
    "Data": {
      "EnvelopeId": "SGEVa1b2c3d4e5f6",
      "Status": "success",
      "CreatedAt": "2024-01-15T10:30:00Z"
    }
  }
}

Error Codes

Error Code	Description
`OPENAPI.OPERATOR_USER_ID_REQUIRED`	X-Operator-User-Id header not provided
`OPENAPI.OPERATOR_USER_NOT_FOUND`	The user does not exist or is not in the current space
`INVALID_REQUEST`	Request body parsing failed
`VALIDATION.TITLE_EMPTY`	Envelope title is empty
`VALIDATION.TITLE_TOO_LONG`	Envelope title exceeds 100 characters
`VALIDATION.SIGNING_ORDER_TYPE_INVALID`	SigningOrderType is invalid
`VALIDATION.DOCUMENT_REQUIRED`	Document list is empty
`VALIDATION.DOCUMENT_ID_DUPLICATE`	Duplicate document ID
`VALIDATION.DOCUMENT_FILE_ID_EMPTY`	Document FileId is empty
`VALIDATION.SIGNER_REQUIRED`	Signer list is empty
`VALIDATION.RECIPIENT_ID_DUPLICATE`	Duplicate signer or carbon-copy recipient ID
`VALIDATION.RECIPIENT_EMAIL_INVALID`	Invalid email format
`VALIDATION.SIGNER_REQUIRES_TAB`	Signer has no tabs
`VALIDATION.DOCUMENT_REQUIRES_SIGNER_TAB`	Document has no signer tabs
`VALIDATION.SIGNING_ORDER_INVALID`	Signing order is invalid
`VALIDATION.TAB_TYPE_INVALID`	Tab type is invalid
`VALIDATION.TAB_DOCUMENT_INVALID`	Tab references a non-existent document
`VALIDATION.TAB_RECIPIENT_NOT_SIGNER`	Tab RecipientId does not refer to a Signer
`VALIDATION.EXPIRES_AT_PAST`	Expiration time is in the past
`ENVELOPE.OUT_ID_DUPLICATE`	OutEnvelopeId already exists (returns existing envelope)
`INTERNAL_ERROR`	Internal service error

Upload Files Get Envelope Detail