Skip to main content

​
Overview

The embed package editor feature allows you to integrate our package editor directly into your web application. This provides a seamless experience for users, enabling them to modify and template packages before they are sent without leaving your platform.

​
Package state

When embedding the package editor, it is recommended to set the package state to either add or draft.

​
Add add

By creating the package in an add state the package editor will guide the user through the package properties and templating the documents just like the native add package experience.
If you plan on updating an existing package and displaying the embedded package editor again you should set the state to add in your call to packages/update. If you do not set the state to add during the update, the package will automatically transition into a draft state. If the package has already been sent the state can no longer be transitioned back to add.

​
Draft draft

If you are adding all the signers and documents or disabling the editing of the package properties, then creating the package in a draft state with focusTemplating embed option is the preferred approach.

​
Steps

1

Add package

When you want to embed the package editor, you have to create a package with generateEditLink and the embedded package option set to true.
Request
POST /packages/add
{
    "name": "Embedded Package Editor",
    "type": "concurrent",
    "state": "draft",
    "generateEditLink": true,
    "options": {
        "embedded": true,
        "embed": {
            "focusTemplating": true
        }
    },
    "signers": [
        {
            "firstName": "signer",
            "lastName": "one",
            "email": "signer.one@example.com"
        }
    ],
    "documents": [
        {
            "fileName": "document.pdf",
            "fileId": "682f1158-e3f5-4329-8f88-c52cb5447d8c"
        }
    ]
}
Response
{
    "package": {
        ...
        "editLink": {
            "link": "https://sign.syngrafii.com/link/6iC4sCyjRaMTm2FcMjwIVA"
        },
        ...
    }
}

​
Embed options

You can customize the embedded package editor experience by setting additional embed options.
2

Embed edtior

To embed the package edtior in an iframe, you need to use the editLink.link provided in the add package response or by calling the Packages link API endpoint directly.
<iframe 
    id="editor-iframe"
    src="https://sign.syngrafii.com/link/6iC4sCyjRaMTm2FcMjwIVA"
></iframe>
If you are embedding existing packages consider generating a new edit link before embedding as they expire after 60 minutes.
3

Process embed messages

When embedding the package editor, you may want to handle certain events such as when the package is sent by the user. You can achieve this by listening for messages from the iframe.
window.addEventListener("message", (event) => {
    // Validate origin
    if (event.origin !== "https://sign.syngrafii.com" || !event.data) return;

    // Handle action
    switch (event.data.action) {
        case "package_close":
            // User has closed the package editor. You should continue with your workflow.
            break;
        case "package_send":
            // User has sent the package and closed the package editor. You should continue with your workflow.
            break;
        case "session_expired":
            // User session has expired. The package editor will show an Expired Session message
            break;
    }
}, false);
See the Embed messaging guide for more information.

​
Redirecting

If your workflow does not allow for embedding via iframe you can optionally redirect your users to the package edit link and have it redirect back to your site by setting the options.embed.returnUrl to a valid URL during the call to add package.
Request
POST /packages/add
{
  "name": "Embed Package Edtitor",
  "type": "concurrent",
  "state": "draft",
  "generateEditLink": true,
  "options": {
    "embed": {
      "focusTemplating": true,
      "returnUrl": "https://example.com/your-return-url",
      "returnState": "your-state"
    }
  },
  "signers": [
    {
      "firstName": "signer",
      "lastName": "one",
      "email": "signer.one@example.com"
    }
  ],
  "documents": [
    {
      "fileName": "document.pdf",
      "fileId": "682f1158-e3f5-4329-8f88-c52cb5447d8c"
    }
  ]
}