Get Embedded Page URL
POST/openapi/v1/embedded/views
Exchange an access token for an embedded page URL. Open the returned Url in a WebView to let the user initiate signing or view their contract list — no additional authentication is needed inside the WebView.
OperateType values:
| OperateType | Embedded Page Content | OperateParam Parameters |
|---|---|---|
request_signatures | Initiate signing (3-step flow: set recipients → place signature areas → send) | FileIds (required), CanEditFiles (optional), Lang (optional), EmailNotification (optional) |
signature_status | Contract list for the current user's Space | Lang (optional) |
FileIds obtained from POST /openapi/v1/files/upload, must be within 24-hour validity, and must be in PDF format. Non-PDF files must be converted via POST /openapi/v1/files/convert-tasks first.
After the user completes the flow (request_signatures): The embedded page shows a success screen with View Envelope and Envelope List buttons. Both navigate within the WebView — no page jump out of your app.
URL validity: The returned Url (containing the embedded token) is valid for 12 hours. Do not cache it for reuse — request a fresh URL each time.
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); optional in client_credentials mode, falls back to system user ID if omitted.
Request Body
application/jsonOperateTypeRequiredstring
Embedded page type.
- `request_signatures`: Open the 3-step envelope creation flow (set recipients → place signature areas → send). Requires `OperateParam` with `FileIds` (required).
- `signature_status`: Open the contract list for the current user's Space. `OperateParam` is optional, only `Lang` applies.
request_signaturessignature_status
OperateParamOptionalobject
Parameters associated with the selected `OperateType`. Parameter applicability varies by mode:
- **request_signatures** mode: `FileIds` (required), `CanEditFiles` (optional), `Lang` (optional), `EmailNotification` (optional)
- **signature_status** mode: only `Lang` (optional); other parameters are not applicable
Unspecified optional parameters use their default values.
Sub-properties
FileIdsOptionalarray<string>
List of file IDs to use in the embedded page. **Required only for `request_signatures` mode.** Obtained from `POST /openapi/v1/files/upload`. Each FileId must be within its 24-hour validity window and belong to the current user's Space. Files must be in PDF format; for non-PDF files, call `POST /openapi/v1/files/convert-tasks` to convert them to PDF before passing in.
CanEditFilesOptionalboolean
**Only applicable to `request_signatures` mode.** Whether to allow editing files (re-upload/delete) in the embedded page. Optional, defaults to `false`. When enabled, the `CanEditFiles` parameter is appended to the embedded page URL.
LangOptionalstring
Interface language, applicable to both modes. Allowed values: `en` (English), `zh-CN` (Simplified Chinese), `zh-HK` (Traditional Chinese), `id` (Indonesian), `ms` (Malay), `th` (Thai), `vi` (Vietnamese). When provided, the `Lang` parameter is appended to the embedded page URL; if omitted, the language configured in the current user's profile is used.
enzh-CNzh-HKidmsthvi
EmailNotificationOptionalobject
Email notification settings (optional). Applies to `request_signatures` mode only. Use it to skip certain emails when initiating signing from the embedded page. See EmailNotification for allowed values.
Sub-properties
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.
Response Parameters
Response.Data
UrlOptionalstring
The embedded page URL. Open this URL directly in a WebView. The URL contains a one-time embedded token valid for 12 hours. Do not cache or reuse — request a fresh URL each time.
ExpiresAtOptionalstring(date-time)
Expiry time of the embedded token in RFC3339 format.
Error Codes
| Error Code | Description |
|---|---|
INVALID_REQUEST | Missing or invalid parameters (e.g. OperateType not supported, FileIds empty for request_signatures) |
OPENAPI.EMBEDDED_FILE_MUST_BE_PDF | The file corresponding to FileId is not in PDF format. Call POST /openapi/v1/files/convert-tasks to convert it to PDF first |
UNAUTHORIZED | access_token missing, invalid, or expired |
EXTENSION.SKIPPED_NOTIFICATION_INVALID | Invalid EmailNotification.SkippedNotifications value (not one of the 6 allowed values) |
INTERNAL_ERROR | Internal server error |