The BoldSign mobile app is now available. Visitthis link for more details and give it a try!

The BoldSign mobile app is now available. Visitthis link for more details and give it a try!

Request Demo
BoldSign Logo Small

Features

Explore the BoldSign features that make eSigning easier.

Mandating Signer Authentication After Sending Documents via API​

Mandating Signer Authentication After Sending Documents via API

Secure your document signing process by prompting users to identify themselves before allowing them access to documents. With BoldSign, you can accomplish this using multiple supported signer authentication methods to verify the signers:

  1. Access Code: A set of alphanumeric characters specified by the sender to the recipient for accessing the document. The sender needs to provide the secure code directly to the recipient.
  2. Email OTP:A system-generated one-time password delivered to the recipient’s inbox, required to access the document.
  3. SMS OTP :A system-generated one-time password delivered to the recipient’s phone number, required to access the document.This is only available to higher-tier plans.
  4. Identity Verification: A comprehensive process to confirm the signer’s identity, which can include passport, drivers license, or government ID verification. This is only available to higher-tier plans.

Adding these signer authentications ensures only the intended people access the document, thus protecting your information. In this blog post, we will see how to add signer authentication to a document after sending it using email OTP, SMS OTP, identity verification, and access codes via the BoldSign API

Adding email OTP to a document recipient using the API

With the BoldSign API, you can add email OTP authentication to a recipient by specifying the authenticationType as Email OTP and providing the document ID in which the recipient is added.  When the recipient wants to sign the document, they will be required to enter a valid code that will be sent to their email address before accessing it. Please note that if the signer fails authentication three times, the document will be locked. Refer to this documentation to see how to unlock the document in this scenario.

The following sample code snippets request the email OTP authentication be added to one of the document’s recipients.

Curl

    
curl -X PATCH "https://api.boldsign.com/v1/document/addAuthentication?documentId={documentId}"
      -H 'X-API-KEY: {your API key}'
      -H "Content-Type: application/json"
      -d "{\"authenticationType\": \"EmailOTP\", \"emailId\": \" alexgayle@cubeflakes.com \"}"
 

C#

    
var apiClient = new ApiClient("https://api.boldsign.com", "{apikey}");
var documentclient = new DocumentClient(apiClient);
await documentclient.AddAuthenticationAsync("{documentId}", " starvritsa@boldsign.dev", AuthenticationType.EmailOTP).ConfigureAwait(false);
 

Python

    
import requests
import json
url = "https://api.boldsign.com/v1/document/addAuthentication?documentId={documentId}"
payload = json.dumps({
  "authenticationType": "EmailOTP",
  "emailId": "alexgayle@cubeflakes.com"
})
headers = {
  'X-API-KEY': '{your API key}',
  'Content-Type': 'application/json'
}
response = requests.request("PATCH", url, headers=headers, data=payload)
print(response.text)
 

Node.js

    
const axios = require('axios');
await axios.patch(
'https://api.boldsign.com/v1/document/addAuthentication',
    {
    authenticationType: 'EmailOTP',
        emailId: 'alexgayle@cubeflakes.com'
    },

    {
        params: { documentId: '{documentId}' },
        headers: {
          'X-API-KEY': '{Your API key}',
          'Content-Type': 'application/json'
        }
    }
);
 

PHP

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

$client = new Client(['verify' => false]);
$headers = [
  'X-API-KEY' => '{your API key}',
  'Content-Type' => 'application/json'
];
$body = '{
  "authenticationType": "EmailOTP",
  "emailId": " alexgayle@cubeflakes.com "
}';
$request = new Request('PATCH', 'https://api.boldsign.com/v1/document/addAuthentication?documentId={documentId}', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
 

Adding SMS OTP to a document recipient using the API

Senders can also opt to add SMS authentication to a recipient using the API. You will need to specify the authenticationType as SMSOTP. It is also mandatory to add the CountryCode and Number for SMS authentication. This means that the signer will be prompted to enter a code before they can access the document. That code will be texted to the specified number. Please note that a Business or Advanced plan is required to use SMS OTP.

The following sample code snippets request the SMS OTP authentication to be added to one of a document’s recipients.

Curl

    
curl -X PATCH "https://api.boldsign.com/v1/document/addAuthentication?documentId={documentId}"
      -H -H 'X-API-KEY: {your API key}'
      -H "Content-Type: application/json"
      -d "{\"authenticationType\": \"SMSOTP\", \"emailId\": \"alexgayle@cubeflakes.com\", \"phoneNumber\": {\"countryCode\": \"{signer country code}\", \"number\": \"{signer phone number}\"}}"
 

C#

    
var apiClient = new ApiClient("https://api.boldsign.com", "{apikey}");
var documentclient = new DocumentClient(apiClient);
var phoneNumber = new PhoneNumber() {
  CountryCode = "{signer country code}",
Number = "{signer phone number}"
  };
await documentclient.AddAuthenticationAsync("{documentId}", " alexgayle@cubeflakes.com", AuthenticationType.SMSOTP, null, phoneNumber: phoneNumber).ConfigureAwait(false);
 

Python

    
import requests
import json
url = "https://api.boldsign.com/v1/document/addAuthentication?documentId={documentId}"
payload = json.dumps({
  "authenticationType": "SMSOTP",
  "emailId": " alexgayle@cubeflakes.com ",
  "phoneNumber": {
    "countryCode": "{signer country code}",
    "number": "{signer phone number}"
  }
})
headers = {
  'X-API-KEY': '{your API key}',
  'Content-Type': 'application/json'
}
response = requests.request("PATCH", url, headers=headers, data=payload)
print(response.text)
 

Node.js

    
const axios = require('axios');
await axios.patch(  
'https://api.boldsign.com/v1/document/addAuthentication',
    {
        authenticationType: 'SMSOTP',
        emailId: 'alexgayle@cubeflakes.com,
        phoneNumber: {
            countryCode: '{signer country code}',
            number: '{signer phone number}'
        }
    },

    {
        params: { documentId: '{documentId}' },
        headers: {
            'X-API-KEY': '{Your API key}',
            'Content-Type': 'application/json'
        }
    }
);
 

PHP

    
<?php
require_once "vendor/autoload.php";
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;
$client = new Client([   'verify' => false]);
$headers = [
  'X-API-KEY' => '{your API key}',
  'Content-Type' => 'application/json'
];
$body = '{
  "authenticationType": "SMSOTP",
  "emailId": "alexgayle@cubeflakes.com ",
  "phoneNumber": {
    "countryCode": "{signer country code}",
    "number": "{signer phone number}"
  }
}';
$request = new Request('PATCH', 'https://api.boldsign.com/v1/document/addAuthentication?documentId={documentId}', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
 

Adding an access code to a document recipient using the API

You can also authenticate signers with an access code using the BoldSign API by setting the authenticationType to AccessCode and providing a unique access code (e.g., “1234”) in the accessCode property. The access code will be used when the sender wants to use a specific code to verify the signer. The access code must be communicated personally to the signer beforehand.

The following sample code snippets request the access code authentication to be added to one of a document’s recipients.

Curl

    
curl -X PATCH "https://api.boldsign.com/v1/document/addAuthentication?documentId={documentId}"
      -H -H 'X-API-KEY: {your API key}'
-H "Content-Type: application/json"
      -d "{\"accessCode\": \"123456\", \"authenticationType\": \"AccessCode\", \"emailId\": \" alexgayle@cubeflakes.com \"}"
 

C#

    
var apiClient = new ApiClient("https://api.boldsign.com", "{apikey}");
var documentclient = new DocumentClient(apiClient);
await documentclient.AddAuthenticationAsync("{documentId}", "alexgayle@cubeflakes.com ", AuthenticationType.AccessCode, null, "123456").ConfigureAwait(false);
 

Python

    
import requests
import json
url = "https://api.boldsign.com/v1/document/addAuthentication?documentId={documentId}"
payload = json.dumps({
  "accessCode": "123456",
  "authenticationType": "AccessCode",
  "emailId": "boldsign.dev"
})
headers = {
  'X-API-KEY': '{your API key}',
  'Content-Type': 'application/json'
}

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

Node.js

    
const axios = require('axios');
await axios.patch(
    'https://api.boldsign.com/v1/document/addAuthentication',

    {
        accessCode: '123456',
        authenticationType: 'AccessCode',
        emailId: alexgayle@cubeflakes.com '
    },

    {
        params: { documentId: '{documentId}' },
        headers: {
            'X-API-KEY': '{Your API key}',
            'Content-Type': 'application/json'
        }
    }
);
 

PHP

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

$client = new Client([   'verify' => false]);
$headers = [
  'X-API-KEY' => '{your API key}',
  'Content-Type' => 'application/json'
];
$body = '{
  "accessCode": "123456",
  "authenticationType": "AccessCode",
  "emailId": " alexgayle@cubeflakes.com IIf"
}';
$request = new Request('PATCH', 'https://api.boldsign.com/v1/document/addAuthentication?documentId={documentId}', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
 

Adding identity verification to a document recipient using the API

Senders can select signers for identity verification, enabling individualized security measures based on document sensitivity and signer roles. To add this, the sender will need to set the authentication type to IdVerification and then customize the settings in the IdentityVerificationSettings section. These settings include setting the frequency of authentication using type, specifying the number of retries allowed with maximumRetryCount, enabling selfie and live capture by setting the requireLiveCapture and requireMatchingSelfie values to true, and configuring the nameMatcher. Refer to this documentation for more details about identity verification settings.

The following sample code snippets request the identity verification authentication to be added to one of a document’s recipients.

Curl

    
curl -X 'PATCH' \
  'https://api.boldsign.com/v1/document/addAuthentication?documentId={your document id}' \
  -H 'accept: */*' \
  -H 'X-API-KEY: {your api key}' \
  -H 'Content-Type: application/json;odata.metadata=minimal;odata.streaming=true' \
  -d '{
  "emailId": "mathewwilson@cubeflakes.com",
  "order": 1,
  "authenticationType": "IdVerification",
  "identityVerificationSettings": {
    "type": "EveryAccess",
    "maximumRetryCount": 10,
    "requireLiveCapture": true,
    "requireMatchingSelfie": true,
    "nameMatcher": "Strict"
  }
}'
 

C#

    
var apiClient = new ApiClient("https://api.boldsign.com", "{your api key}");
var documentClient = new DocumentClient(apiClient);
var identityVerificationSettings = new IdentityVerificationSettings
{
    Type = IdVerificationType.EveryAccess,
    MaximumRetryCount = 10,
    RequireLiveCapture = true,
    RequireMatchingSelfie = true,
    NameMatcher = NameVariation.Strict
};
await documentClient.AddAuthenticationAsync(
    "{your document id}",
    "mathewwilson@cubeflakes.com",
    AuthenticationType.IdVerification,
    identityVerificationSettings: identityVerificationSettings
).ConfigureAwait(false);
 

Python

    
import requests
import json
url = "https://api.boldsign.com/v1/document/addAuthentication?documentId={your document id)"
payload = json.dumps({
  "emailId": "mathewwilson@cubeflakes.com",
  "order": 1,
  "authenticationType": "IdVerification",
  "identityVerificationSettings": {
    "type": "EveryAccess",
    "maximumRetryCount": 10,
    "requireLiveCapture": True,
    "requireMatchingSelfie": True,
    "nameMatcher": "Strict"
  }
})
headers = {
  'X-API-KEY': '{your api key}',
  'Content-Type': 'application/json'
}
response = requests.request("PATCH", url, headers=headers, data=payload)
print(response.text)
 

Node.js

    
const axios = require('axios');
const documentId = '{your document id};
const apiKey = '{your api key}';
async function addAuthentication() {
    try {
        const response = await axios.patch(
            'https://api.boldsign.com/v1/document/addAuthentication',
            {
                emailId: 'mathewwilson@cubeflakes.com',
                order: 1,
                authenticationType: 'IdVerification',
                identityVerificationSettings: {
                    type: 'EveryAccess',
                    maximumRetryCount: 10,
                    requireLiveCapture: true,
                    requireMatchingSelfie: true,
                    nameMatcher: 'Strict'
                }
            },
            {
                params: { documentId: documentId },
                headers: {
                    'X-API-KEY': apiKey,
                    'Content-Type': 'application/json'
                }
            }
        );
        console.log(response.data);
    } catch (error) {
        console.error(error.response ? error.response.data : error.message);
    }
}
addAuthentication();
 

PHP

    
<?php
require 'vendor/autoload.php';
use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;
$documentId = '{your document id};
$apiKey = '{your api key}';
$client = new Client([
    'base_uri' => 'https://api.boldsign.com',
    'headers' => [
        'X-API-KEY' => $apiKey,
        'Content-Type' => 'application/json'
    ],
    'verify' => false
]);
$body = [
    'emailId' => 'mathewwilson@cubeflakes.com',
    'order' => 1,
    'authenticationType' => 'IdVerification',
    'identityVerificationSettings' => [
        'type' => 'EveryAccess',
        'maximumRetryCount' => 10,
        'requireLiveCapture' => true,
        'requireMatchingSelfie' => true,
        'nameMatcher' => 'Strict'
    ]
];
try {
    $response = $client->patch('/v1/document/addAuthentication', [
        'query' => ['documentId' => $documentId],
        'json' => $body
    ]);
    echo $response->getBody();
} catch (RequestException $e) {
    if ($e->hasResponse()) {
        echo $e->getResponse()->getBody();
    } else {
        echo $e->getMessage();
    }
}
 

Conclusion

Requiring your signers to verify themselves before accessing a document ensures the security and integrity of your signing process. Organizations can reduce the risk of documents being accessed by unintended people during the signing process. By using signer authentication, you add an additional layer of security to your signing process.

If you are not yet a BoldSign customer, try a 30-day free trial and see how BoldSign safeguards your information. We value your feedback, so please share your thoughts in the comments section. 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.

Picture of Starvritsa Buhungi

Starvritsa Buhungi

Starvritsa is a Technical Assistant at BoldSign, channelling her passion into crafting top-tier content for users through meticulous documentation. She creates content across various formats, including API tutorials, help articles, and comprehensive guides.

Share this blog

Picture of Starvritsa Buhungi

Starvritsa Buhungi

Starvritsa is a Technical Assistant at BoldSign, channelling her passion into crafting top-tier content for users through meticulous documentation. She creates content across various formats, including API tutorials, help articles, and comprehensive guides.

Subscribe RSS feed

Leave a Reply

Your email address will not be published. Required fields are marked *