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.

Read more about webhooks

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/send

You 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.

Code snippet

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
    }
  ],
  "locale": "EN"
}' \
  -F 'ExpiryDays=30' \
  -F 'EnablePrintAndSign=false' \
  -F 'AutoDetectFields=false' \
  -F 'OnBehalfOf=' \
  -F 'EnableSigningOrder=false' \
  -F 'UseTextTags=false' \
  -F 'SendLinkValidTill=' \
  -F 'Files=@BoldSign test.pdf;type=application/pdf' \
  -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'
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 formFieldCollections = new List<FormField>()
{
    signatureField
};

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 sendForSign = new SendForSign()
{
   Message = "please sign this",
   Title = "Agreement",
   HideDocumentId = false,
   Signers = documentSigners,
   Files = filesToUpload,

};
var documentCreated = documentClient.SendDocument(sendForSign);
import requests
import json

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

signer_data = {
    "name": "David",
    "emailAddress": "david@cubeflakes.com",
    "signerType": "Signer",
    "formFields": [
        {
            "id": "string",
            "name": "string",
            "fieldType": "Signature",
            "pageNumber": 1,
            "bounds": {
                "x": 50,
                "y": 50,
                "width": 200,
                "height": 25
            },
            "isRequired": True
        }
    ],
    "locale": "EN"
}

payload = {
    'DisableExpiryAlert': 'false',
    'ReminderSettings.ReminderDays': '3',
    'BrandId': '',
    'ReminderSettings.ReminderCount': '5',
    'EnableReassign': 'true',
    'Message': 'Please sign this.',
    'Signers': json.dumps(signer_data),
    'ExpiryDays': '10',
    'EnablePrintAndSign': 'false',
    'AutoDetectFields': 'false',
    'OnBehalfOf': '',
    'EnableSigningOrder': 'false',
    'UseTextTags': 'false',
    'SendLinkValidTill': '',
    'Title': 'Agreement',
    'HideDocumentId': 'false',
    'EnableEmbeddedSigning': 'false',
    'ExpiryDateType': 'Days',
    'ReminderSettings.EnableAutoReminder': 'false',
    'ExpiryValue': '60',
    'DisableEmails': 'false',
    'DisableSMS': 'false'
}

files=[
  ('Files',('file',open('{Your File Path}','rb'),'application/pdf'))
]

headers = {
  'accept': 'application/json',
  '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('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    }\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');

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'
        }
    }
);

Request body

filesarrayThe 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.
titlestringThis is the title of the document that will be displayed in the BoldSign user interface as well as in the signature request email.
messagestringA 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.

namestringName of the signer. This name will appear on all the emails, notifications, and the audit files.
emailAddressstringMail ID of the signer. This ID will appear on all the emails, notifications, and the audit files.
privateMessagestringWhen the specified signer proceeds to sign the document, a message appears. You can include the instructions that the signer should know before signing the document.
authenticationTypestringThis is used to allow authentication for a specific signer. We have three types of authentication. They are AccessCode , EmailOTP, SMSOTP and IdVerification. The default value is None.

phoneNumberobject

When you set the authentication type to SMSOTP or select the delivery mode as SMS or EmailAndSMS, you can provide the phone number with the country code.

countryCodestringThis property represents the country code associated with the phone number.
numberstringThis property represents the actual phone number.
deliveryModestringThis property allows you to specify the desired delivery mode for sending notifications. We have three types of delivery modes. They are Email , SMS and EmailAndSMS. The default value is Email.
authenticationCodestringThe authentication access code that must be entered by the signer to access the document. This should be shared with the signer.
signerOrderintegerSigning order of the signer. This is applicable when the signing order option is enabled.
enableEmailOTPbooleanEnables email OTP authentication. When this feature is activated, the signer must enter the OTP received via email in order to access the document.
signerTypestringType of the signer. The values are Signer, Reviewer, and InPersonSigner.
hostEmailstringMail ID of the host. It is applicable when the signerType is set to InPersonSigner.
signerRolestringThe role of the signer.
allowFieldConfigurationbooleanThis option enables the signer to add fields at their end while signing the document. You can also assign fields to the signer if anything is required, and it becomes mandatory if set to false. By default, it is set to false.

identityVerificationSettingsobject

Settings for identity verification when IdVerification authentication type is enabled for the signer.

typestringCustomize the frequency of identity verification for signers accessing documents.
  • EveryAccess: Signers must undergo identity verification each time they access the document, even after completing their signature.
  • UntilSignCompleted: Identity verification is required until the signer completes their signature. After which, they will not need to undergo identity verification again.
  • OncePerDocument: Signers authenticate their identity only once, even if accessing the document multiple times.
maximumRetryCountintegerSpecify the maximum number of verification attempts allowed for signers. Exceeding this limit restricts access to the document. Senders have the option to reset failed signers for additional attempts and manually review failed document uploads for approval or rejection. Maximum number of retries is 10.
requireLiveCapturebooleanMandate signers to capture a live image of their identification document using their device camera. This verifies the document's authenticity and originality, preventing the use of photos or photocopies.
requireMatchingSelfiebooleanUses advanced machine learning algorithms to ensure facial recognition accuracy, preventing the use of stolen identity documents by comparing the photo on the ID and the selfie image.
nameMatcherstringDefine the tolerance level for matching the signer's name with the name on the uploaded identification document. Options include:
  • Strict: Minimal variations are permitted, adhering to strict matching rules.
  • Moderate: Moderate matching rules allow for variations in the middle, prefix, and suffix parts of the name.
  • Lenient: Relaxed matching rules accommodate minor spelling mistakes for increased flexibility.

formFieldsarray

List of form fields associated with the signer.

idstringThe ID of the form field.
namestringName of the form field.
typestringType of the form field. The available values are Signature, Initial, CheckBox, TextBox, Label, DateSigned, RadioButton, Image, Attachment, EditableDate, Hyperlink, and Dropdown.
pageNumberintegerPage number in the document, in which the form field has to be placed.

boundsRectangle

Position and size values of the form field to be placed.

xfloatX-coordinate value to place the form field.
yfloatY-coordinate value to place the form field.
widthfloatWidth of the form field.
heightfloatHeight of the form field.
isRequiredbooleanDecides whether this form field is required to be filled or not.
valuestringValue to be displayed on the label form field.
fontSizefloatSize of the font.
font stringFont family. The values are Courier, Helvetica, and TimesNewRoman.
fontHexColorstringColor of the font. The value should be a hex color code. Example - #035efc.
isBoldFontbooleanDecides whether the font should be in bold or not.
isItalicFontbooleanDecides whether the font should be in italic or not.
isUnderLineFontbooleanDecides whether the font should be underlined or not.
lineHeightintegerHeight of a line in the text.
characterLimitintegerLimits the number of characters in the text.
groupNamestringThe group name of the form field. This field is required when the fieldType is set to RadioButton.
placeHolderstringA hint text to be displayed in the textbox form field by default.
validationTypestringType of validation for the textbox form field. The values are Only Numbers, Regex, Currency, Email, and None.
validationCustomRegexstringValue for regex validation. This is applicable when the validationType is set to Regex.
validationCustomRegexMessagestringDescription for regex validation. This message is displayed when the signer enters an invalid regex format value in the textbox form field.
dateFormatstringFormat of the date to be displayed on the date signed form field. The default value is MM/dd/yyyy. When null is provided, the value is inherited from the business profile settings of your account. Accepted formats are MM/dd/yyyy (02/08/2024), dd/MM/yyyy (08/02/2024), dd-MMM-yyyy (08-Feb-2024), MMM-dd-yyyy (Feb-08-2024), MMM dd, yyyy (Feb 08, 2024), dd MMM, yyyy (08 Feb, 2024), yyyy, MMM dd (2024, Feb 08), yyyy/MM/dd (2024/02/08), dd-MM-yyyy (08-02-2024), MM-dd-yyyy (02-08-2024), yyyy-MM-dd (2024-02-08).
timeFormatstringFormat of the time to be displayed on the date signed form field. When null is provided, the value is inherited from the business profile settings of your account. Accepted formats are hh:mm tt (12:30 PM), h:mm tt (2:45 PM), HH:mm (14:30), H:mm (9:15), None (Disabled, no time will be displayed).

imageInfoobject

Options to customize the image form field.

titlestringTitle of the image form field.
descriptionstringDescription of the image form field.
allowedFileExtensionsstringControls the image formats that are allowed to upload on the image form field. The values are .jpg or .jpeg, .svg, .png, and .bmp.

attachmentInfoobject

Options to customize the attachment form field.

titlestringTitle of the attachment form field.
descriptionstringDescription of the image form field.
allowedFileTypesstringControls the file formats that are allowed to upload on the attachment form field. The values are PDF, Document, and Image.

editableDateFieldSettingsobject

Options to customize the editable date form field.

dateFomatstringFormat of the date to be displayed on the date signed form field. The default value is MM/dd/yyyy.
minDatestringThe minimum date that can be selected. The string should be in date-time format.
maxDate stringThe maximum date that can be selected. The string should be in date-time format.
hyperLinkTextstringText to be displayed for the hyperlink.
dataSyncTagstringThe value that can be specified on two or more textbox form fields to sync them.
dropDownOptionsarrayThe values that have to be displayed on the dropdown form field. One or more values can be specified.
textAlignstringDetermines the horizontal alignment of text for the textbox and label form fields, and can be set to Left, Center, or Right.
textDirectionstringDetermines the text direction of text for the textbox and label form fields, and can be set to LTR or RTL.
characterSpacingfloatDetermines the character spacing of text for the textbox and label form fields. It can be set as a floating-point value.
languageintegerIndex of the language, in which the document signing pages and emails for the signer should render. The supported languages are 1-English, 2-Spanish, 3-German, 4-French, and 5-Romanian. Note that 'locale' should now be used instead of 'language' as it has replaced the deprecated term.
localestringSpecify the language index for rendering document signing pages and emails for the signer, choosing from the supported locales such as EN-English, NO-Norwegian, FR-French, 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.

ccarray

Mail ID of the CC recipients. One or more CC recipients can be specified.

emailAddressstringMail ID of the CC recipients.
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.
expiryDaysintegerThe number of days after which the document expires. The default value is 60 days.
ReminderSettings.EnableAutoReminderbooleanEnables or disables the auto-reminder.
ReminderSettings.ReminderDaysintegerThe number of days between each automatic reminder.
ReminderSettings.ReminderCountintegerThe number of times the auto-reminder should be sent.
disableEmailsbooleanDisables the sending of document related emails to all the recipients. The default value is false.
disableSMSbooleanDisables the sending of document related SMS to all the recipients. The default value is false.
brandIdstringYou 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.
hideDocumentIdbooleanDecides whether the document ID should be hidden or not.
labelsarrayLabels (tags) are added to the document to categorize and filter the documents. One or more labels can be added.
fileUrlsarrayThe 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.
sendLinkValidTillstringConfigures the expiration for the generated URL. A maximum of 180 days can be assigned. The string should be in date-time format.
useTextTagsBooleanWhen enabled, it will convert all the tags defined in the document to BoldSign form fields. The default value is false.

textTagDefinitionarray

This can be used for long text tag handling.

definitionIdstringThe definition id of the text tag.
typeFieldTypeThe type of the form field.
signerIndexintegerThe signer index of the form field.
isRequiredbooleanWhen disabled, the signer is not required to fill out the specific form field. The default value is true.
placeHolderstringThe placeholder of the form field.
fieldIdstringThe field id of the form field.

fontobject

The font of the form field.

nameFontFamilyFont family. The values are Courier, Helvetica, and TimesNewRoman.
colorstringColor of the font. The value should be hex color code. Example - #035efc.
sizefloatSize of the font.
styleFontStyleStyle of the font. The values are Regular, Bold, Italic, and Underline.
lineHeightintegerHeight of a line in the text.

validationobject

When we select the type as TextBox, the validation of the form field is required.

typestringThe validation type of the textbox form field. The available values are None, NumbersOnly, EmailAddress, Currency, and CustomRegex. The default value is None.
regexstringThe custom regex of the textbox form filed. When we set the ValidationType to CustomRegex, it will be required.

sizeobject

This can be used to specify the form field's height and width.

widthfloatThe width of the form field.
heightfloatThe height of the form field.
dateFormatstringFormat of the date to be displayed on the date signed form field. The default value is MM/dd/yyyy. When null is provided, the value is inherited from the business profile settings of your account. Accepted formats are MM/dd/yyyy (02/08/2024), dd/MM/yyyy (08/02/2024), dd-MMM-yyyy (08-Feb-2024), MMM-dd-yyyy (Feb-08-2024), MMM dd, yyyy (Feb 08, 2024), dd MMM, yyyy (08 Feb, 2024), yyyy, MMM dd (2024, Feb 08), yyyy/MM/dd (2024/02/08), dd-MM-yyyy (08-02-2024), MM-dd-yyyy (02-08-2024), yyyy-MM-dd (2024-02-08).
timeFormatstringFormat of the time to be displayed on the date signed form field. When null is provided, the value is inherited from the business profile settings of your account. Accepted formats are hh:mm tt (12:30 PM), h:mm tt (2:45 PM), HH:mm (14:30), H:mm (9:15), None (Disabled, no time will be displayed).
radioGroupNamestringThe form field's group name, which is required when we set the type as RadioButton.
valuestringThe value of the form field.
dropDownOptionsarrayThe options of the dropdown form field.
enablePrintAndSignbooleanAllows the signer to reassign the signature request to another person. The default value is true.
disableExpiryAlertarrayDisables 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.

languageintegerLanguage in which the document signing pages and emails for the signer should be rendered. The supported languages are 1-English, 2-Spanish, 3-German, 4-French, and 5-Romanian. Note that 'locale' should now be used instead of 'language' as it has replaced the deprecated term.
titlestringTitle of the document.
descriptionstringA message for the singer. You can include the instructions that the signer should know before signing the document.
localestringSpecify the language index for rendering document signing pages and emails for the signer, choosing from the supported locales such as EN-English, NO-Norwegian, FR-French, 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.
onBehalfOfstringMail ID of the user to send the document on behalf of them.
autoDetectFieldsbooleanWhen 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.
documentDownloadOptionenumThis 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.

Example response

201 Created

{
  "documentId": "8f59295d-xxxx-xxxx-xxxx-e7dc88cfff2c"
}