Document
A document is also known as an envelope. It acts as an overall container for BoldSign transactions. A document in BoldSign contains one or more files, in which the signature will be added electronically, details about the sender and signers, status, history, etc. Each document has a unique ID, and you can use that for identifying or fetching the document.
Using BoldSign, you can send documents to others for eSignatures. In addition, you can perform various operations like self-sign, sign the document as a recipient, send the document on behalf of another user, add authentication, remind signers, delete a document, get document details, get a document list, etc.
Asynchronous document processing
The process of document send is asynchronous. Although you will promptly receive the document ID upon initiation, the actual file may still be undergoing processing in the background. To determine whether the document has been successfully sent, you must listen for the webhooks.
The system will trigger either a Sent
or SendFailed
event, indicating the success or failure of the document transmission, respectively. In the event of failure, the system will send a SendFailed
event along with an accompanying error message. It is imperative to address and resolve this error to ensure the proper sending of the document in the next request.
Document not found
If you discover that a document is not present in your account even after receiving a documentId
in the API response, it is directly tied to the asynchronous document processing, as explained in the preceding section. To ascertain whether the document has been successfully created, you should actively monitor the Sent
and SendFailed
webhook events. These events will provide confirmation regarding the status of the document, indicating whether it has been successfully created or if an issue has occurred during the process.
Send documents
post/v1/document/sendYou can request signatures from others by sending the documents for signing. It is not mandatory for the signers to have a BoldSign account. Thus, the signer can sign a document sent by another user with or without a BoldSign account. If required, you can also add yourself as one of the signers. To self-sign a document, you can send a signature request to yourself alone. This API supports both multipart/form-data
and application/json
content types.
Code snippet using multipart/form-data
curl -X 'POST' \ 'https://api.boldsign.com/v1/document/send' \ -H 'accept: application/json' \ -H 'X-API-KEY: {your API key}' \ -H 'Content-Type: multipart/form-data' \ -F 'DisableExpiryAlert=false' \ -F 'ReminderSettings.ReminderDays=5' \ -F 'BrandId=' \ -F 'ReminderSettings.ReminderCount=3' \ -F 'EnableReassign=true' \ -F 'Message=' \ -F 'Signers={ "name": "sdc", "emailAddress": "alexgayle@cubeflakes.com", "signerType": "Signer", "formFields": [ { "id": "string", "name": "string", "fieldType": "Signature", "pageNumber": 1, "bounds": { "x": 50, "y": 50, "width": 1, "height": 1 }, "isRequired": true }, { "id": "string", "name": "string", "fieldType": "Label", "pageNumber": 1, "bounds": { "x": 150, "y": 250, "width": 1, "height": 1 }, "isRequired": true, "backgroundHexColor": "string" } ], "locale": "EN" }' \ -F 'ExpiryDays=30' \ -F 'EnablePrintAndSign=false' \ -F 'AutoDetectFields=false' \ -F 'OnBehalfOf=' \ -F 'EnableSigningOrder=false' \ -F 'UseTextTags=false' \ -F 'SendLinkValidTill=' \ -F 'FileUrls=string' \ -F 'Title=dcsd' \ -F 'HideDocumentId=false' \ -F 'EnableEmbeddedSigning=false' \ -F 'ExpiryDateType=Days' \ -F 'ReminderSettings.EnableAutoReminder=true' \ -F 'ExpiryValue=60' \ -F 'DisableEmails=false' \ -F 'DisableSMS=false' \ -F 'MetaData={ "DocumentType": "new", "DocumentCategory": "software" }' \
var apiClient = new ApiClient("https://api.boldsign.com", "{your API key}"); var documentClient = new DocumentClient(apiClient); var documentFilePath = new DocumentFilePath { ContentType = "application/pdf", FilePath = "agreement.pdf", }; var filesToUpload = new List<IDocumentFile> { documentFilePath, }; var signatureField = new FormField( id: "sign", isRequired: true, type:FieldType.Signature, pageNumber: 1, bounds: new Rectangle(x: 100, y: 100, width: 100, height: 50)); var labelField = new FormField( id: "label", isRequired: true, type: FieldType.Label, pageNumber: 1, bounds: new Rectangle(x: 200, y: 400, width: 100, height: 50)); labelField.BackgroundHexColor = "#FFFFFF"; var formFieldCollections = new List<FormField>() { signatureField, labelField }; var signer = new DocumentSigner( signerName: "David", signerType: SignerType.Signer, signerEmail: "david@cubeflakes.com", formFields: formFieldCollections, locale: Locales.EN); var documentSigners = new List<DocumentSigner>() { signer }; var metaData = new Dictionary<string, string>() { ["DocumentType"] = "new", ["DocumentCategory"] = "software", }; var sendForSign = new SendForSign() { Message = "please sign this", Title = "Agreement", HideDocumentId = false, Signers = documentSigners, Files = filesToUpload, MetaData = metaData }; var documentCreated = documentClient.SendDocument(sendForSign);
import boldsign configuration = boldsign.Configuration( api_key = "YOUR_API_KEY" ) with boldsign.ApiClient(configuration) as api_client: document_api = boldsign.DocumentApi(api_client) form_fields = [ boldsign.FormField( fieldType="Signature", pageNumber=1, bounds=boldsign.Rectangle( x=50, y=50, width=200, height=25 ) ), boldsign.FormField( fieldType="Label", value="Label Field", pageNumber=1, bounds=boldsign.Rectangle( x=150, y=250, width=200, height=25 ) ), ] document_signer = boldsign.DocumentSigner( name="David", emailAddress="david@cubeflakes.com", signerOrder=1, signerType="Signer", formFields=form_fields, locale="EN" ) send_for_sign = boldsign.SendForSign( document_title = "SDK Document Test case", description="Testing document from SDK integration test case", files=["YOUR_FILE_PATH"], disableExpiryAlert=False, reminderSettings=boldsign.ReminderSettings( reminderDays=3, reminderCount=5, enableAutoReminder=False ), enableReassign=True, message='Please sign this.', signers=[document_signer], expiryDays=10, enablePrintAndSign=False, AutoDetectFields=False, onBehalfOf='', enableSigningOrder=False, useTextTags=False, title="Document SDK API", hideDocumentId=False, enableEmbeddedSigning=False, expiryDateType='Days', expiryDate=60, disableEmails=False, disableSMS=False, ) send_document_response = document_api.send_document(send_for_sign)
const axios = require("axios"); const FormData = require("form-data"); const fs = require("fs"); const form = new FormData(); form.append("DisableExpiryAlert", "false"); form.append("ReminderSettings.ReminderDays", "3"); form.append("BrandId", ""); form.append("ReminderSettings.ReminderCount", "5"); form.append("EnableReassign", "true"); form.append("Message", "Please sign this."); form.append( "Signers", '{\n "name": "David",\n "emailAddress": "david@cubeflakes.com",\n "formFields": [\n {\n "fieldType": "Signature",\n "pageNumber": 1,\n "bounds": {\n "x": 100,\n "y": 100,\n "width": 100,\n "height": 50\n },\n "isRequired": true,\n "backgroundHexColor": "string"\n }\n ]\n}' ); form.append("ExpiryDays", "10"); form.append("EnablePrintAndSign", "false"); form.append("AutoDetectFields", "false"); form.append("OnBehalfOf", ""); form.append("EnableSigningOrder", "false"); form.append("UseTextTags", "false"); form.append("SendLinkValidTill", ""); form.append("Files", fs.readFileSync("agreement.pdf"), { filename: "agreement.pdf", contentType: "application/pdf", }); form.append("Title", "Agreement"); form.append("HideDocumentId", "false"); form.append("EnableEmbeddedSigning", "false"); form.append("ExpiryDateType", "Days"); form.append("ReminderSettings.EnableAutoReminder", "false"); form.append("ExpiryValue", "60"); form.append("DisableEmails", "false"); form.append("DisableSMS", "false"); form.append( "metaData", JSON.stringify({ DocumentType: "new", DocumentCategory: "software", }) ); const response = await axios.post( "https://api.boldsign.com/v1/document/send", form, { headers: { ...form.getHeaders(), accept: "application/json", "X-API-KEY": "{your API key}", "Content-Type": "multipart/form-data", }, } );
Code snippet using application/json
curl -X 'POST' \ 'https://api.boldsign.com/v1/document/send' \ -H 'accept: application/json' \ -H 'X-API-KEY: {your API key}' \ -H 'Content-Type: application/json' \ -d '{ "DisableExpiryAlert": false, "ReminderSettings": { "ReminderDays": 5, "ReminderCount": 3, "EnableAutoReminder": true }, "BrandId": "", "EnableReassign": true, "Message": "", "Signers": [ { "name": "Alex", "emailAddress": "alexgayle@boldsign.dev", "signerType": "Signer", "formFields": [ { "id": "string", "name": "string", "fieldType": "Signature", "pageNumber": 1, "bounds": { "x": 50, "y": 50, "width": 125, "height": 25 }, "isRequired": true } { "id": "string", "name": "string", "fieldType": "Label", "pageNumber": 1, "bounds": { "x": 150, "y": 250, "width": 125, "height": 25 }, "isRequired": true, "backgroundHexColor": "string" } ], "locale": "EN" } ], "ExpiryDays": 30, "EnablePrintAndSign": false, "AutoDetectFields": false, "OnBehalfOf": "", "EnableSigningOrder": false, "UseTextTags": false, "SendLinkValidTill": "", "Files": [ "data:application/pdf;base64,JVBERi0xLjcKJcfs..." ], "Title": "Sampledocument", "HideDocumentId": false, "EnableEmbeddedSigning": false, "ExpiryDateType": "Days", "ExpiryValue": 60, "DisableEmails": false, "DisableSMS": false, "MetaData": { "DocumentType": "new", "DocumentCategory": "Software" } }'
import requests import json url = "https://api.boldsign.com/v1/document/send" signer_data = { "name": "David", "emailAddress": "david@boldsign.dev", "signerType": "Signer", "formFields": [ { "id": "string", "name": "string", "fieldType": "Signature", "pageNumber": 1, "bounds": { "x": 50, "y": 50, "width": 200, "height": 25 }, "isRequired": True }, { "id": "string", "name": "string", "fieldType": "Label", "pageNumber": 1, "bounds": { "x": 150, "y": 250, "width": 200, "height": 25 }, "isRequired": True, "backgroundHexColor": "string" } ], "locale": "EN" } payload = { 'DisableExpiryAlert': 'false', 'ReminderSettings.ReminderDays': '3', 'BrandId': '', 'ReminderSettings.ReminderCount': '5', 'EnableReassign': 'true', 'Message': 'Please sign this.', 'Signers': [signer_data], 'Title': 'Agreement', 'Files': [ 'data:application/pdf;base64,JVBERi0xLjcKJcfs...' ], 'ExpiryDays': '10', 'EnablePrintAndSign': 'false', 'AutoDetectFields': 'false', 'OnBehalfOf': '', 'EnableSigningOrder': 'false', 'UseTextTags': 'false', 'SendLinkValidTill': '', 'HideDocumentId': 'false', 'EnableEmbeddedSigning': 'false', 'ExpiryDateType': 'Days', 'ReminderSettings.EnableAutoReminder': 'false', 'ExpiryValue': '60', 'DisableEmails': 'false', 'DisableSMS': 'false', 'MetaData': { 'DocumentType': 'new', 'DocumentCategory': 'Software' } } headers = { 'Content-Type': 'application/json', 'accept': 'application/json', 'X-API-KEY': '{your API key}' } response = requests.post(url, headers=headers, json=payload) print(response.text)
const axios = require('axios'); const fs = require('fs'); // Create the payload object const payload = { DisableExpiryAlert: false, ReminderSettings: { ReminderDays: 3, ReminderCount: 5, EnableAutoReminder: false }, BrandId: '', EnableReassign: true, Message: 'Please sign this.', Signers: [ { name: 'David', emailAddress: 'david@boldsign.dev', formFields: [ { fieldType: 'Signature', pageNumber: 1, bounds: { x: 100, y: 100, width: 100, height: 50 }, isRequired: true }, { fieldType: 'Label', pageNumber: 1, bounds: { x: 200, y: 400, width: 100, height: 50 }, isRequired: true, backgroundHexColor: 'string' } ] } ], ExpiryDays: 10, EnablePrintAndSign: false, AutoDetectFields: false, OnBehalfOf: '', EnableSigningOrder: false, UseTextTags: false, SendLinkValidTill: '', Files: [ 'data:application/pdf;base64,JVBERi0xLjcKJcfs...' ], Title: 'Agreement', HideDocumentId: false, EnableEmbeddedSigning: false, ExpiryDateType: 'Days', ExpiryValue: 60, DisableEmails: false, DisableSMS: false, MetaData: { 'DocumentType': 'new', 'DocumentCategory': 'Software' } }; const response = await axios.post( 'https://api.boldsign.com/v1/document/send', payload, { headers: { 'Content-Type': 'application/json', 'accept': 'application/json', 'X-API-KEY': '{your API key}' } } ); console.log(response.data);
<?php require_once "vendor/autoload.php"; use GuzzleHttp\Client; use GuzzleHttp\Psr7\Request; $client = new Client(); $headers = [ 'accept' => 'application/json', 'Content-Type' => 'application/json', 'X-API-KEY' => '{your API key}' ]; $payload = [ "DisableExpiryAlert" => false, "ReminderSettings" => [ "ReminderDays" => 5, "ReminderCount" => 3, "EnableAutoReminder" => true ], "BrandId" => '', "EnableReassign" => true, "Message" => '', "Signers" => [ [ "name" => "Sample document", "emailAddress" => "alexgayle@cubeflakes.com", "signerType" => "Signer", "formFields" => [ [ "id" => "string", "name" => "string", "fieldType" => "Signature", "pageNumber" => 1, "bounds" => [ "x" => 50, "y" => 50, "width" => 125, "height" => 25 ], "isRequired" => true ], [ "id" => "string", "name" => "string", "fieldType" => "Label", "pageNumber" => 1, "bounds" => [ "x" => 150, "y" => 250, "width" => 125, "height" => 25 ], "isRequired" => true, "backgroundHexColor" => "string" ] ], "locale" => "EN" ] ], "ExpiryDays" => 30, "EnablePrintAndSign" => false, "AutoDetectFields" => false, "OnBehalfOf" => '', "EnableSigningOrder" => false, "UseTextTags" => false, "SendLinkValidTill" => '', "Files" => [ 'data:application/pdf;base64,JVBERi0xLjcKJcfs...' ], "Title" => 'Sample document', "HideDocumentId" => false, "EnableEmbeddedSigning" => false, "ExpiryDateType" => 'Days', "ExpiryValue" => 60, "DisableEmails" => false, "DisableSMS" => false, "MetaData"=> { "DocumentType"=> "new", "DocumentCategory"=> "Software" } ]; $options = [ 'body' => json_encode($payload) ]; $request = new Request('POST', 'https://api.boldsign.com/v1/document/send', $headers); $res = $client->sendAsync($request, $options)->wait(); echo $res->getBody();
Request body
filesarray | The files to be uploaded for sending signature request. .pdf, .png, .jpg, and .docx are supported file formats. The preferred file format is .pdf . You can upload up to 25 files. Each document may have a maximum of 1000 pages and must be no larger than 25 MB in size. The base64 format is data:application/{{fileType}};base64,{{content}} . | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
titlestring | This is the title of the document that will be displayed in the BoldSign user interface as well as in the signature request email. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
messagestring | A message for all the recipients. You can include the instructions that the signer should know before signing the document. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
signersarray | Details of the signers. One or more signers can be specified.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ccarray | Mail ID of the CC recipients. One or more CC recipients can be specified.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
enableSigningOrderboolean | Enables or disables the signing order. When enabled, signers must sign the document in the designated order and cannot sign in parallel. The default value is set to false. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
expiryDaysinteger | The number of days after which the document expires. The default value is 60 days. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ReminderSettings.EnableAutoReminderboolean | Enables or disables the auto-reminder. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ReminderSettings.ReminderDaysinteger | The number of days between each automatic reminder. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ReminderSettings.ReminderCountinteger | The number of times the auto-reminder should be sent. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
disableEmailsboolean | Disables the sending of document related emails to all the recipients. The default value is false. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
disableSMSboolean | Disables the sending of document related SMS to all the recipients. The default value is false . | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
brandIdstring | You can customize the logo, colors, and other elements of the signature request emails and document signing pages to match your company branding. The ID of the existing brand can be obtained from the branding API and from the web app. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
hideDocumentIdboolean | Decides whether the document ID should be hidden or not. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
labelsarray | Labels (tags) are added to the document to categorize and filter the documents. One or more labels can be added. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
fileUrlsarray | The URL of the files to be uploaded for sending signature request. .pdf, .png, .jpg, and .docx are supported file formats. The preferred file format is .pdf . You can upload up to 25 files. Each document may have a maximum of 1000 pages and must be no larger than 25 MB in size. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sendLinkValidTillstring | Configures the expiration for the generated URL. A maximum of 180 days can be assigned. The string should be in date-time format. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
useTextTagsBoolean | When enabled, it will convert all the tags defined in the document to BoldSign form fields. The default value is false . | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
textTagDefinitionsarray | This can be used for long text tag handling.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
enablePrintAndSignboolean | Allows the signer to reassign the signature request to another person. The default value is true . | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
disableExpiryAlertarray | Disables the alert, which was shown one day before the expiry of the document. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
documentInfoarray | Options to customize the information, like the title and description of the document for a particular signer.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
onBehalfOfstring | Mail ID of the user to send the document on behalf of them. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
autoDetectFieldsboolean | When enabled, it will convert all the fillable form fields in the document to BoldSign form fields. BoldSign supports Textbox, Checkbox, Radio button, and Signature form fields. Other fields will not be detected as of now. The default value is false . | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
documentDownloadOptionenum | This option allows you to configure how the uploaded files, especially multiple files, should be downloaded: either as a single combined document or as separate documents. The values are Combined and Individually . The default value is Combined . If the value is null , the setting configured in the business profile settings will be considered. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
formGroupsarray | Manages the rules and configuration of grouped form fields.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
metaDatadictionary | Additional information about the document in the form of key-value pairs. Up to 50 key-value pairs can be added. The key is limited to 50 characters, and the value is limited to 500 characters. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
recipientNotificationSettingsobject | Control email notifications to recipients or CC collectively by configuring properties within
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
enableAuditTrailLocalizationboolean | Enable localization for audit trail based on the signer's language. If null is provided, the value will be inherited from the Business Profile settings. Only one additional language can be specified in the signer's languages besides English. |
Example response
201 Created
{ "documentId": "8f59295d-xxxx-xxxx-xxxx-e7dc88cfff2c" }