Embedded Signing

View our Pricing & Plans for a detailed list and comparison of features available in each plan.

Docubee supports embedded signing on your website. Embedded signing allows you to integrate document preparation, sending, and signing into your existing website or application. It provides a secure and cohesive user experience.

This article includes:

• configuring a Docubee account to support embedded signing and then to handle the actual signing process in an embedded interface.

Before you Begin

To embed workflows you need to prepare the workspace and follow some general guidelines:

1. Organization plan – The organization must be on a plan that supports Embedded UI and API Access. 
   • The Sales or Customer Success teams will assign these features for both trial / development and production environments.
2. Workspace API Access Tokens – The workspace (belonging to the above organization) must have one or more API access tokens generated that have the following permissions:
   • Upload Documents
   • Set Document Fields
   • Start Quick Sign
   • Complete Signing of Quick Sign Documents
   • Generate Embedded UI URL
3. Matching formDefinitionId – The formDefinitionId for both the field placement and signing processes must match. This can be any valid value, per the API documentation, but the fields will only show if the same string is used in both cases.

Integrate Embedded Signing

It is an end-to-end handling of a document signing process and includes the following steps:

1. Upload a document to your website
2. Prepare it for signing by providing an embedded UI for placing fields
3. Start a signature process
4. Request a recipient’s by providing an embedded UI for the signing process
5. Track the signing status in embedded signing

You can handle many of these steps in numerous ways. This article assumes that you will use embedded interfaces and the Docubee API where possible.

Upload a Document

POST https://docubee.app/api/v2/documents

You must be sure to set the appropriate Content-Type header for the type of document being uploaded for the server to process the document correctly. The response will contain a documentId in the body that is used in the following steps. For details, see our public API documentation for Upload.

Provide an Embedded UI for Placing Fields

POST https://docubee.app/api/v2/embed

(This is a currently documented endpoint.) Takes a definition for an embeddable interface and returns a URL that can be embedded in a parent application to give the user the ability to perform the defined function. In this case, you can prepare the document for signing by using the embedded interface to place fields on the provided document. The Content-Type will be “application/json”.
The request body:

{
  "data": {
    "documentId": documentId,
    "formDefinitionId": "my_form"
  },
  "domain": "https://secure.mydomain.com:*",
  "page": "fieldPlacement"
}

This will return a URL that can be embedded in an iFrame on the provided domain.

If you want to map data from your system onto a document with our field mapping, you need to identify the fields to be mapped with the configuration array. Here’s a sample request body:

{
  "data": {
    "configuration": {
      "mappedData": [
  {
          "id": "MY_TEXTFIELD_ID",
          "label": "First_Name",
          "templates": [ "TextTemplate" ]
        },
        {
          "id": "MY_DATE_FIELD_ID",
          "label": "Current_Date",
          "templates": [ "DateTemplate" ]
        }
      ],
      "roles": [
        { "displayName": "First Signer", "formRoleId": "formRole1" },
        { "displayName": "Second Signer", "formRoleId": "formRole2" }
      ]
    },
    "documentId": documentId,
    "formDefinitionId": "my_form"
  },
  "domain": "https://secure.mydomain.com:*",
  "page": "fieldPlacement"
}

This will return a URL that can be embedded in an iFrame on the provided domain and will have dropdowns for the mapped fields.

Start a Signature Process

POST https://docubee.app/api/v2/signatures

This will have a Content-Type of “application/json” and the body details are available in our public API documentation for Start Signature Process.

To support embedding of the signing interface, each “signer” should have a “contactMethod” of “type”: “embed”. This will return results for each signer having an object containing a signerId and the signature process as a whole will have a processId. Both of these are used in the embedded interface.

Sample body:

{
  "documents": [{
    "documentId": documentId,
    "formDefinitionId": "my_form"
  }],
  "signers": [{
    "label": "My Signer",
    "contactMethod": [{
      "type": "embed"
    }]
  }]
}

If you have mappedData fields, you can pass your data into those fields. Here’s a sample body:

{
  "documents": [{
    "documentId": documentId,
    "formDefinitionId": "my_form"
  }],
  "fieldData": {
    "MY_TEXTFIELD_ID": "John",
    "MY_DATE_FIELD_ID": "1/25/2024"
  },
  "signers": [{
    "label": "My Signer",
    "contactMethod": [{
      "type": "embed"
    }]
  }]
}

Provide an Embedded UI for the Signing Process

POST https://docubee.app/api/v2/embed

(This is a currently documented endpoint.) Takes a definition for an embeddable interface and returns a URL that can be embedded in a parent application that enables the user to perform the defined function. In this case, it will create the interface to complete the signing for a specified user/recipient. It will have a Content-Type of “application/json”.

The body of the request:

{
  "data": {
    "processId": processId,
    "signerId": signerId
  },
  "domain": "https://secure.mydomain.com:*",
  "page": "signing"
}

This will return a URL that can be embedded in an iFrame on the provided domain.

Track Signing Status in Embedded Signing

Once the embedded frame loads with the signing interface, the application will emit events to the parent using postMessage. You can listen for the specific changes in state to trigger navigation, content, or removal of the iFrame from the page by using addEventListener.

The code example below shows how to listen for events that come from the iFrame:

window.addEventListener('message', (message) => {
  if (!message.origin.includes('docubee.app')) {
    return;
  }

  const { details, event } = JSON.parse(message.data);

  if (event !== 'SIGNING_STATUS') {
    return;
  }

  // details.status can be used to trigger changes
}, false);

Once you have the specific event, you can add your own handlers within your product.

Related Information

Docubee API Reference
Embed eSignatures on Your Site or Application
Glossary
Additional Resources

Need more help getting set up? Contact us for assistance from our customer support team.