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) |
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)
- **signature_status** mode: only `Lang` (optional); other parameters are not applicable
Unspecified optional parameters use their default values.
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
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 |
INTERNAL_ERROR | Internal server error |