Envelope Signing (eSign)API ReferenceGet Envelope Detail

Get Envelope Detail

POST/openapi/v1/envelopes/detail

Get the envelope's current status and signer progress.

Request Parameters

Header Parameters
AuthorizationRequiredstring
Bearer <access_token>
X-Operator-User-IdOptionalstring
Operator user ID. Not required in Authorization Code mode (the authorized user is used automatically). Optional in Client Credentials mode — omit to use the system user ID.
Request Body
application/json
EnvelopeIdRequiredstring
Envelope ID (required)

Request Example

{
  "EnvelopeId": "SGEV1234567890"
}

Response Parameters

Response.Data
EnvelopeIdOptionalstring
Envelope ID
OutEnvelopeIdOptionalstring
External business ID (returned if provided when creating, otherwise empty)
BasicInfoOptionalobject
Envelope basic info
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). When omitted, EmailSubject defaults to the envelope's EnvelopeTitle and EmailMessage is empty.
EmailSubjectOptionalstring
Signing invitation email subject (optional, defaults to envelope's EnvelopeTitle)
EmailMessageOptionalstring
Email body shown to recipients (optional)
SkippedNotificationsOptionalarray<string>
Email notifications to skip. The corresponding party does not receive emails for the listed events; omit this field or pass an empty array to skip nothing (default behavior). Allowed values (6): - `sender_on_sent`: do not notify the sender after the envelope is sent - `signer_on_sent`: do not notify signers after the envelope is sent - `cc_on_sent`: do not notify carbon-copy recipients after the envelope is sent - `sender_on_finished`: do not notify the sender when the envelope reaches a final state - `signer_on_finished`: do not notify signers when the envelope reaches a final state - `cc_on_finished`: do not notify carbon-copy recipients when the envelope reaches a final state **Finished** covers all final states: fully signed, voided, expired and declined. Note: one person may belong to more than one party (for example the sender is also a signer), in which case they receive the emails sent to each party separately. To stop all of them, include every matching value — for example pass both `sender_on_finished` and `signer_on_finished`. Email only: SMS and email verification codes are not affected.
StatusDetailOptionalobject
Envelope status detail
StatusOptionalstring
Envelope current status. draft; sending (async anchor resolving for large documents); sent (including delivered/viewed/partial-signed); sent_failed (async anchor resolving failed or timed out for large documents); completed; voided; declined.
draftsendingsentsent_failedcompletedvoideddeclined
CreatedAtOptionalstring(date-time)
Creation time, RFC3339 format
SentAtOptionalstring(date-time)
Sent time, RFC3339 format (empty for draft)
CompletedAtOptionalstring(date-time)
Completion time, RFC3339 format (only when completed)
VoidedAtOptionalstring(date-time)
Voided time, RFC3339 format (only when voided)
VoidReasonOptionalstring
Void reason (only when voided)
FailureReasonOptionalstring
Failure reason (only when status = `sent_failed`).
DocumentsOptionalarray<object>
Document list
DocumentIdOptionalstring
System-assigned document ID
NameOptionalstring
Document name
OrderOptionalinteger
Document display order
PageCountOptionalinteger
Document page count
DocPagesOptionalarray<object>
Document page list
PageNumberOptionalinteger
Page number (starting from 1)
WidthOptionalnumber(double)
Page width (PDF native unit)
HeightOptionalnumber(double)
Page height (PDF native unit)
SignersOptionalarray<object>
Signer list with signing status
RecipientIdOptionalstring
System-assigned recipient ID
NameOptionalstring
Name (required)
EmailOptionalstring
Email (masked, e.g. z***@example.com)
SigningOrderOptionalinteger
Signing order (0 when SigningOrderType=parallel)
StatusOptionalstring
Signer status. created; sent; delivered; viewed; signed; declined; voided.
createdsentdeliveredviewedsigneddeclinedvoided
SignedAtOptionalstring(date-time)
Signing completion time, RFC3339 format (only when signed)
StatusUpdatedAtOptionalstring(date-time)
Last status update time, RFC3339 format
DeclineReasonOptionalstring
Decline reason (only when declined)
AuthenticationOptionalobject
Signer authentication settings (returned in detail)
AuthMethodsOptionalarray<string>
Authentication method, single choice (combinable options not yet available). Allowed: "email" | "access_code" | "ekyc". "none" is not supported; omit Authentication for no verification.
AccessCodeOptionalstring
Access code - required when AuthMethods contains "access_code"; signer must enter the code to enter the signing page.
EkycCertTypeOptionalstring
eKYC certificate type - required when AuthMethods contains "ekyc". Allowed: "idcard" | "passport" | "hkid".
CarbonCopiesOptionalarray<object>
Carbon-copy recipient list
RecipientIdOptionalstring
System-assigned recipient ID
NameOptionalstring
Name (required)
EmailOptionalstring
Email (masked, e.g. z***@example.com)
StatusOptionalstring
Carbon-copy status. created; sent; delivered; viewed.
createdsentdeliveredviewed
StatusUpdatedAtOptionalstring(date-time)
Last status update time, RFC3339 format
TabsOptionalarray<object>
All signing tabs of the envelope
TabIdOptionalstring
System-assigned tab ID
TabTypeOptionalstring
Tab type
signHerestampinitialHeredateSignedtextcheckboxdate
RecipientIdOptionalstring
Owning signer ID
DocumentIdOptionalstring
Owning document ID
PositionOptionalobject
Tab position
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). Providing a concrete value is recommended (range 60–300). If 0 or omitted, the server fills in a default width based on TabType: 120 for signHere / initialHere / stamp / attachment / text, and 16 for checkbox.
HeightOptionalnumber(double)
Field height, unit: pt (1 pt = 1/72 inch). Providing a concrete value is recommended (range 20–120). If 0 or omitted, the server fills in a default height based on TabType: 50 for signHere / initialHere, 120 for stamp, 120 for attachment, 16 for checkbox, and 18 for text.
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, shown on the signing page as the placeholder hint for this tab
ValueOptionalstring
Preset value
RequiredOptionalboolean
Whether required
ReadOnlyOptionalboolean
Whether read-only
TooltipOptionalstring
Tooltip text
StyleOptionalobject
Font style
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
CurrentValueOptionalstring
The value actually entered / selected by the signer (applicable to text/checkbox/date)
FilledAtOptionalstring(date-time)
Tab fill time, RFC3339 format
PropertiesOptionalstring
Type-specific extended properties (JSON string), consistent with the Tab.Properties supplied at creation time
NameOptionalstring
Tab name, matching the Name supplied when the tab was created; falls back to that TabLabel value when Name was omitted at creation time
CreatedByOptionalobject
Creator info
UserIdOptionalstring
User ID
NameOptionalstring
User name
EmailOptionalstring
User email
WatermarkOptionalobject
Watermark configuration. Null when envelope has no watermark configured.
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).
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
SigningSettingsOptionalobject
Signing settings (optional)
⌃Sub-properties
AllowFreePlaceTabsOptionalboolean
Whether signers may add signing fields themselves during signing (optional, default false). When true, Tabs may be empty; signers add fields on the signing page before completing. When false, Tabs must contain at least 1 field

Error Codes

Error CodeDescription
INVALID_REQUESTRequest body parsing failed or EnvelopeId is empty
NOT_FOUNDEnvelope does not exist
INTERNAL_ERRORInternal service error
Quick Create EnvelopeGet Signing Link