How to Control Recipient Notifications via BoldSign API
When sending a document using the BoldSign API, you can control the notifications that recipients receive through the recipientNotificationSettings property for each signer. If this property is not provided, the default notification settings configured in your business profile will apply.
For example, if you’re sending multiple documents to a client and want to avoid overwhelming them with notifications, you can disable reminders and only notify them when the document is signed or completed. This ensures they stay informed about important actions without being flooded by updates.
This blog provides guidance on how to customize recipient notifications by updating the recipientNotificationSettings property in your API requests.
Default behavior
If the recipientNotificationSettings property is not included in your API request, the default notification settings from your business profile will be used. This means recipients will receive notifications according to the predefined settings, such as reminders, signing requests, and other key events.
Customizing recipient notifications
To customize recipient notifications, include the recipientNotificationSettings property in your API request.
Let’s see, in various programming languages, how to update the notification settings for a recipient.
Curl
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 '{
"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
}
],
"recipientNotificationSettings": {
"signatureRequest": true,
"declined": true,
"revoked": true,
"signed": true,
"completed": true,
"expired": true,
"reassigned": true,
"deleted": true,
"reminders": true,
"editRecipient": true
}
}
],
"Files": [
"data:application/pdf;base64,JVBERi0xLjcKJcfs..."
],
"Title": "Sampledocument"
}'
C#
using BoldSign.Api;
using BoldSign.Model;
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
{
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()
{
signatureField
};
var signer = new DocumentSigner(
signerName: "David",
signerType: SignerType.Signer,
signerEmail: "david@cubeflakes.com",
formFields: formFieldCollections);
signer.RecipientNotificationSettings = new RecipientNotificationSettings()
{
SignatureRequest = true,
Declined = true,
Revoked = true,
Signed= true,
Completed= true,
Expired = true,
Reassigned = true,
Deleted = true,
Reminders = true,
EditRecipient = true
};
var documentSigners = new List()
{
signer
};
var sendForSign = new SendForSign()
{
Title = "Agreement",
Signers = documentSigners,
Files = filesToUpload
};
var documentCreated = documentClient.SendDocument(sendForSign);
Python
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
}
],
"recipientNotificationSettings": {
"signatureRequest": true,
"declined": true,
"revoked": true,
"signed": true,
"completed": true,
"expired": true,
"reassigned": true,
"deleted": true,
"reminders": true,
"editRecipient": true
}
}
payload = {
'Signers': [signer_data],
'Title': 'Agreement',
'Files': [
'data:application/pdf;base64,JVBERi0xLjcKJcfs...'
]
}
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)
Node js
const axios = require('axios');
const fs = require('fs');
// Create the payload object
const payload = {
Signers: [
{
name: 'David',
emailAddress: 'david@boldsign.dev',
formFields: [
{
fieldType: 'Signature',
pageNumber: 1,
bounds: {
x: 100,
y: 100,
width: 100,
height: 50
},
isRequired: true
},
recipientNotificationSettings: {
signatureRequest: true,
declined: true,
revoked: true,
signed: true,
completed: true,
expired: true,
reassigned: true,
deleted: true,
reminders: true,
editRecipient: true
}
}
],
Files: [
'data:application/pdf;base64,JVBERi0xLjcKJcfs...'
],
Title: 'Agreement'
}
};
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
<?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 = [
"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
]
],
"recipientNotificationSettings" => [
"signatureRequest" => true,
"declined" => true,
"revoked" => true,
"signed" => true,
"completed" => true,
"expired" => true,
"reassigned" => true,
"deleted" => true,
"reminders" => true,
"editRecipient" => true
]
]
],
"Files" => [
'data:application/pdf;base64,JVBERi0xLjcKJcfs...'
],
"Title" => 'Sample document'
];
$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();
RecipientNotificationSettings properties
signatureRequest: Indicates whether the recipient should be notified when a document is sent.
declined: Indicates whether the recipient should be notified when a document is declined.
revoked: Indicates whether the recipient should be notified when a document is revoked.
signed: Indicates whether the recipient should be notified when a document is signed by another recipient.
completed: Indicates whether the recipient should be notified when the document is completed.
expired: Indicates whether the recipient should be notified when a document expires.
reassigned: Indicates whether the recipient should be notified when the document is reassigned.
deleted: Indicates whether the recipient should be notified when a document is deleted.
reminders: Indicates whether the recipient should receive reminders for pending signature requests.
editRecipient: Indicates whether the recipient should be notified when there is a change in the recipient.
By customizing these settings, you can control the notification experience for each recipient according to your requirements.
Conclusion
Controlling recipient notifications via the BoldSign API is simple and offers flexibility in managing communication with signers. Whether you want to stick with the default settings or specify custom notifications, the recipientNotificationSettings property provides the control you need.
Start your 30-day free BoldSign trial today and send documents via SMS and email so that no document goes unnoticed.
We value your feedback, so please share your thoughts below. If you have any questions or need more information about our services, don’t hesitate to schedule a demo or reach out to our support team through our support portal.
Related blogs
Note: This blog was originally published at boldsign.com
