Embed editor

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

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.

Show options

boolean

Enable embedded signing mode.

object

Embed options used to customize the embedded package editor. 2.8

Show properties

boolean

User can only save changes to draft packages; the user will not be able to send it.

boolean

User will not be allowed to modify package properties.

boolean

User will not be allowed to modify package verification properties.

boolean

User will not be allowed to modify package signers.

boolean

User will not be allowed to modify package documents.

boolean

User will not be allowed to modify package properties, verification properties, signers, or documents. They will still be allowed to template each document.

boolean

The first document will be focused when the package editor is loaded instead of the package properties.

string

User will be redirected back to the returnUrl when they are done editing the package.

string

Will be included in a state query string parameter appended to the returnUrl.

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.

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"
    }
  ]
}

Getting started

Guides

API

Webhooks

Reference

Overview

Package `state`

Add `add`

Draft `draft`

Steps

Add package

Embed options

Embed edtior

Process embed messages

Redirecting

​Overview

​Package state

​Add add

​Draft draft

​Steps

Add package

​Embed options

Embed edtior

Process embed messages

​Redirecting

Overview

Package `state`

Add `add`

Draft `draft`

Steps

Embed options

Redirecting