Embedded request

The Embedded request allows users to create, upload, and send documents on your website or mobile app using an iFrame, popup window, or new tab. It is beneficial when your application user needs to review or make other changes before sending it out for signature.

You can either create a new document or use an existing template in order to generate the embedded request link for embedding within your application.

The document created using the embedded request will remain in the draft state until the user completes and sends it out for signature.

Create embedded request link

post/v1/document/createEmbeddedRequestUrl

Generating the embedded request link is the same as sending the regular document, but with additional properties to customize the embedded process. For detailed information on the send document API specific properties, please refer to the Send document article.

This API supports both multipart/form-data and application/json content types.

Asynchronous document processing

The document creation process is asynchronous in nature. You will receive an embedded request URL and document ID immediately, but the uploaded document might still be processing in the background. In the meantime, if you open the embedded request URL in the browser, you will see the progress of the document processing.

Request body

RedirectUrlstring	The redirect URI will be redirected after the document creation process is completed. The string should be in URI format.
ShowToolbarboolean	Controls the visibility of the toolbar at the top of the document editor. Defaults to false.
SendViewOptionstring	Configures the initial view page to be loaded from the generated URL. The FillingPage is used to customize signers, authentication, etc. The PreparePage is used to configure signers form fields. Either PreparePage or FillingPage. Defaults to PreparePage.
ShowSaveButtonboolean	Controls the visibility of the `Save and Close` button from the `More Action` drop-down menu. Set to false if you don't want your users to save the document as draft instead of sending it out for signature. Defaults to true.
ShowSendButtonboolean	Controls the visibility of the `Send` button at the top right corner of the page. Set to false if you want your users to save the document as only drafts instead of sending it out for signature. Defaults to true.
ShowPreviewButtonboolean	Controls the visibility of the `Preview` button from the `More Action` drop-down menu. Set to false if you don't want your users to preview the document before sending it out for signature. Defaults to true.
ShowNavigationButtonsboolean	Controls the visibility of the `Back` button. Set to false if you don't want your users to navigate away from the current page. Defaults to true.
SendLinkValidTillstring	Configures the expiration for the generated URL. A maximum of 180 days can be assigned. The String should be in date-time format.
Localestring	By default, while opening the embedded request link, all the static contents available in the page will be loaded in the English language. This property is used to load the contents with different languages. The supported languages are EN(English), FR(French), NO(Norwegian), DE(German), ES(Spanish), BG(Bulgarian), CS(Czech), DA(Danish), IT(Italian), NL(Dutch), PL(Polish), PT(Portuguese), RO(Romanian), RU(Russian), and SV(Swedish)
ShowTooltipboolean	To control the visibility of the `Tooltip` near the assignee field on the prepare page, set it to "true" if you want to show the tooltip to the user. Defaults to false.
allowScheduledSendboolean	This property enables or disables the scheduling option. When enabled, it allows scheduling the document for future sending. The default value is `false`.

Example request using multipart/form-data

curl -X POST 'https://api.boldsign.com/v1/document/createEmbeddedRequestUrl' \
    -H 'X-API-KEY={your API key}' \
    -F 'Title=Sent from API Curl' \
    -F 'ShowToolbar=true' \
    -F 'ShowNavigationButtons=true' \
    -F 'ShowPreviewButton=true' \
    -F 'ShowSendButton=true' \
    -F 'ShowSaveButton=true' \
    -F 'SendViewOption=PreparePage' \
    -F 'ShowTooltip=false' \
    -F 'Locale=EN' \
    -F 'SendLinkValidTill=2022-10-21T06:37:57.424Z' \
    -F 'RedirectUrl=https://boldsign.dev/sign/redirect' \
    -F 'Message=This is document message sent from API Curl' \
    -F 'EnableSigningOrder=false' \
    -F 'Signers[0][Name]=Signer Name 1' \
    -F 'Signers[0][EmailAddress]=alexgayle@cubeflakes.com' \
    -F 'Signers[0][SignerOrder]=1' \
    -F 'Signers[0][authenticationCode]=1123' \
    -F 'Signers[0][PrivateMessage]=This is private message for signer' \
    -F 'Signers[0][FormFields][0][FieldType]=Signature' \
    -F 'Signers[0][FormFields][0][Id]=Sign' \
    -F 'Signers[0][FormFields][0][PageNumber]=1' \
    -F 'Signers[0][FormFields][0][IsRequired]=True' \
    -F 'Signers[0][FormFields][0][Bounds][X]=50' \
    -F 'Signers[0][FormFields][0][Bounds][Y]=50' \
    -F 'Signers[0][FormFields][0][Bounds][Width]=200' \
    -F 'Signers[0][FormFields][0][Bounds][Height]=30' \
    -F 'Files=@NDA.pdf;type=application/pdf'

var apiClient = new ApiClient("YOUR_API_KEY");

var documentClient = new DocumentClient(apiClient);

List<FormField> formField = new List<FormField>
{
    new FormField(
        id: "Signature",
        type: FieldType.Signature,
        pageNumber: 1,
        bounds: new Rectangle(x: 50, y: 50, width: 200, height: 30))
};

var documentRequest = new EmbeddedDocumentRequest
{
    Title = "Sent from API SDK",
    Signers = new List<DocumentSigner>
    {
        new DocumentSigner(
            signerName: "David",
            signerType: SignerType.Signer,
            signerEmail: "david@cubeflakes.com",
            formFields: formField)
    },
    Files = new List<IDocumentFile>
    {
        new DocumentFilePath
        {
            ContentType = "application/pdf",
            FilePath = "YOUR_FILE_PATH",
        }
    },
    SendViewOption = PageViewOption.PreparePage,
    ShowToolbar = true
};

var embeddedSendCreated = documentClient.CreateEmbeddedRequestUrl(documentRequest);
var documentSendUrl = embeddedSendCreated.SendUrl;

import boldsign

configuration = boldsign.Configuration(api_key="YOUR_API_KEY")

with boldsign.ApiClient(configuration) as api_client:
    
    document_api = boldsign.DocumentApi(api_client)
	
    form_field = boldsign.FormField(
        fieldType="Signature",
        pageNumber=1,
        bounds=boldsign.Rectangle(x=50, y=50, width=200, height=30))
       
    document_signer = boldsign.DocumentSigner(
        name="Signer Name 1",
        emailAddress="signer1@boldsign.dev",
        signerType="Signer",
        formFields=[form_field])
    
    embedded_document_request = boldsign.EmbeddedDocumentRequest(
        title="Sent from API Python SDK",
        showToolbar=True,
        sendViewOption="FillingPage",
        signers=[document_signer],
        files=["YOUR_FILE_PATH"])
    
    embedded_send_created = document_api.create_embedded_request_url_document(embedded_document_request)

<?php require_once "vendor/autoload.php";

use BoldSign\Configuration;
use BoldSign\Api\DocumentApi;
use BoldSign\Model\{FormField, Rectangle, DocumentSigner, EmbeddedDocumentRequest};

$config = new Configuration();
$config->setApiKey('YOUR_API_KEY');

$document_api = new DocumentApi($config);

$form_field = new FormField();
$form_field->setFieldType('Signature');
$form_field->setPageNumber(1);
$bounds = new Rectangle([50, 100, 100, 60]);
$form_field->setBounds($bounds);

$document_signer = new DocumentSigner();
$document_signer->setName('Signer Name 1');
$document_signer->setEmailAddress('signer1@boldsign.dev');
$document_signer->setSignerType('Signer');
$document_signer->setFormFields([$form_field]);

$embedded_document_request = new EmbeddedDocumentRequest();
$embedded_document_request->setTitle('Sent from API Php SDK');
$embedded_document_request->setSendViewOption('FillingPage');
$embedded_document_request->setShowToolbar(true);
$embedded_document_request->setSigners([$document_signer]);
$embedded_document_request->setFiles(['YOUR_FILE_PATH']);

$embedded_send_created = $document_api->createEmbeddedRequestUrlDocument($embedded_document_request);

ApiClient client = Configuration.getDefaultApiClient();
client.setApiKey("YOUR_API_KEY");

DocumentApi documentApi = new DocumentApi(client);

FormField signatureField = new FormField();
signatureField.setFieldType(FormField.FieldTypeEnum.SIGNATURE);
signatureField.setPageNumber(1);
Rectangle bounds = new Rectangle().x(100f).y(100f).width(100f).height(50f);
signatureField.setBounds(bounds);

DocumentSigner signer = new DocumentSigner();
signer.setName("Signer Name 1");
signer.setEmailAddress("signer1@boldsign.dev");
signer.setSignerType(DocumentSigner.SignerTypeEnum.SIGNER);
signer.setFormFields(Arrays.asList(signatureField));
				
EmbeddedDocumentRequest embeddedDocumentRequest = new EmbeddedDocumentRequest();
File file = new File("YOUR_FILE_PATH");  
embeddedDocumentRequest.setFiles(Arrays.asList(file));
embeddedDocumentRequest.setSigners(Arrays.asList(signer));
embeddedDocumentRequest.setSendViewOption(EmbeddedDocumentRequest.SendViewOptionEnum.FILLING_PAGE);
embeddedDocumentRequest.setShowToolbar(true);
embeddedDocumentRequest.setTitle("Sent from API java SDK");

EmbeddedSendCreated embeddedSendCreated = documentApi.createEmbeddedRequestUrlDocument(embeddedDocumentRequest);

import { DocumentApi, DocumentSigner, EmbeddedDocumentRequest, FormField, Rectangle } from "boldsign"; 
import * as fs from 'fs';

const documentApi = new DocumentApi();
documentApi.setApiKey("YOUR_API_KEY");

const bounds = new Rectangle();
bounds.x = 100;
bounds.y = 50;
bounds.width = 100;
bounds.height = 100;

const formField = new FormField();
formField.fieldType = FormField.FieldTypeEnum.Signature;
formField.pageNumber = 1;
formField.bounds = bounds;

const documentSigner = new DocumentSigner();
documentSigner.name = "Signer Name 1";
documentSigner.emailAddress = "signer1@boldsign.dev";
documentSigner.signerType = DocumentSigner.SignerTypeEnum.Signer;
documentSigner.formFields = [formField];

const files = fs.createReadStream("YOUR_FILE_PATH");

const embeddedDocumentRequest = new EmbeddedDocumentRequest();
embeddedDocumentRequest.title = "Sent from API Node SDK";
embeddedDocumentRequest.showToolbar = true;
embeddedDocumentRequest.sendViewOption = EmbeddedDocumentRequest.SendViewOptionEnum.FillingPage;
embeddedDocumentRequest.files = [files];
embeddedDocumentRequest.signers = [documentSigner];

const embeddedSendCreated = documentApi.createEmbeddedRequestUrlDocument(embeddedDocumentRequest);

Example request using application/json

curl -X POST 'https://api.boldsign.com/v1/document/createEmbeddedRequestUrl' \
    -H 'X-API-KEY: {your API key}' \
    -H 'Content-Type: application/json' \
    -d '{
        "Title": "Sent from API Curl",
        "ShowToolbar": true,
        "ShowNavigationButtons": true,
        "ShowPreviewButton": true,
        "ShowSendButton": true,
        "ShowSaveButton": true,
        "SendViewOption": "PreparePage",
        "ShowTooltip": false,
        "Locale": "EN",
        "SendLinkValidTill": "2022-10-21T06:37:57.424Z",
        "RedirectUrl": "https://boldsign.dev/sign/redirect",
        "Message": "This is document message sent from API Curl",
        "EnableSigningOrder": false,
        "Signers": [
            {
                "Name": "Signer Name 1",
                "EmailAddress": "alexgayle@cubeflakes.com",
                "SignerOrder": 1,
                "authenticationCode": "1123",
                "PrivateMessage": "This is private message for signer",
                "FormFields": [
                    {
                        "FieldType": "Signature",
                        "Id": "Sign",
                        "PageNumber": 1,
                        "IsRequired": true,
                        "Bounds": {
                            "X": 50,
                            "Y": 50,
                            "Width": 200,
                            "Height": 30
                        }
                    }
                ]
            }
        ],
        "Files": [
            "data:application/pdf;base64,JVBERi0xLjcKJcfs..." 
        ]
    }'

Example response

{
    "documentId": "625cff3d...",
    "sendUrl": "https://app.boldsign.com/document/embed/?documentId=625cff3d..."
}