Create an e-sign iframe builder session

Create a strong one-off iframe builder session for a draft e-sign document. The request body is empty. The response returns iframe_url, session_key, iframe_session_id, document_id, and expires_at; this iframe-session creation response does not expose the agency iframe allowlist, brand payload, allowed_origin, or redirect_url.

Before this endpoint can be used, RealAML must have iframe domains configured for the agency in Django admin under the agency branding settings (brand_iframe_allowed_urls). The session can only be created for a draft document and expires after 60 minutes.

Embed flow:

Create or fetch a draft document. For scratch drafts, call POST /documents/ with no template_id. For template drafts, call POST /documents/ with template_id and optional recipient role overrides.

Call this endpoint and place the returned iframe_url in an iframe in the partner application. Do not append session_key to the iframe URL.

When the iframe loads, it posts realaml.esign.ready to the parent window. The parent must verify the iframe origin and source, then send { type: "realaml.esign.session_key", session_key } to the iframe using postMessage with the exact RealAML app origin as targetOrigin.

The iframe exchanges the one-off session_key and the parent message origin for an iframe-scoped bearer token. RealAML validates that parent origin against the agency admin iframe domain allowlist.

The one-off key can be exchanged once. The resulting iframe token is scoped to this document, this agency, and the original user. It cannot be used for recipient mode and cannot access other documents.

Inside the iframe, the user can edit document metadata, apply a template to an empty draft, upload/remove files, manage recipients, place PDF fields, and send the document.

After a successful send, the iframe shows a document-sent message and posts realaml.esign.document_sent to the parent window. Event payload: document_id, status, sent_at, and iframe_session_id.

If the iframe session expires before completion, the iframe posts realaml.esign.session_expired to the parent window. Event payload can include document_id, iframe_session_id, expires_at, and message when known.

Use GET /documents/{envelope_id}/ or configured webhooks/callbacks for terminal completion state; the iframe send event only means sending was accepted and recipient notification processing started.

{ "iframe_session_id": "dcdee395-4335-45c8-ae30-12a2738d2982", "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6", "iframe_url": "http://example.com", "session_key": "string", "expires_at": "2019-08-24T14:15:22.123Z" }

Create an e-sign iframe builder session

Request

Responses