BoldSign Sender Identity API – Send Documents Securely on Behalf of Others

The BoldSign Sender Identity API is designed specifically for API users and developers who need to perform document-related actions on behalf of another person in automated or system-driven workflows. It enables secure delegation for actions such as sending documents, reminders, and accessing audit logs without requiring the sender identity owner to have a BoldSign account.

Sender Identities work through an approval-based delegation model. The identity owner approves the request via email, after which API users can act on their behalf while maintaining clear audit trails and compliance. If the sender identity owner wants to view or manage documents directly, they may optionally create a BoldSign account, but it’s not required for delegation.

What are sender identities and why they matter

Sender Identities are a delegation mechanism, and you (the API caller) can perform supported operations on behalf of another person after they approve the request, which is useful for assistants, HR, sales ops, legal ops, and system-driven workflows.

This avoids issues such as:

Password or credential sharing.
Sender name inconsistency in emails, reminders, and audit trails.
Stalled workflows when the “real sender” is unavailable.

What is the sender identity lifecycle in BoldSign

A Sender Identity is a delegated profile that allows one user to act on behalf of another. Here’s an overview of the lifecycle:

Stage	Description
Create	Add a sender identity with a name and email. BoldSign emails the person for approval.
Approve or decline	The user approves or declines the request. Approval grants delegated rights.
Manage	Update details, resend invitations, or request approval again if needed.
Use	Send documents, reminders, revoke access, or download audit logs as the sender.
Delete	Remove identities when roles change or employees exit.
List	Retrieve all identities for visibility and compliance.
Get details	Fetch full properties for auditing or troubleshooting.

What you’ll need before you start

A BoldSign account, either sandbox or production
An API key or OAuth2 access token to call BoldSign APIs over HTTPS
A REST client such as cURL, Postman, or your preferred HTTP library

Authentication headers must be in one of the following formats:

API Key → X-API-KEY:
OAuth2 → Authorization: Bearer

Examples in this guide use API Key authentication for clarity.

BoldSign sender identity API endpoints used in this guide

Task	Method	Endpoint	Typical success
Create sender identity	POST	/v1/senderIdentities/create	201 Created
Update sender identity	POST	/v1/senderIdentities/update	204 No content
Delete sender identity	DELETE	/v1/senderIdentities/delete	204 No content
Resend invitation	POST	/v1/senderIdentities/resendInvitation	204 No content
Request approval again	POST	/v1/senderIdentities/rerequest	204 No content
List sender identities	GET	/v1/senderIdentities/list	200 Success
Get identity details	GET	/v1/senderIdentities/properties	200 Success

Sender identities are user-level delegations

In BoldSign, sender identities are defined at the user level, not across the entire organization. As a result, you can:

Limit visibility: A sender identity is visible and usable only to the user who created it. Other team members cannot automatically view or use these identities.
Follow legal and compliance requirements: This behavior is intentional and helps to meet legal and compliance obligations, ensuring sender identities are protected from unintended access or exposure.

How do you create a sender identity via API

To act on behalf of another user, first create a sender identity.

Required inputs:

name: Full name of the sender Identity.
email: The email address of the sender identity.

What inputs are optional but commonly used

RedirectUrl: Where the identity owner lands after approval or rejection.
BrandId: Brand-aware emails and approval page.
NotificationSettings: What the onBehalfOf email receives.
MetaData: Up to 50 key or value pairs.
Locale: Email and approval page language.
AttachSignedDocument: When enabled while the Completed option is also enabled, the completion email includes the signed document and audit trail. If the document is ≤ 5 MB, it is attached directly. If it’s larger, a secure download link is provided instead.

BoldSign then sends an approval email to the sender identity email. Once approved, the identity becomes usable for OnBehalfOf operations.

You can find detailed instructions in our documentation. Here’s a basic code example that shows how to create a sender identity using the BoldSign API.

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;odata.metadata=minimal;odata.streaming=true' \ 
  -d '{ 
  "Name": "Luther Cooper", 
  "Email": "luthercooper@cubeflakes.com", 
  "RedirectUrl": "https://boldsign.com", 
  "BrandId": "Your Brand Id ", 
  "NotificationSettings": { 
    "Viewed": true, 
    "Sent": false, 
    "DeliveryFailed": true, 
    "Declined": true, 
    "Revoked": true, 
    "Reassigned": true, 
    "Completed": true, 
    "Signed": true, 
    "Expired": true, 
    "AuthenticationFailed": true, 
    "Reminders": true, 
    "AttachSignedDocument": false 
  }, 
  "MetaData": { 
    "TenantId": "xxxxx070-xxxx-xxxx-xxxx-757xxxxxxxxx", 
    "AccountPlan": "Free" 
  }, 
  "Locale": "EN" 
}'

var apiClient = new ApiClient("https://api.boldsign.com", "Your_API_Key"); 
var senderIdentityClient = new SenderIdentityClient(apiClient); 
var senderIdentityRequest = new SenderIdentityRequest("Luther Cooper", "luthercooper@cubeflakes.com", null); 
senderIdentityRequest.MetaData = new Dictionary() 
{ 
  ["tenantId"] = "xxxxx070-xxxx-xxxx-xxxx-757xxxxxxxxx", 
  ["accountPlan"] = "Free" 
}; 
var senderIdentityCreated = senderIdentityClient.CreateSenderIdentity(senderIdentityRequest);

import boldsign 
configuration = boldsign.Configuration(api_key="YOUR_API_KEY") 
with boldsign.ApiClient(configuration) as api_client: 
    sender_identities_api = boldsign.SenderIdentitiesApi(api_client) 
    sender_identity_request = boldsign.CreateSenderIdentityRequest( 
        name="Luther Cooper", 
        email="luthercooper@cubeflakes.com", 
    ) 
    sender_identities_api.create_sender_identities(sender_identity_request)

<?php require_once "vendor/autoload.php"; 
use BoldSign\Configuration; 
use BoldSign\Api\SenderIdentitiesApi; 
use BoldSign\Model\CreateSenderIdentityRequest; 
$config = new Configuration(); 
$config->setApiKey('YOUR_API_KEY'); 
$sender_identities_api = new SenderIdentitiesApi($config); 
$sender_identity_request = new CreateSenderIdentityRequest(); 
$sender_identity_request->setName('Luther Cooper'); 
$sender_identity_request->setEmail('luthercooper@cubeflakes.com'); 
$sender_identities_api->createSenderIdentities($sender_identity_request);

ApiClient client = Configuration.getDefaultApiClient();   
client.setApiKey("YOUR_API_KEY"); 
SenderIdentitiesApi senderIdentitiesApi = new SenderIdentitiesApi(client); 
CreateSenderIdentityRequest senderIdentityRequest = new CreateSenderIdentityRequest(); 
senderIdentityRequest.setName("Luther Cooper"); 
senderIdentityRequest.setEmail("luthercooper@cubeflakes.com"); 
senderIdentitiesApi.createSenderIdentities(senderIdentityRequest);

import { SenderIdentitiesApi, CreateSenderIdentityRequest } from "boldsign"; 
const senderIdentitiesApi = new SenderIdentitiesApi(); 
senderIdentitiesApi.setApiKey("YOUR_API_KEY"); 
const senderIdentityRequest = new CreateSenderIdentityRequest(); 
senderIdentityRequest.name = "Luther Cooper"; 
senderIdentityRequest.email = "luthercooper@cubeflakes.com"; 
senderIdentitiesApi.createSenderIdentities(senderIdentityRequest);

How do you update a sender identity via API

Use this when you need to correct or modify an existing sender identity.

Required inputs:

Email: Passed as a query parameter in the request URL.
Updated fields: Provided in the request body, like Name,RedirectUrl, NotificationSettings, MetaData, and Locale.
Metadata update behavior:
- If the key exists, metadata is updated.
- If the key doesn’t exist, metadata is added.
- If the value is null or an empty string, metadata is removed.

Importantly, you must URL-encode the email. For example, you would change

luthercooper@cubeflakes.com to luthercooper%40cubeflakes.com.

For more details, refer to our official documentation. Here’s a sample code snippet that shows how to update a sender identity using the BoldSign API.

cURL

curl -X 'POST' \ 
  'https://api.boldsign.com/v1/senderIdentities/update?email={Your Encoded Email}' \ 
      -H 'accept: */*' \ 
      -H 'X-API-KEY: {your API key}' \ 
      -H 'Content-Type: application/json;odata.metadata=minimal;odata.streaming=true' \ 
      -d '{ 
          "Name": "Luther", 
          "RedirectUrl": "https://boldsign.com", 
          "NotificationSettings": { 
            "Viewed": true, 
            "Sent": false, 
            "DeliveryFailed": true, 
            "Declined": true, 
            "Revoked": true, 
            "Reassigned": true, 
            "Completed": true, 
            "Signed": true, 
            "Expired": true, 
            "AuthenticationFailed": true, 
            "Reminders": true, 
            "AttachSignedDocument": false 
          }, 
          "MetaData": { 
            "AccountPlan": "Paid" 
          }, 
         "Locale": "EN" 
        }'


var apiClient = new ApiClient("https://api.boldsign.com", "Your_API_Key"); 
var senderIdentityClient = new SenderIdentityClient(apiClient); 
var senderIdentityRequest = new SenderIdentityRequest("Luther", "luthercooper@cubeflakes.com", null); 
senderIdentityRequest.MetaData = new Dictionary() 
{ 
  ["accountPlan"] = "Paid" 
}; 
senderIdentityClient.UpdateSenderIdentity(senderIdentityRequest);

import boldsign 
configuration = boldsign.Configuration(api_key="YOUR_API_KEY") 
with boldsign.ApiClient(configuration) as api_client:   
    sender_identities_api = boldsign.SenderIdentitiesApi(api_client)  
    sender_identity_request = boldsign.EditSenderIdentityRequest(name="Luther") 
     
sender_identities_api.update_sender_identities(email="luthercooper@cubeflakes.com", edit_sender_identity_request=sender_identity_request)

<?php require_once "vendor/autoload.php"; 
use BoldSign\Configuration; 
use BoldSign\Api\SenderIdentitiesApi; 
use BoldSign\Model\EditSenderIdentityRequest; 
$config = new Configuration(); 
$config->setApiKey('YOUR_API_KEY'); 
$sender_identities_api = new SenderIdentitiesApi($config); 
$sender_identity_request = new EditSenderIdentityRequest(); 
$sender_identity_request->setName('Luther'); 
$sender_identities_api->updateSenderIdentities($email = 'luthercooper@cubeflakes.com', $sender_identity_request);

ApiClient client = Configuration.getDefaultApiClient();   
client.setApiKey("YOUR_API_KEY"); 
SenderIdentitiesApi senderIdentitiesApi = new SenderIdentitiesApi(client);
 
EditSenderIdentityRequest senderIdentityRequest = new EditSenderIdentityRequest(); 
senderIdentityRequest.setName("Luther"); 
senderIdentitiesApi.updateSenderIdentities("luthercooper@cubeflakes.com", senderIdentityRequest);

import { SenderIdentitiesApi, EditSenderIdentityRequest } from "boldsign"; 
const senderIdentitiesApi = new SenderIdentitiesApi(); 
senderIdentitiesApi.setApiKey("YOUR_API_KEY"); 
const senderIdentityRequest = new EditSenderIdentityRequest(); 
senderIdentityRequest.name = "Luther"; 
senderIdentitiesApi.updateSenderIdentities("luthercooper@cubeflakes.com", senderIdentityRequest);

How do you delete a sender identity via API

You can delete a sender identity, which removes the sender identity altogether, and it can’t be retrieved again. To use it again later, you must recreate it and reapprove.

Required input:

Sender identity email

When to use:

Employee exit: Remove access when an employee leaves the organization.
Permanent role change: Delete identities that are no longer relevant due to a change in responsibilities.
Security compliance: Ensure only active and authorized identities remain in your system.

Check the official documentation for complete usage guidelines. Here’s a sample code snippet that shows how to delete a sender identity using the BoldSign API.

cURL

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

var apiClient = new ApiClient("https://api.boldsign.com", "Your_API_Key"); 
var senderIdentityClient = new SenderIdentityClient(apiClient);
 
senderIdentityClient.DeleteSenderIdentity("luthercooper@cubeflakes.com");

import boldsign 
configuration = boldsign.Configuration(api_key="YOUR_API_KEY") 
with boldsign.ApiClient(configuration) as api_client: 
    sender_identities_api = boldsign.SenderIdentitiesApi(api_client) 
    sender_identities_api.delete_sender_identities(email="luthercooper@cubeflakes.com")

<?php require_once "vendor/autoload.php"; 
use BoldSign\Configuration; 
use BoldSign\Api\SenderIdentitiesApi; 
$config = new Configuration(); 
$config->setApiKey('YOUR_API_KEY'); 
$sender_identities_api = new SenderIdentitiesApi($config); 
$sender_identities_api->deleteSenderIdentities($email='luthercooper@cubeflakes.com');

ApiClient client = Configuration.getDefaultApiClient();   
client.setApiKey("YOUR_API_KEY");           
SenderIdentitiesApi senderIdentitiesApi = new SenderIdentitiesApi(client); 
senderIdentitiesApi.deleteSenderIdentities("luthercooper@cubeflakes.com");

import { SenderIdentitiesApi } from "boldsign"; 
const senderIdentitiesApi = new SenderIdentitiesApi(); 
senderIdentitiesApi.setApiKey("YOUR_API_KEY"); 
senderIdentitiesApi.deleteSenderIdentities("luthercooper@cubeflakes.com");

How do you resend an invitation or request approval again

Action	When to use	Endpoint	Usage Scenario
Resend invitation	Original approval email was missed or deleted	POST /v1/senderIdentities/resendInvitation	Sender accidentally deleted the approval email.
Request approval again	Request was declined by mistake or the user changed their mind	POST /v1/senderIdentities/rerequest	Sender initially declined but later agreed to delegate.

Refer to the official documentation for detailed information. Here’s a sample code snippet that shows how to resend an invitation for a sender identity using the BoldSign API.

cURL

curl -X 'POST' \ 
  'https://api.boldsign.com/v1/senderIdentities/resendInvitation?email={Your Encoded Email}' \ 
      -H 'accept: */*' \ 
      -H 'X-API-KEY: {your API key}' \ 
      -d ''

var apiClient = new ApiClient("https://api.boldsign.com", "Your_API_Key"); 
var senderIdentityClient = new SenderIdentityClient(apiClient); 
senderIdentityClient.ResendInvitation("luthercooper@cubeflakes.com");


import boldsign 
configuration = boldsign.Configuration(api_key="YOUR_API_KEY") 
 
with boldsign.ApiClient(configuration) as api_client:     
    sender_identities_api = boldsign.SenderIdentitiesApi(api_client) 
    sender_identities_api.resend_invitation_sender_identities(email="luthercooper@cubeflakes.com")

<?php require_once "vendor/autoload.php"; 
use BoldSign\Configuration; 
use BoldSign\Api\SenderIdentitiesApi; 
$config = new Configuration(); 
$config->setApiKey('YOUR_API_KEY'); 
$sender_identities_api = new SenderIdentitiesApi($config); 
$sender_identities_api->resendInvitationSenderIdentities($email='luthercooper@cubeflakes.com');

ApiClient client = Configuration.getDefaultApiClient();   
client.setApiKey("YOUR_API_KEY");           
SenderIdentitiesApi senderIdentitiesApi = new SenderIdentitiesApi(client); 
senderIdentitiesApi.resendInvitationSenderIdentities("luthercooper@cubeflakes.com");

import { SenderIdentitiesApi } from "boldsign"; 
const senderIdentitiesApi = new SenderIdentitiesApi(); 
senderIdentitiesApi.setApiKey("YOUR_API_KEY"); 
senderIdentitiesApi.resendInvitationSenderIdentities("luthercooper@cubeflakes.com");

Refer to the official guide for more information. Here’s a sample code snippet that shows how to resend an approval request for a sender identity using the BoldSign API.

cURL

curl -X 'POST' \ 
  'https://api.boldsign.com/v1/senderIdentities/rerequest?email={Your Encoded Email}' \ 
      -H 'accept: */*' \ 
      -H 'X-API-KEY: {your API key}'

var apiClient = new ApiClient("https://api.boldsign.com", "Your_API_Key"); 
var senderIdentityClient = new SenderIdentityClient(apiClient); 
senderIdentityClient.RerequestSenderIdentity("luthercooper@cubeflakes.com");

import boldsign 
configuration = boldsign.Configuration(api_key="YOUR_API_KEY") 
with boldsign.ApiClient(configuration) as api_client:  
    sender_identities_api = boldsign.SenderIdentitiesApi(api_client)  sender_identities_api.re_request_sender_identities(email="luthercooper@cubeflakes.com")

<?php require_once "vendor/autoload.php"; 
use BoldSign\Configuration; 
use BoldSign\Api\SenderIdentitiesApi; 
$config = new Configuration(); 
$config->setApiKey('YOUR_API_KEY'); 
$sender_identities_api = new SenderIdentitiesApi($config); 
$sender_identities_api->reRequestSenderIdentities($email='luthercooper@cubeflakes.com');

ApiClient client = Configuration.getDefaultApiClient();   
client.setApiKey("YOUR_API_KEY"); 
         
SenderIdentitiesApi senderIdentitiesApi = new SenderIdentitiesApi(client); 
senderIdentitiesApi.reRequestSenderIdentities("luthercooper@cubeflakes.com");

import { SenderIdentitiesApi } from "boldsign"; 
const senderIdentitiesApi = new SenderIdentitiesApi(); 
senderIdentitiesApi.setApiKey("YOUR_API_KEY"); 
senderIdentitiesApi.reRequestSenderIdentities("luthercooper@cubeflakes.com");

How do you list sender identities and filter them

List identities

This lists sender identities under your BoldSign organization account, with paging and optional filtering.

Query parameters:

pageSize: Number of identities per page
page: Page number to fetch
search: Filter by attributes such as name and email address
brandIds: Filter by brand

For more details, see the official documentation. Here’s a sample code snippet.

cURL

curl -X 'GET' \ 
  'https://api.boldsign.com/v1/senderIdentities/list?pageSize=10&page=1&search= luthercooper &brandIds[0]=Your Brand Id' \ 
      -H 'accept: application/json' \ 
      -H 'X-API-KEY: {your API key}'

var apiClient = new ApiClient("https://api.boldsign.com", "Your_API_Key"); 
var senderIdentityClient = new SenderIdentityClient(apiClient); 
 var brandIds = new List { "Your Brand Id" }; 
    var senderIdentityList = senderIdentityClient.ListSenderIdentities(1, 10, "luthercooper@cubeflakes.com", brandIds);

import boldsign 
configuration = boldsign.Configuration(api_key="YOUR_API_KEY") 
 
with boldsign.ApiClient(configuration) as api_client: 
     
    sender_identities_api = boldsign.SenderIdentitiesApi(api_client) 
    sender_identity_list = sender_identities_api.list_sender_identities(page=1,page_size=10,search="luthercooper@cubeflakes.com",brand_ids=["Your Brand Id"])

<?php require_once "vendor/autoload.php"; 
use BoldSign\Configuration; 
use BoldSign\Api\SenderIdentitiesApi; 
$config = new Configuration(); 
$config->setApiKey('YOUR_API_KEY'); 
$sender_identities_api = new SenderIdentitiesApi($config); 
$sender_identity_list = $sender_identities_api->listSenderIdentities($page = 1,$page_Size=10,$search='luthercooper@cubeflakes.com',$brandIds=['Your Brand Id']);

ApiClient client = Configuration.getDefaultApiClient();   
client.setApiKey("YOUR_API_KEY"); 
SenderIdentitiesApi senderIdentitiesApi = new SenderIdentitiesApi(client); 
List brandIds = Arrays.asList("Your Brand Id"); 
SenderIdentityList senderIdentityList = senderIdentitiesApi.listSenderIdentities(1, 10, "luthercooper@cubeflakes.com", brandIds);

import { SenderIdentitiesApi } from "boldsign"; 
const senderIdentitiesApi = new SenderIdentitiesApi(); 
senderIdentitiesApi.setApiKey("YOUR_API_KEY"); 
const senderIdentityList = senderIdentitiesApi.listSenderIdentities(1,10,"luthercooper@cubeflakes.com",["Your Brand Id"]);

How do you fetch a sender identity’s full details

You can fetch details either by ID or email. If both are sent, BoldSign prioritizes the ID and ignores the email. This can cause confusion if the two values don’t match, so the best practice is to send only one.

Check the official documentation for complete usage guidelines.

cURL:

curl -X 'GET' \ 'https://api.boldsign.com/v1/senderIdentities/properties?id=2e96f9ad-xxxx-xxxx-xxxx-3063e73f04f8' \ 
      -H 'accept: application/json' \ 
      -H 'X-API-KEY: {your API key}'

var apiClient = new ApiClient("https://api.boldsign.com", "Your_API_Key"); 
var senderIdentityClient = new SenderIdentityClient(apiClient); 
var senderIdentityDetails = senderIdentityClient.GetProperties("2e96f9ad-xxxx-xxxx-xxxx-3063e73f04f8");

import boldsign 
configuration = boldsign.Configuration(api_key="YOUR_API_KEY") 
with boldsign.ApiClient(configuration) as api_client: 
    sender_identities_api = boldsign.SenderIdentitiesApi(api_client) 
    sender_identities_api.get_sender_identity_properties(id = "SENDER_IDENTITY_ID",email = "luthercooper@cubeflakes.com")

<?php require_once "vendor/autoload.php"; 
use BoldSign\Configuration; 
use BoldSign\Api\SenderIdentitiesApi; 
$config = new Configuration(); 
$config->setApiKey('YOUR_API_KEY'); 
$sender_identities_api = new SenderIdentitiesApi($config); 
$sender_identities_api->getSenderIdentityProperties("SENDER_IDENTITY_ID",$email="luthercooper@cubeflakes.com");

ApiClient client = Configuration.getDefaultApiClient();   
client.setApiKey("YOUR_API_KEY"); 
SenderIdentitiesApi senderIdentitiesApi = new SenderIdentitiesApi(client); 
senderIdentitiesApi.getSenderIdentityProperties("SENDER_IDENITY_ID","luthercooper@cubeflakes.com");

import { SenderIdentitiesApi } from "boldsign"; 
const senderIdentitiesApi = new SenderIdentitiesApi(); 
senderIdentitiesApi.setApiKey("YOUR_API_KEY"); 
const senderIdentityList = senderIdentitiesApi.listSenderIdentities(1,10,"luthercooper@cubeflakes.com",["Your Brand Id"]);

How do you send documents on behalf of someone after approval

After the sender identity is approved, use the OnBehalfOf field when sending documents so the request appears to come from the approved identity owner. BoldSign refers to these as OnBehalfOf documents.

The exact “send document” endpoint depends on whether you send from a template, draft, or direct upload, but the concept is the same, include the onBehalfOf field with the approved sender identity email.

Real-world use cases

Sales contract during manager travel: Delegate sending contracts to associates while the manager is away.
HR recruiter name correction: Update misspelled recruiter details for professionalism.
Legal team member exit: Delete identity to prevent unauthorized use.
Missed approval email: Resend invitation to ensure timely approval.
Accidental decline of request: Resend an approval request to restore access.
Organization-wide audit: List identities for compliance across HR, legal, and sales.

Best practices for secure on behalf of workflows

When performing actions on behalf of others, like managing sender identities or sending documents, always use a dedicated system identity rather than a personal user account.

This matters when you want to ensure:

Consistency: Notifications appear uniform and professional.
Privacy protection: Individual user details remain secure.
Simplified management: Easier credential rotation and streamlined audit logging.

We recommend you use a neutral email address like admin@companyname.com for all delegated activities.

Conclusion

The BoldSign sender identity API ensures secure, flexible workflows by allowing you to act on behalf of others without sharing credentials. This keeps your document process professional, fast, and transparent.

Get started today! Sign up for a free BoldSign sandbox account and begin managing sender identities with just a few API calls. For questions or assistance, visit our support portal.

Related blogs

Note: This blog was originally published at boldsign.com

Search This Blog

BoldSign Blogs