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.

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("https://api.boldsign.com", "Your-API-KEY");

var documentClient = new DocumentClient(apiClient);

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

var documentRequest = new EmbeddedDocumentRequest
{
    Title = "Sent from API SDK",
    Message = "This is document message sent from API SDK",
    EnableSigningOrder = true,
    Signers = new List<DocumentSigner>
    {
        new DocumentSigner(
            name: "Signer Name 1",
            emailAddress: "signer1@boldsign.dev",
            signerOrder: 1,
            authenticationCode: "123",
            signerType: SignerType.Signer,
            privateMessage: "This is private message for signer",
            formFields: formFields),
    },
    Files = new List<IDocumentFile>
    {
        new DocumentFileStream
        {
            ContentType = "application/pdf",
            FileData = fileStream,
            FileName = "NDA1.pdf",
        },
        new DocumentFileBytes()
        {
            ContentType = "application/pdf",
            FileData = fileByteArray,
            FileName = "NDA2.pdf",
        },
        new DocumentFilePath
        {
            ContentType = "application/pdf",

            // directly provide file path
            FilePath = "NDA3.pdf",
        },
    },

    // customize page options
    SendViewOption = PageViewOption.PreparePage,
    Locale = Locales.EN,
    ShowToolbar = true,
    ShowNavigationButtons = true,
    ShowSaveButton = true,
    ShowPreviewButton = true,
    ShowSendButton = true,
	  SendLinkValidTill = DateTime.UtcNow.AddHours(2),
    ShowTooltip = false,
};

var documentCreated = await documentClient.CreateEmbeddedRequestUrlAsync(documentRequest);

// url to send the document from your web application
var documentSendUrl = documentCreated.SendUrl;

import requests

url = "https://api.boldsign.com/v1/document/createEmbeddedRequestUrl"

payload={'Title': 'Sent from API Curl',
'ShowToolbar': 'true',
'ShowNavigationButtons': 'true',
'ShowPreviewButton': 'true',
'ShowSendButton': 'true',
'ShowSaveButton': 'true',
'SendViewOption': 'FillingPage',
'Locale': 'EN',
'SendLinkValidTill': '2022-10-21T06:37:57.424Z',
'ShowTooltip': 'false',
'RedirectUrl': 'https://boldsign.dev/sign/redirect',
'Message': 'This is document message sent from API Curl',
'EnableSigningOrder': 'false',
'Signers[0][Name]': 'Signer Name 1',
'Signers[0][EmailAddress]': 'signer1@boldsign.dev',
'Signers[0][SignerOrder]': '1',
'Signers[0][authenticationCode]': '1123',
'Signers[0][PrivateMessage]': 'This is private message for signer',
'Signers[0][FormFields][0][FieldType]': 'Signature',
'Signers[0][FormFields][0][Id]': 'Sign',
'Signers[0][FormFields][0][PageNumber]': '1',
'Signers[0][FormFields][0][IsRequired]': 'True',
'Signers[0][FormFields][0][Bounds][X]': '50',
'Signers[0][FormFields][0][Bounds][Y]': '50',
'Signers[0][FormFields][0][Bounds][Width]': '200',
'Signers[0][FormFields][0][Bounds][Height]': '30'}
files=[
  ('Files',('file',open('{file path}','rb'),'application/octet-stream'))
]
headers = {
  'X-API-KEY': '{your API key}'
}

response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.text)

const axios = require('axios'); 
const FormData = require('form-data'); 
const fs = require('fs'); 
const form = new FormData(); 
form.append('Title', 'Sent from API Curl'); 
form.append('ShowToolbar', 'true'); 
form.append('ShowNavigationButtons', 'true'); 
form.append('ShowPreviewButton', 'true'); 
form.append('ShowSendButton', 'true'); 
form.append('ShowSaveButton', 'true'); 
form.append('ShowSaveButton', 'true');
form.append('Locale', 'EN');
form.append('SendLinkValidTill', '12-22-2022 12:00 PM'); 
form.append('ShowTooltip', 'false');
form.append('RedirectUrl', ' https://boldsign.dev/sign/redirect'); 
form.append('Message', 'This is document message sent from API Curl'); 
form.append('EnableSigningOrder', 'false'); 
form.append('Signers[0][Name]', 'Signer Name 1'); 
form.append('Signers[0][EmailAddress]', 'signer1@boldsign.dev'); 
form.append('Signers[0][SignerOrder]', '1'); 
form.append('Signers[0][authenticationCode]', '1123'); 
form.append('Signers[0][PrivateMessage]', 'This is private message for signer'); 
form.append('Signers[0][FormFields][0][FieldType]', 'Signature'); 
form.append('Signers[0][FormFields][0][Id]', 'Sign'); 
form.append('Signers[0][FormFields][0][PageNumber]', '1'); 
form.append('Signers[0][FormFields][0][IsRequired]', 'True'); 
form.append('Signers[0][FormFields][0][Bounds][X]', '50'); 
form.append('Signers[0][FormFields][0][Bounds][Y]', '50'); 
form.append('Signers[0][FormFields][0][Bounds][Width]', '200'); 
form.append('Signers[0][FormFields][0][Bounds][Height]', '30'); 
form.append('Files', fs.readFileSync('NDA.pdf;type=application/pdf'), 'NDA.pdf;type=application/pdf'); 
const response = await axios.post( 

    ' https://api.boldsign.com/v1/document/createEmbeddedRequestUrl', 

    form, 
    { 
        headers: { 
            ...form.getHeaders(), 
            'Authorization': 'Bearer <access-token>' 
        } 
    } 
);

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

import requests

# URL and API key
url = "https://api.boldsign.com/v1/document/createEmbeddedRequestUrl"
api_key = "{your API key}"


# Payload
payload = {
    "Title": "Sent from API Curl",
    "ShowToolbar": True,
    "ShowNavigationButtons": True,
    "ShowPreviewButton": True,
    "ShowSendButton": True,
    "ShowSaveButton": True,
    "SendViewOption": "FillingPage",
    "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": "signer1@boldsign.dev",
            "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..."
    ]
}

# Headers
headers = {
    "X-API-KEY": api_key,
    "Content-Type": "application/json",
    "accept": "application/json"
}

# Make the request
response = requests.post(url, headers=headers, json=payload)

# Print response
print(response.text)

const axios = require('axios');
const fs = require('fs');

// Payload
const payload = {
    Title: 'Sent from API Curl',
    ShowToolbar: true,
    ShowNavigationButtons: true,
    ShowPreviewButton: true,
    ShowSendButton: true,
    ShowSaveButton: true,
    ShowTooltip: false,
    Locale: 'EN',
    SendLinkValidTill: '2022-12-22T12:00:00Z',
    RedirectUrl: 'https://boldsign.dev/sign/redirect',
    Message: 'This is document message sent from API Curl',
    EnableSigningOrder: false,
    Signers: [
        {
            Name: 'Signer Name 1',
            EmailAddress: 'signer1@boldsign.dev',
            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...'
    ]
};

// Make the request
const response = await axios.post(
    'https://api.boldsign.com/v1/document/createEmbeddedRequestUrl',
    payload,
    {
        headers: {
            'X-API-KEY': '{Your API Key}',
            'Content-Type': 'application/json',
            'accept': 'application/json'
        }
    }
);

// Print response
console.log(response.data);

<?php
require_once "vendor/autoload.php";
use GuzzleHttp\Client;


// Payload
$payload = [
    'Title' => 'Sent from API Curl',
    'ShowToolbar' => true,
    'ShowNavigationButtons' => true,
    'ShowPreviewButton' => true,
    'ShowSendButton' => true,
    'ShowSaveButton' => true,
    'ShowTooltip' => false,
    'SendViewOption' => 'PreparePage',
    '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...'
    ]
];

$client = new Client();
$headers = [
    'accept' => 'application/json',
    'X-API-KEY' => 'Your-API-KEY',
    'Content-Type' => 'application/json'
];

$response = $client->post('https://api.boldsign.com/v1/document/createEmbeddedRequestUrl', [
    'headers' => $headers,
    'json' => $payload
]);

echo $response->getBody();

Example response

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