Embedded sender widget

Overview

The embedded sender widget puts Inkfree's complete document preparation flow inside an iframe on your site. Users can upload agreements, configure signers, place required signature and input fields with visual drag-and-drop, customize email copy, and dispatch envelopes without ever creating or logging into an Inkfree account.

Your server makes two API calls: POST /api/v1/inkfree/embed/drafts creates a draft, and POST /api/v1/inkfree/embed/sessions mints the one-time token. Your page then mounts the widget with that token. Before you start, read the overview to create an API key and register your origin.

Create a draft

{
  "emailSubject": "Vendor Agreement",
  "signers": [
    { "id": 0, "name": "Ana Ruiz", "email": "ana@example.com", "deliveryMode": "EMBEDDED" }
  ],
  "files": [
    {
      "unsignedPdf": "contract.pdf",
      "fields": [
        { "type": "signature", "signerIndex": 0, "page": 0, "x": 72, "y": 650, "w": 160, "h": 40, "required": true },
        { "type": "date_signed", "signerIndex": 0, "page": 0, "x": 260, "y": 650, "w": 110, "h": 24 }
      ]
    }
  ]
}

curl -X POST "https://services.softsages.com/core/api/v1/inkfree/embed/drafts" \
  -H "X-API-Key: sk_live_YOUR_API_KEY" \
  -H "X-Idempotency-Key: YOUR_IDEMPOTENCY_KEY" \
  -F 'request={"emailSubject":"Vendor Agreement","emailMessage":"Please review and sign.","expirationDays":30,"signers":[{"id":0,"name":"Ana Ruiz","email":"ana@example.com","deliveryMode":"EMBEDDED"}]}' \
  -F 'files=@contract.pdf'

{
  "message": "c8a49c661ef54659b922097e3f89bf91",
  "code": 200,
  "correlationId": "01a1353b-cd8f-78ba-b868-d4e7246a9731"
}

Mint a creation 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": "creation",
    "requestId": "c8a49c661ef54659b922097e3f89bf91",
    "parentOrigin": "https://app.example.com"
  }'

{
  "token": "YOUR_ONE_TIME_TOKEN",
  "scope": "creation",
  "requestId": "c8a49c661ef54659b922097e3f89bf91",
  "expiresInSeconds": 300
}

Mounting in the frontend

Pass the minted token to your web page and call InkfreeEmbed.mount() with type: "create":

<div id="sender-widget" style="width: 100%; height: 850px;"></div>

<script src="https://sign.inkfree.app/embed/inkfree-embed.js"></script>
<script>
  var widget = InkfreeEmbed.mount({
    container: "#sender-widget",
    type: "create",
    token: token,
    minHeight: "820px",
    title: "Document Preparation"
  });

  widget.on("send_completed", function (event) {
    console.log("Envelope dispatched:", event.requestId);
    // Redirect or update parent UI
  });
</script>

The four steps walkthrough

Signers and delivery modes

• Signers added in the widget: They sign in your app (deliveryMode: "EMBEDDED"). Inkfree sends them no email or text: you mint a signing token for each of them when it is their turn and open the signing widget yourself. The user cannot change this inside the widget.
• Pre-filled signers: A signer you passed in the draft request keeps the mode you gave it (EMBEDDED or EMAIL; a signer with no mode counts as EMAIL), matched by email address. If the user changes a pre-filled signer's email in the widget, Inkfree treats it as a new signer, who signs in your app.
• Embedded signers: They need a valid email and cannot be CC recipients. The user can protect them with an access code, a one-time code by email or a one-time code by text (or identity verification where it is set up); the signer is asked for it inside your iframe before the document opens. There is no "Deliver via" choice for them, because Inkfree sends them nothing, and they cannot be sent a link by SMS. On the signing widget they cannot delegate, and they can download the documents unless the sender switched off "Download documents" in Step 4.
• Email signers: They get the account's normal invitation, reminders and completion email. Their Inkfree signing link is the signer's url in GET /api/v1/inkfree/envelopes/{id}; minting a signing token for them fails with SIGNER_NOT_EMBEDDED.
• Approvers: Every approver on a draft is EMBEDDED. Inkfree sends them nothing; you open the signing widget for them with a token minted for their email, and they approve or reject inside your app (see Embedded approvers). The envelope response lists them under approval.reviewers with their status and deliveryMode, and no url.
• CC recipients: A CC recipient always receives the final copy by email.

After the draft is sent

Sending turns the draft into an envelope with the same id. The send_completed event carries the envelope's status in data.status, and your page should act on it:

• Pending: the signers are up. Read GET /api/v1/inkfree/envelopes/{id}, and for each EMBEDDED signer with status Pending mint a signing token and mount the signing widget when they are ready to sign. With a signing order, a signer whose turn has not come gets NOT_YOUR_TURN from the mint call; show them as waiting and try again after the earlier signers have signed (the signer.signed webhook tells you when). See Embedded signing.
• InReview: the user added approvers. For each approver with status Pending, mint a signing token with the approver's email and mount the signing widget; they approve or reject there (with an approval order, only the current approver gets a token, others get NOT_YOUR_TURN). The status becomes Pending once they have all approved, or Rejected if one rejects. There is no webhook for approval: use the widget's approval_completed and approval_rejected events as a hint and confirm by polling the envelope. A token for a signer before then fails with REQUEST_NOT_READY.
• Scheduled: the user scheduled the send. The envelope's scheduleTime says when it goes out and becomes Pending (or InReview first, with approvers). Poll after that time; minting earlier fails with REQUEST_NOT_READY.

The widget stays on its confirmation panel until your page removes it with widget.destroy(). The envelope response also carries signRequestConfig (the permissions the user chose) and each signer's and approver's deliveryMode, status and, for email signers, url.

Omitted features

These features are deliberately excluded from the sender widget: in-person signing, saved templates ("Choose Template"), cloud drive imports, the eSign-mode choice, and creating or editing custom fields (the account's existing custom fields can be placed). Everything else in Inkfree's own four-step wizard is available, subject to the account's plan: approvers (who approve inside your app), signing delays, SMS delivery, one-time codes and access codes, identity verification, signer permissions, scheduled sends, AI field detection, the AI assistant and AI insights.