The Black Friday Deal for 2023 is live now. Get Flat 30% OFF on all plans!Learn More

Black Friday Deal - Flat 30% OFF! Learn More

Request Demo
Sending eSignature Documents on Behalf of Others using APIs Banner Image

Sending eSignature Documents on Behalf of Others using APIs

In the fast-paced world of digital transactions, the need for streamlined document handling has become more paramount than ever. Sending out documents for signature on behalf of others can be a time-consuming process, especially when dealing with multiple signatories. However, with the advent of innovative electronic signature solutions, such as BoldSign’s sender identity feature, the process has been revolutionized, offering simplicity and efficiency like never before.

In this blog post, let’s explore how to send eSignature documents on behalf of others using BoldSign’s sender identity feature. Whether you’re an executive sending contracts on behalf of your higher authority or an administrative professional managing agreements for multiple clients, understanding how to harness BoldSign’s sender identity feature will empower you to optimize your document workflow and ensure a smooth, efficient, and legally compliant signing process.

What is a sender identity?

The sender identity feature enables users to serve as authorized representatives, to send eSignature documents on behalf of others.

Requesting approval for sending documents

The sender identity feature allows users to request approval from a person or entity to act as their authorized representative. This approval grants the user the ability to send documents for signature on behalf of the approving individual or organization.

Effortless document management

With the sender identity feature, users are able to manage the entire signature process efficiently. They can track the status of sent documents, monitor the signature progress, and receive notifications upon completion.

Revoking access and access code management

The sender identity feature also offers a high level of control and security. Users can revoke sender identity access if necessary, ensuring that sensitive documents are protected from unauthorized use. Additionally, users can manage access codes to further safeguard the signing process.

Creating a sender identity in BoldSign using an API

To create a sender identity in BoldSign, you have two options: the web app or the API. In this blog post, we will focus on the API method for creating sender identities.

To get started with the API, you need to make a POST /v1/senderIdentities/create API call. The interesting part is that the person you want to send documents for doesn’t need to have a BoldSign account. Any person with an email address can authorize you to send documents on their behalf. The following is an example of the API call using cURL.

    
curl -X 'POST' \
  'https://api.boldsign.com/v1/senderIdentities/create' \
  -H 'accept: */*' \
  -H 'X-API-KEY: {your API key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "John Cooper",
    "email": "john@boldsign.dev"
  }'

Upon successful execution, you will receive a 201-response status code along with the sender identity resource ID in the response body. Make sure to store this ID in your database, as you may need it for making other API calls related to this sender identity. The following code shows the example response.

    
{
  "senderIdentityId": "a0f845a4-6272-4050-a4e8-6779a9b7886b"
}

Now you have successfully created a sender identity using the BoldSign API, allowing you to send documents on behalf of John Cooper. Please refer to this documentation for more details: Create a sender identity.

Configuring notification settings for a sender identity

When creating a sender identity, you can customize how the sender receives notifications for the documents sent on their behalf. By specifying the notification settings, you can control when they receive notifications for specific actions. If no notification settings are specified during creation, they will not receive any notifications for updates to their documents.

For instance, in the following example, the notification settings are defined so that the sender receives notifications when the document is sent and when it’s completed, but no notification will be sent if the signer fails the specified authentication. The following is how the request body looks for the previously described configuration.

    
curl -X 'POST' \
  'https://api.boldsign.com/v1/senderIdentities/create' \
  -H 'accept: */*' \
  -H 'X-API-KEY: {your API key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "John Cooper",
    "email": "john@boldsign.dev",
    "notificationSettings": {
      "sent": true,
      "completed": true,
      "authenticationFailed": false
    }
  }'
    

For a complete list of available notification settings, you can refer to this documentation.

It’s worth noting that you can update these notification settings in the future by using the sender identity update endpoint, which we will cover in later sections. This ensures that you can adapt the notification preferences based on the needs and preferences of the sender, John Cooper, in this case.

Approving a sender identity

After you have created the sender identity, the sender will receive an email containing a link to approve it. The email sent by BoldSign will provide clear information about the request, including details about the requester, the permissions being requested, and the reasons for the request.

Email for Approval
Email for sender identity approval

By clicking on the provided link within the email, the sender will be directed to the approval page, where they can review and approve the sender identity request.

Approve sender identity request
Approve sender identity request

On this approval page, they can grant consent for the sender identity to act on their behalf. This process ensures transparency and allows the sender to understand and authorize the permissions sought by the requester. By following this straightforward approval process, BoldSign ensures secure and accountable sender identity management for seamless document handling.

Resending approval request

In certain situations, it may be necessary to resend an approval request. The sender may have accidentally deleted the initial email or may not have noticed it yet. Resending the approval request serves as a reminder. This can be achieved by making a call to the POST /v1/senderIdentities/resendInvitation API endpoint. The below is an example of the API call using cURL:
    
curl -X 'POST' \
  'https://api.boldsign.com/v1/senderIdentities/resendInvitation?email=john@boldsign.dev' \
  -H 'accept: */*' \
  -H 'X-API-KEY: {your API key}' \
  -d ''

Users can resend the approval request up to five times for a specific sender identity. However, if an attempt is made to resend the approval request more than 5 times, a 400 response status code will be received, along with the following error message in the response body.

    
{
  "error": "Exceeded the maximum resend verification limit"
}

By having this resend functionality, BoldSign ensures that the approval process remains flexible and accommodating, allowing for effective communication and approval management. Please refer to this documentation for more details: Resend sender identity invitation.

Rerequesting approval

In cases where the recipient of the approval request has initially denied the request, there is an option to rerequest the approval. This can be done by making a call to the POST /v1/senderIdentities/rerequest API endpoint. The API call allows us to send a fresh approval request to the same recipient. Following is an example of the API call using cURL.
    
curl -X 'POST' \
  'https://api.boldsign.com/v1/senderIdentities/rerequest?email=john@boldsign.dev' \
  -H 'accept: */*' \
  -H 'X-API-KEY: {your API key}' \
  -d ''

By rerequesting the approval, you give the recipient another opportunity to review the request and reconsider their decision. This can be helpful if the initial denial was a result of oversight or if they needed more time to make an informed decision. Please refer to this documentation for more details: Rerequest sender identity approval.

Sending eSignature documents on behalf of others

Once the sender identity is created and approved, you can initiate the process of sending documents on the sender’s behalf. From the perspective of the signer, the document will appear to be sent by the person who approved the sender identity.

In this scenario, let’s say John has granted approval to Luther to send documents on his behalf. Consequently, Luther can now send documents on behalf of John. When the signer receives the document, they will see John’s name and email address as the sender, even though Luther is the one initiating the process.

In this simple example, to send a preconfigured template for signature on behalf of John, you need to specify John’s email address in the onBehalfOf field within the request body. The following is the request body for the API.
    
curl --location --request POST 'https://api.boldsign.com/v1/template/send?templateId=80e68eed-38d2-48f8-83b2-8e887e4cd32d' \
--header 'X-API-KEY: {your API key} \
--header 'Content-Type: application/json' \
--data-raw '{
  "onBehalfOf": "john@boldsign.dev"
}'

After executing the API call successfully, the response body will contain the document ID, which you can utilize to track the status of the document.

    
{
  "documentId": "de6350c1-cc8c-4120-a8ed-29e10b7249f4"
}

Please refer to this documentation for more details: Send document on someone’s behalf.

Signer's view of the signature request document

After the document has been successfully created and sent out for signature, the requested signer will receive an email containing a link to sign the document. The email received by the signer is depicted in the following image. It’s crucial to emphasize that the signer will see John’s name, not Luther’s, in the email, as John’s email address was specified in the onBehalfOf field within the request body.
Signer's view of the signature request
Signer's view of the signature request
This user-friendly approach ensures that the signer perceives the document sign request as coming directly from John, despite the fact that Luther initiated the process on his behalf. The specified onBehalfOf field facilitates seamless handling of document signing, providing a smooth and intuitive experience for all parties involved.

Tracking and managing documents on behalf of others

Once a person grants you permission to act on their behalf, you gain the ability not only to send documents on their behalf but also to manage these documents and perform certain actions. You can revoke a document, change the access code for a signer, retrieve document properties, download documents, and access the audit trail.

In the web application, you can easily monitor the list of documents that you have sent on behalf of others by navigating to the Documents -> Behalf Documents page. From there, you can perform the required actions, all within the web application.
Manage Documents from Web App
Managing documents from the web application
Manage documents overview
Overview of managed documents
To retrieve the list of documents sent on behalf of a particular person, you can use the /v1/document/behalfList API endpoint. By default, it will provide a list of all the documents sent with all approved sender identities. However, you can apply filters based on criteria such as email address, document status, signer email address, and date range.
Following is an example of an API request to list documents that you have sent on behalf of John with a status of WaitingForOthers:
    
curl --location 'https://api.boldsign.com/v1/document/behalfList?Status=WaitingForOthers&EmailAddress=john@boldsign.dev' \
--header 'accept: application/json' \
--header 'X-API-KEY: {your API key}'

By utilizing these tracking and management features, BoldSign ensures that the document workflow remains efficient, organized, and easily accessible to manage documents on behalf of others.

Revoke document on behalf of others

Similar to the behalfList API, you can interact with other document-related API endpoints, such as /v1/document/revoke, by utilizing the onBehalfOf field in the request body. This convenient approach allows you to perform various actions on behalf of others seamlessly. In fact, you can use the onBehalfOf field across all document-related API endpoints, making it a straightforward process.
In the following example, we have specified John’s email address in the onBehalfOf field in the request body to revoke a document.
    
curl --location 'https://api.boldsign.com/v1/document/revoke?documentId=de6350c1-cc8c-4120-a8ed-29e10b7249f4' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: {your API key}' \
--data-raw '{
  "message": "Sample revoke message",
  "onBehalfOf": "john@boldsign.dev"
}'

It’s important to note that providing the onBehalfOf field in the request body is essential for actions performed on behalf of others. If you omit this field, the API will respond with the following error message, prompting you to specify it. This ensures that you are appropriately executing actions on behalf of others and is not required for regular documents that you have sent under your own name.

    
{
  "error": "The email provided is not a valid sender identity."
}

Please refer to this documentation for more details: Revoke document.

Managing sender identities

In addition to document management, you can efficiently manage sender identities to perform various actions, such as updating notification settings, revoking sender identities, and deleting those that are no longer required, both through the API and the web application.

Updating notification settings

As previously discussed, you can update the notification settings for a sender identity at any time. By making an API call to the POST /v1/senderIdentities/update endpoint, you can control the type of email notifications the sender should receive for the documents. Following is an example of the API request to update notification settings for John’s sender identity.
    
curl -X 'POST' \
  'https://api.boldsign.com/v1/senderIdentities/update?email=john@boldsign.dev' \
  -H 'accept: */*' \
  -H 'X-API-KEY: {your API key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "notificationSettings": {
      "viewed": true,
      "sent": false,
      "deliveryFailed": true,
      "declined": true,
      "revoked": true,
      "reassigned": true,
      "completed": true,
      "signed": true,
      "expired": true,
      "authenticationFailed": true,
      "reminders": true
    }
  }'

Please refer to this documentation for more details: Update sender identity.

Deleting sender identity

If a sender identity is no longer required, you can delete it using the DELETE /v1/senderIdentities/delete API endpoint. It’s important to note that if you need to send documents on behalf of the same person in the future, you will need to obtain approval from them again. Following is an example of the API call to delete John’s sender identity.

    
curl -X 'DELETE' \
  'https://api.boldsign.com/v1/senderIdentities/delete?email=john@boldsign.dev' \
  -H 'accept: */*' \
  -H 'X-API-KEY: {your API key}'

Please refer to this documentation for more details: Delete sender identity.

Revoking sender identity permission

If the person who granted you permission to send documents on their behalf wishes to revoke that permission for any reason, they can easily do so:

  • Via email link: They can click on the link provided in the email they received when they initially approved the sender identity. This link will direct them to the approval page, where they have the option to revoke the access.
  • Using BoldSign account: If they have a BoldSign account, they can also revoke the permission by navigating to API -> Sender Identities within the web app and clicking the Revoke button associated with your sender identity.
Revoke sender permission
Revoke sender permission

By following either of these methods, they can promptly and easily revoke the permission they previously granted to send documents on their behalf. This ensures that the control over their sender identity remains in their hands, allowing for secure and accountable document handling.

Furthermore, by setting up webhooks, you can automate various actions based on the events received. For instance, when a sender identity is approved or denied, an email can be sent to the requester automatically. Similarly, notifications can be sent to the requester when a sender identity is revoked. For detailed instructions on configuring webhooks, please refer to the Webhooks documentation.

Conclusion

BoldSign’s API and web application combination empowers users to manage sender identities efficiently, streamline document workflows, and stay informed with real-time updates. Whether you are utilizing the API or the user-friendly web application, BoldSign ensures a seamless, secure, and collaborative experience for sending eSignature documents on behalf of others and managing them. Document management has never been more intuitive and efficient.

Please share your comments below. If you need any further assistance, schedule a demo or contact our support team through our support portal.

Share this blog

Subscribe RSS feed
Mohan Ravi

Mohan Ravi

A seasoned tech enthusiast with over 5 years of hands-on experience in the ever-evolving world of software development. From mastering the intricacies of .NET to harnessing the power of JavaScript, Mohan's expertise extends across the realms of full-stack development. A true problem-solver and a passionate coder at heart, he is always eager to explore new technologies and bring innovative ideas to life.

Share this blog

Mohan Ravi

Mohan Ravi

A seasoned tech enthusiast with over 5 years of hands-on experience in the ever-evolving world of software development. From mastering the intricacies of .NET to harnessing the power of JavaScript, Mohan's expertise extends across the realms of full-stack development. A true problem-solver and a passionate coder at heart, he is always eager to explore new technologies and bring innovative ideas to life.

Subscribe RSS feed

Leave a Reply

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