Add authentication to the document

patch/v1/document/addAuthentication

The sender can enable authentication for the document, which secures the signing page. Each recipient must authenticate themselves before opening the document to sign.

There are three types of Authentication: AccessCode, EmailOTP, and SMSOTP.

AccessCode - A set of alphanumeric characters will be specified by the sender to the recipient for accessing the document, and the sender needs to provide the secure code directly to the recipient.
EmailOTP - A system generated one time password will be delivered to the recipient's mailbox that is required to access the document.
SMSOTP - A system generated one time password will be delivered to the recipient's phone number that is required to access the document.

Code snippet

The following sample code snippet requests the EmailOTP authentication to be added to one of the document's recipients.

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\"}"

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

import boldsign

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

with boldsign.ApiClient(configuration) as api_client:

    document_api = boldsign.DocumentApi(api_client)
    
    access_code_detail = boldsign.AccessCodeDetail(
      authenticationType="EmailOTP",
      emailId="alexgayle@cubeflakes.com"
    )
    
    add_authentication_response = document_api.add_authentication(
      document_id="YOUR_DOCUMENT_ID",
      access_code_detail=access_code_detail
    )

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

The following sample code snippet requests the AccessCode authentication to be added to one of the document's recipients.

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\"}"

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

import boldsign

configuration = boldsign.Configuration(
    api_key = "YOUR_API_KEY"
)
with boldsign.ApiClient(configuration) as api_client:

    document_api = boldsign.DocumentApi(api_client)
    
    
    access_code_detail = boldsign.AccessCodeDetail(
        authenticationType="AccessCode",
        accessCode="123456",
        emailId="alexgayle@cubeflakes.com"
    )
    
    add_authentication_response = document_api.add_authentication(
        document_id="YOUR_DOCUMENT_ID",
        access_code_detail=access_code_detail
    )

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

The following code sample snippet requests the SMS OTP authentication to be added to one of the document's recipients.

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\": \"+1\", \"number\": \"2015666802\"}}"

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

import boldsign

configuration = boldsign.Configuration(
    api_key = "YOUR_API_KEY"
)
with boldsign.ApiClient(configuration) as api_client:
    
    document_api = boldsign.DocumentApi(api_client)
    
    phoneNumber = boldsign.PhoneNumber(
        country_code="+1",
        number="201566802"
    )
    
    access_code_detail = boldsign.AccessCodeDetail(
        authenticationType="SMSOTP",
        phone_number=phoneNumber,
        emailId="alexgayle@cubeflakes.com"
    )
    
    add_authentication_response = document_api.add_authentication(
        document_id="YOUR_DOCUMENT_ID",
        access_code_detail=access_code_detail
    )

const axios = require('axios');
await axios.patch(

    'https://api.boldsign.com/v1/document/addAuthentication',

    {
        authenticationType: 'SMSOTP',
        emailId: 'alexgayle@cubeflakes.com',
        phoneNumber: {
            countryCode: '+1',
            number: '2015666802'
        }
    },

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

If a document contains repeated signers with signing order, in that case the recipient's signing order can be specified along with the signer's email to add the EmailOTP authentication request, as shown in the following code snippet.

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\": \"EmailOTP\", \"emailId\": \"alexgayle@cubeflakes.com\", \"order\": 2}"

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

import boldsign

configuration = boldsign.Configuration(
    api_key = "YOUR_API_KEY"
)
with boldsign.ApiClient(configuration) as api_client:
    
    document_api = boldsign.DocumentApi(api_client)
    
    access_code_detail = boldsign.AccessCodeDetail(
        authenticationType="EmailOTP",
        emailId="alexgayle@cubeflakes.com",
        order=1
    )
    
    add_authentication_response = document_api.add_authentication(
        document_id="YOUR_DOCUMENT_ID",
        access_code_detail=access_code_detail
    )

const axios = require('axios');
await axios.patch(

    'https://api.boldsign.com/v1/document/addAuthentication',

    {
        authenticationType: 'EmailOTP',
        emailId: 'alexgayle@cubeflakes.com',
        order: 2

    },

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

Query parameters

documentIdstringRequired

ID of the requested document

Request body

accessCodestring Access code is required when using AccessCode type of authentication. Otherwise, it should be empty.

authenticationTypestringRequired It includes AccessCode and EmailOTP authentications. If you prefer EmailOTP authentication, set the DisableEmails property in the document to false. If you prefer AccessCode authentication, you must share the access code to the recipient directly.

emailIdStringRequired Email address of the signer.

onBehalfOfstring If the document is created on behalf of the sender, the sender's identity email address must be specified.

orderInt A number that denotes the signer's order, which targets the given email address present in the recipient list. The order should be in the range of 1 - 50.

identityVerificationSettingsobject

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

typestring	Customize 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.
maximumRetryCountinteger	Specify 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.
requireLiveCaptureboolean	Mandate 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.
requireMatchingSelfieboolean	Uses 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.
nameMatcherstring	Define 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.
holdForPrefillboolean	Enable this option to hold the signer from signing the document, giving you the opportunity to prefill the signer's details. Once the prefill is completed, the signer can proceed with the signing process. The maximum hold time is 30 seconds; if you exceed this time limit, the signer will be redirected to the signing page.

phoneNumberobject

When the authentication type is specified as SMSOTP, you can provide the phone number with the country code.

countryCodestring	This property represents the country code associated with the phone number.
numberstring	This property represents the actual phone number.

Example response

200 Success