Embedded Signing

Overview

Embedded signing allows your users to sign agreements directly within your application interface without receiving an email invitation link or being redirected to an external domain.

The signer reviews the document, navigates required fields, adopts or draws an e-signature, and submits the completed envelope. All interactions occur inside a secure, sandboxed iframe.

Configuring embedded signers

A signer signs in your app when their deliveryMode is "EMBEDDED". Signers added in the embedded sender widget are EMBEDDED by default. When you create an envelope with POST /api/v1/inkfree/envelopes (see Envelopes) or a draft with POST /api/v1/inkfree/embed/drafts, set it on the signer:

"signers": [
  {
    "id": 0,
    "name": "Ana Ruiz",
    "email": "ana@example.com",
    "deliveryMode": "EMBEDDED"
  }
]

Mint a signing session token

curl -X POST "https://services.softsages.com/core/api/v1/inkfree/embed/sessions" \
  -H "X-API-Key: sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "signing",
    "requestId": "e4b281f9a0c3451ea9f1388b7d23a105",
    "signerEmail": "ana@example.com",
    "parentOrigin": "https://app.example.com"
  }'

{
  "token": "YOUR_ONE_TIME_TOKEN",
  "scope": "signing",
  "requestId": "e4b281f9a0c3451ea9f1388b7d23a105",
  "expiresInSeconds": 300
}

Validation rules & signing order

Inkfree issues a signing token only when all of these are true:

• Your API key is active and your account is open.
• parentOrigin is registered under Settings > API Keys > Embedded signing origins.
• The envelope exists and its status is Pending: approvers, if any, have approved and a scheduled send time has passed (REQUEST_NOT_READY otherwise). An approver's token is the exception, see below.
• The email belongs to a signer on the envelope with deliveryMode: "EMBEDDED", who is a regular signer (not a CC recipient). While the envelope is InReview, it may instead belong to an EMBEDDED approver under approval.reviewers.
• The signer has not signed yet. An access code or one-time code on the signer does not stop the token: the signer enters it inside the iframe.
• Signing order: If the envelope uses a signing order, it must be this signer's turn. A token requested before the earlier signers have signed is refused with NOT_YOUR_TURN.

Embedded approvers

Approvers can approve inside your app too, with the same token call and the same widget. An approver is embedded when their deliveryMode is "EMBEDDED"; every approver added in the sender widget or pre-filled on a draft is. Inkfree sends an embedded approver no email.

1. After sending, the envelope is InReview. Read it and find the approvers under approval.reviewers with status Pending.
2. Mint a token with scope: "signing" and the approver's email as signerEmail.
3. Mount the widget with type: "sign". The approver sees the document with Approve and Reject.
4. The widget sends approval_viewed, then approval_completed or approval_rejected. Confirm on your server: when every approver has approved, the envelope becomes Pending and you can mint tokens for the signers. A rejection makes it Rejected.

An approver gets a token only while they are Pending and it is their turn. An approver who is not embedded gets SIGNER_NOT_EMBEDDED; one who already approved gets REQUEST_COMPLETED; with an approval order, a later approver gets NOT_YOUR_TURN. In an approver group, once one member approves the others are Skipped and get NOT_YOUR_TURN. A decision counts once. An approver with an EMAIL delivery mode (possible on envelopes you create with POST /api/v1/inkfree/envelopes) is emailed as usual.

Mounting the signing widget

Once your server returns the one-time token, initialize the widget in your web page:

<div id="signing-container" style="width: 100%; height: 750px;"></div>

<script src="https://sign.inkfree.app/embed/inkfree-embed.js"></script>
<script>
  var widget = InkfreeEmbed.mount({
    container: "#signing-container",
    type: "sign",
    token: token,
    theme: {
      primaryColor: "#0a7d5c",
      buttonTextColor: "#ffffff"
    }
  });

  widget.on("sign_completed", function (event) {
    console.log("Document signed by:", event.data.signerRole);
    // Display confirmation screen or redirect
  });

  widget.on("sign_declined", function () {
    console.log("Document was declined by signer");
  });
</script>

A signer who completes the flow produces these events, in order: ready, signer_viewed, sign_started (once, when the signer fills the first field or adopts a signature) and sign_completed. A signer who declines produces sign_declined instead, and the decline reason stays inside Inkfree. After sign_completed or sign_declined the widget stays on a final screen until your page removes it. sign_completed means this signer's signature was accepted; other signers may still be pending. See the SDK reference for every event and error code.

Confirming results on your server

Client-side browser events can fail to dispatch if the user closes their browser immediately after pressing Complete or drops connection. Always confirm completion server-to-server:

• Webhook notifications: Subscribe to signer.opened, signer.signed, signer.declined, envelope.completed and, where identity verification is used, signer.identity_verified and signer.identity_verification_blocked. There is no webhook when approvers approve or when a scheduled send goes out: poll the envelope for those.
• Query envelope status: Call GET /api/v1/inkfree/envelopes/{id} to inspect current completion status. The response carries each signer's deliveryMode and status, the approvers under approval.reviewers (with status and deliveryMode; no url for embedded approvers), scheduleTime and the signRequestConfig permissions.
• Download the signed PDF: Call GET /api/v1/inkfree/envelopes/{id}/document?signed=true to download the legal PDF and certificate. The signing frame offers a download button after signing unless the sender switched off signRequestConfig.allowDocumentDownload (on by default); the file is downloaded in the iframe, so keep the SDK's default sandbox. You can always fetch the signed file from your server instead.

Email notifications behavior