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.
When BasicInfo.SigningOrderType=sequential, every signer must provide SigningOrder, and the values must start from 1 and be consecutive (for example, 1,2,3). Gaps are not allowed.

Required Scope: envelope:create (holding the envelope:manage superset scope is also sufficient)

Request Parameters

Header Parameters

AuthorizationRequiredstring

Bearer <access_token>

X-Operator-User-IdOptionalstring

Operator user ID. Not required in authorization_code mode (uses authorized user automatically); required in client_credentials mode, must be a valid member of the current space, 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)

TabsRequiredarray<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)

Field width, unit: pt (1 pt = 1/72 inch). Please provide a concrete value; recommended range 60–300. Passing 0 or omitting this field will render the field invisible on the signing page.

HeightOptionalnumber(double)

Field height, unit: pt (1 pt = 1/72 inch). Please provide a concrete value; recommended range 20–120. Passing 0 or omitting this field will render the field invisible on the signing page.

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. Adds a horizontal shift on top of the position determined by `RelativeLocation`; positive values shift right, negative values shift left.

AnchorYOffsetOptionalnumber(double)

Y offset relative to the anchor keyword, unit: pt (optional, default 0). Only valid in `anchor` mode. Adds a vertical shift on top of the position determined by `RelativeLocation`; positive values shift down, negative values shift up.

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: SimHei). SimHei=Heiti (sans-serif); SimSun=Song (serif); FangSong=Fangsong (serif). Allowed values: SimHei / SimSun / FangSong

SimHeiSimSunFangSong

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: SimHei). SimHei=Heiti (sans-serif); SimSun=Song (serif); FangSong=Fangsong (serif). Allowed values: SimHei / SimSun / FangSong

SimHeiSimSunFangSong

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

Envelope status. `sent` after successful sending; `sending` while async anchor resolving for large documents

sendingsent

CreatedAtOptionalstring(date-time)

Creation time, RFC3339 format

Response Example

{
  "Response": {
    "RequestId": "req-abc123",
    "Error": null,
    "Data": {
      "EnvelopeId": "SGEVa1b2c3d4e5f6",
      "Status": "sent",
      "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
`OPENAPI.OPERATOR_USER_NOT_HUMAN`	Operator user must be a member of 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`	Duplicate signing order
`VALIDATION.SIGNING_ORDER_REQUIRED`	SigningOrder is missing in sequential mode
`VALIDATION.SIGNING_ORDER_NOT_SEQUENTIAL`	Signing orders do not start from 1 and remain consecutive
`VALIDATION.TAB_TYPE_INVALID`	Tab type is invalid
`VALIDATION.TAB_DOCUMENT_NOT_EXIST`	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

Query File Conversion Tasks Get Envelope Detail