Create embedded request link using multiple templates

The Merge Embedded Request will allow you to merge one or more templates with a document and generate a link that allows users to edit the merged document before sending it. This API is useful for streamlining document preparation, as it combines templates with a document and provides an easy way for users to make any final changes before sending.

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

Create embedded request link

post/v1-beta/template/mergeCreateEmbeddedRequestUrl

Generating a merge embedded request link follows a similar process as a standard template merge and send request, but it includes additional settings specific to the embedded editing experience. Please refer the Template merge and send article for the document API specific properties.

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

Asynchronous document processing

While merging the multiple templates, if you add additional files, the process of document send will be performed asynchronous. You will receive an embedded request URL and document ID immediately, but the uploaded document might be still processing in the background. In the mean time, you can see the progress of the document processing by opening the embedded create document URL in the browser.

To determine whether the embedded request has been successfully created, you must listen for the webhooks. The system will trigger either a DraftCreated event, indicating success, or a TemplateSendFailed event, indicating failure. In the event of failure, the system will provide an error message. It is imperative to address and resolve this error to ensure the embedded merge template process comepltes successfully in the next request.

Code snippet

curl --location --request POST 'https://api.boldsign.com/v1-beta/template/mergeCreateEmbeddedRequestUrl' \
    --header 'X-API-KEY: <api-key>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "redirectUrl": "https://yourapp.example/redirect",
        "showToolbar": true,
        "sendViewOption": "FillingPage",
        "showSaveButton": true,
        "showSendButton": true,
        "showPreviewButton": true,
        "showNavigationButtons": true,
        "showTooltip": false,
        "templateIds": [
          "1a62a39c-xxxx-xxxx-xxxx-c0a09ee3fc82", "01c19aef-xxxx-xxxx-xxxx-7178ef2e1036"
        ]
    }'


var apiClient = new ApiClient("https://api.boldsign.com", "Your-API-KEY");
var templateClient = new TemplateClient(apiClient);

// This is an example document id, add your own template id created from the web app upon usage.
string[] templateIds = new string[] { "0992eb79-ea24-4e95-887a-10aa82b30957",   "01c19aef-4e95-887a-ea24-7178ef2e1036" };
var templateRequest = new EmbeddedMergeTemplateRequest
{
    // customize page options
    SendViewOption = PageViewOption.PreparePage,
    Locale = Locales.EN,
    ShowToolbar = true,
    ShowNavigationButtons = true,
    ShowSaveButton = true,
    ShowPreviewButton = true,
    ShowSendButton = true,
    ShowTooltip = false,
    TemplateIds = templateIds
};

var documentCreated = await templateClient.MergeCreateEmbeddedRequestUrlAsync(templateRequest);

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

import boldsign

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

with boldsign.ApiClient(configuration) as api_client:
    
    template_api = boldsign.TemplateApi(api_client)
    
    form_field = [
        boldsign.FormField(
            fieldType="Signature",
            pageNumber=1,
            bounds=boldsign.Rectangle(
                x=100,
                y=100,
                width=100,
                height=50
            )
        ),
    ]

    role = boldsign.Role(
        signerRole="NewRole",
        roleIndex=4,
        signerName="David",
        signerEmail="david@cubeflakes.com",
        formFields=form_field,
        locale="EN"
    )

    merge_embedded_create_template_request = boldsign.EmbeddedMergeTemplateFormRequest(
        templateIds=["YOUR_TEMPLATE_ID", "YOUR_TEMPLATE_ID"],
        roles=[role],
        showToolbar=True,
        showNavigationButtons=True,
        showPreviewButton=True,
        showSendButton=True,
        showSaveButton=True,
        sendViewOption="PreparePage",
        locale="EN",
        showTooltip=False,
        enableSigningOrder=False,
        roleRemovalIndices=[1, 2],
        files=["YOUR_FILE_PATH"]
    )

    merge_create_embedded_request_url_template_response = template_api.merge_create_embedded_request_url_template(merge_embedded_create_template_request)

const axios = require('axios');
const response = await axios.post(
    'https://api.boldsign.com/v1-beta/template/mergeCreateEmbeddedRequestUrl',
    {
        'redirectUrl': ' https://yourapp.example/redirect', 
        'showToolbar': true, 
        'sendViewOption': 'FillingPage',
        'locale': 'EN',
        'showSaveButton': true, 
        'showSendButton': true, 
        'showPreviewButton': true, 
        'showNavigationButtons': true,
        'showTooltip': false,
        'templateIds': [
          '01c19aef-xxxx-xxxx-xxxx-7178ef2e1036', '6a80bba9-xxxx-xxxx-xxxx-5d4dcd5cb08a'
        ],
        'roles': [
            {
                'roleIndex': 3,
                'signerName': 'David',
                'signerEmail': 'david@cubeflakes.com',
                'formFields': [
                    {
                        'fieldType': 'Signature',
                        'pageNumber': 1,
                        'bounds': {
                            'x': 100,
                            'y': 100,
                            'width': 100,
                            'height': 50
                        }
                    }
                ]
            }
        ],
        'roleRemovalIndices': [1, 2]
    },
    {
        headers: { 
            'X-API-KEY': '<api-key>', 
            'Content-Type': 'application/json' 
        }
    }
);

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

$client = new Client();
$headers = [
  'X-API-KEY' => '<api-key>',
  'Content-Type' => 'application/json'
];
$body = '{
  "redirectUrl": "https://yourapp.example/redirect",
  "showToolbar": true,
  "sendViewOption": "FillingPage",
  "showSaveButton": true,
  "showSendButton": true,
  "locale": "EN",
  "showPreviewButton": true,
  "showNavigationButtons": true,
  "showTooltip": false,
  "roleRemovalIndices": [1, 2],
  "templateIds": [
          "1a62a39c-xxxx-xxxx-xxxx-c0a09ee3fc82", "01c19aef-xxxx-xxxx-xxxx-7178ef2e1036"
        ],
}';
$request = new Request('POST', 'https://api.boldsign.com/v1-beta/template/mergeCreateEmbeddedRequestUrl', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

Request body

templateIdsarray	These are the template IDs of the existing templates to be used for sending. One or more values can be specified.
RedirectUrlstring	The redirect URI will be redirected after the template creation process is complete. The string should be in URI format.
ShowToolbarboolean	Controls the visibility of the toolbar at the top of the template 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 template 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 template 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 template 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), 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 response

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

Create embedded request link using multiple templates