Skip to content
  1. Blog
  2. API

How to Manage Sender Identities with the BoldSign API

TL;DR: A sender identity lets your app send documents in another person’s name once they approve by email. Our API gives you one call each to create, update, list, resend, re-request or delete an identity. Our sender identity page shows how the feature works.

Say your app sends contracts for a sales director who is often travelling. Signers expect the director’s name on each request, but nobody should share the director’s password.

A sender identity solves that. This guide covers the API calls you use to create and look after sender identities, with code samples in six languages.

What is a sender identity in BoldSign?

A sender identity is a delegated profile that lets one user act for another person. The person approves your request by email, and then you can send documents in their name.

Think of a manager who signs a note saying their assistant may post letters for them. The note is the approval, and the letters still carry the manager’s name.

Our help article on user-level access for API keys and sender identities explains who can use each identity.

How does the sender identity lifecycle work?

Each identity moves through a few clear stages. You control most of them with the API.

  1. You create the identity with the person’s name and email, and we email them.
  2. The person approves or declines your request.
  3. You use the approved identity to send documents, reminders and audit logs.
  4. You update its details, resend the invitation or ask again after a decline.
  5. You delete the identity when a role changes or someone leaves.

What do you need before you start?

You need three things to follow the samples in this guide.

Send an API key in the X-API-KEY header, or an OAuth token as Authorization: Bearer. The samples here use an API key.

Which sender identity API endpoints will you use?

Every call goes to https://api.boldsign.com. The table lists each task in this guide with its endpoint.

Task Method Endpoint Success response
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

How do you create a sender identity via API?

Send a POST request with the person’s Name and Email, the two required fields. We then email the person to approve, and the identity works with OnBehalfOf once they do.

A successful call returns 201 Created with a senderIdentityId. Store that ID, since other calls can use it.

Which optional fields are worth setting?

  • RedirectUrl: the page the person lands on after they approve or decline.
  • BrandId: your brand on the approval email and page.
  • NotificationSettings: which document events send an email to the identity owner.
  • MetaData: up to 50 key and value pairs of your own data.
  • Locale: the language of the emails and the approval page.

Inside NotificationSettings, AttachSignedDocument adds the signed document and audit trail to the completion email. Files over 5 megabytes (MB) arrive as a download link instead, as our help article on the signed document in the completion email explains.

Our developer guide on how to create a sender identity lists every field. Here is a sample request in each language.

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": "Alex",
  "Email": "alex@example.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("Alex", "alex@example.com", null);
senderIdentityRequest.MetaData = new Dictionary<string, string>()
{
    ["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="Alex",
        email="alex@example.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('Alex');
$sender_identity_request->setEmail('alex@example.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("Alex");

senderIdentityRequest.setEmail("alex@example.com");

senderIdentitiesApi.createSenderIdentities(senderIdentityRequest);
import { SenderIdentitiesApi, CreateSenderIdentityRequest } from "boldsign";

const senderIdentitiesApi = new SenderIdentitiesApi();
senderIdentitiesApi.setApiKey("YOUR_API_KEY");

const senderIdentityRequest = new CreateSenderIdentityRequest();
senderIdentityRequest.name = "Alex";
senderIdentityRequest.email = "alex@example.com";

senderIdentitiesApi.createSenderIdentities(senderIdentityRequest);

How do you update a sender identity via API?

Send a POST request with the identity’s email as the email query parameter and the changed fields in the body. URL-encode the email, so alex@example.com becomes alex%40example.com.

The body needs at least one of Name, RedirectUrl, NotificationSettings, MetaData or Locale. Metadata follows three rules:

  • A key that already exists gets the new value.
  • A key that does not exist yet is added.
  • A key sent with an empty string is removed.

Keys you leave out stay as they are. Our guide on how to update a sender identity has the full field list.

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": "Alex Morgan",
  "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("Alex Morgan", "alex@example.com", null);
senderIdentityRequest.MetaData = new Dictionary<string, string>()
{
    ["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="Alex Morgan")

    sender_identities_api.update_sender_identities(
        email="alex@example.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('Alex Morgan');

$sender_identities_api->updateSenderIdentities($email = 'alex@example.com', $sender_identity_request);
ApiClient client = Configuration.getDefaultApiClient();
client.setApiKey("YOUR_API_KEY");

SenderIdentitiesApi senderIdentitiesApi = new SenderIdentitiesApi(client);

EditSenderIdentityRequest senderIdentityRequest = new EditSenderIdentityRequest();
senderIdentityRequest.setName("Alex Morgan");

senderIdentitiesApi.updateSenderIdentities("alex@example.com", senderIdentityRequest);
import { SenderIdentitiesApi, EditSenderIdentityRequest } from "boldsign";

const senderIdentitiesApi = new SenderIdentitiesApi();
senderIdentitiesApi.setApiKey("YOUR_API_KEY");

const senderIdentityRequest = new EditSenderIdentityRequest();
senderIdentityRequest.name = "Alex Morgan";

senderIdentitiesApi.updateSenderIdentities("alex@example.com", senderIdentityRequest);

How do you delete a sender identity via API?

Send a DELETE request with the identity’s email as the email query parameter. Deletion is permanent, so to use the identity again you create it again and the person approves a new request.

Delete an identity when an employee leaves or a role changes for good. Clean out identities nobody uses, too. Our guide on how to delete a sender identity covers the details.

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("alex@example.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="alex@example.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='alex@example.com');
ApiClient client = Configuration.getDefaultApiClient();
client.setApiKey("YOUR_API_KEY");

SenderIdentitiesApi senderIdentitiesApi = new SenderIdentitiesApi(client);
senderIdentitiesApi.deleteSenderIdentities("alex@example.com");
import { SenderIdentitiesApi } from "boldsign";

const senderIdentitiesApi = new SenderIdentitiesApi();
senderIdentitiesApi.setApiKey("YOUR_API_KEY");

senderIdentitiesApi.deleteSenderIdentities("alex@example.com");

How do you resend an invitation or request approval again?

Resend the invitation when the person has not approved yet. Ask again with rerequest when the person declined your first request.

How do you resend the invitation?

Send a POST request to the resendInvitation endpoint with the identity’s email. Use it when the person missed or deleted the first approval email. Our guide on how to resend an invitation has more detail.

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("alex@example.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="alex@example.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='alex@example.com');
ApiClient client = Configuration.getDefaultApiClient();
client.setApiKey("YOUR_API_KEY");

SenderIdentitiesApi senderIdentitiesApi = new SenderIdentitiesApi(client);
senderIdentitiesApi.resendInvitationSenderIdentities("alex@example.com");
import { SenderIdentitiesApi } from "boldsign";

const senderIdentitiesApi = new SenderIdentitiesApi();
senderIdentitiesApi.setApiKey("YOUR_API_KEY");

senderIdentitiesApi.resendInvitationSenderIdentities("alex@example.com");

How do you request approval again after a decline?

Send a POST request to the rerequest endpoint with the identity’s email. Use it when the person declined by mistake or has since agreed to the request. Our guide on how to re-request approval has more detail.

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("alex@example.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="alex@example.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='alex@example.com');
ApiClient client = Configuration.getDefaultApiClient();
client.setApiKey("YOUR_API_KEY");

SenderIdentitiesApi senderIdentitiesApi = new SenderIdentitiesApi(client);
senderIdentitiesApi.reRequestSenderIdentities("alex@example.com");
import { SenderIdentitiesApi } from "boldsign";

const senderIdentitiesApi = new SenderIdentitiesApi();
senderIdentitiesApi.setApiKey("YOUR_API_KEY");

senderIdentitiesApi.reRequestSenderIdentities("alex@example.com");

How do you list sender identities and filter them?

Send a GET request to the list endpoint with a page number. The response lists the sender identities under your BoldSign organization account, one page at a time.

The list call accepts these query parameters:

  • page: the page number to fetch, which is required.
  • pageSize: how many identities each page holds.
  • search: a filter on details such as name and email.
  • brandIds: a filter on the brands set when each identity was created.

Our guide on how to list sender identities shows the response format.

curl -X 'GET' \
  'https://api.boldsign.com/v1/senderIdentities/list?pageSize=10&page=1&search=alex&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<string> { "Your Brand Id" };
var senderIdentityList = senderIdentityClient.ListSenderIdentities(1, 10, "alex@example.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="alex@example.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='alex@example.com',$brandIds=['Your Brand Id']);
ApiClient client = Configuration.getDefaultApiClient();
client.setApiKey("YOUR_API_KEY");

SenderIdentitiesApi senderIdentitiesApi = new SenderIdentitiesApi(client);

List<String> brandIds = Arrays.asList("Your Brand Id");
SenderIdentityList senderIdentityList =
        senderIdentitiesApi.listSenderIdentities(1, 10, "alex@example.com", brandIds);
import { SenderIdentitiesApi } from "boldsign";

const senderIdentitiesApi = new SenderIdentitiesApi();
senderIdentitiesApi.setApiKey("YOUR_API_KEY");

const senderIdentityList = senderIdentitiesApi.listSenderIdentities(
  1,
  10,
  "alex@example.com",
  ["Your Brand Id"],
);

How do you get a sender identity’s full details?

Send a GET request to the properties endpoint with either the identity’s id or its email. One of the two is required.

Send just one of the two values to keep the request clear, as a mismatched pair makes errors hard to trace. The sample below uses the ID.

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="alex@example.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="alex@example.com");
ApiClient client = Configuration.getDefaultApiClient();
client.setApiKey("YOUR_API_KEY");

SenderIdentitiesApi senderIdentitiesApi = new SenderIdentitiesApi(client);
senderIdentitiesApi.getSenderIdentityProperties("SENDER_IDENTITY_ID", "alex@example.com");
import { SenderIdentitiesApi } from "boldsign";

const senderIdentitiesApi = new SenderIdentitiesApi();
senderIdentitiesApi.setApiKey("YOUR_API_KEY");

const senderIdentityDetails = senderIdentitiesApi.getSenderIdentityProperties(
  "SENDER_IDENTITY_ID",
);

How do you send documents on behalf of someone after approval?

Add the approved person’s email to the OnBehalfOf field when you send a document. The request then goes out in their name, and the document appears under Behalf Documents in the web app.

The field works the same whether you send from a template, a draft or an upload. Our developer guide on how to send a document on behalf of someone lists the actions you can take for them.

Our post on sending eSignature documents on behalf of others using APIs walks through a full example. For a comparison with app access, read OAuth vs sender identities explained.

What should you watch out for when managing sender identities?

Most problems come from approvals and from who owns each identity. Keep these points in mind.

  • Create identities early, since sending waits until the person approves.
  • Only the user who owns an identity can send and manage its documents.
  • Check the identity owner’s notification settings so they get the emails they expect.
  • Delete identities soon after someone leaves, and list them now and then to check.

Which BoldSign plan do you need for the sender identity API, and what does it cost?

Live API access, including sender identities, comes with the Enterprise API plan. It starts at $30 a month with 40 envelopes, and extra envelopes cost $0.75 each.

The plan includes unlimited templates and brands. You can build and test first in our free sandbox, where documents carry a test watermark. Prices are in USD, as listed on the BoldSign pricing page in November 2026.

Where do you go next with sender identities?

Start with one test identity in the sandbox, using your own second email address. Then build the calls your workflow needs.

Frequently asked questions

What is a sender identity in BoldSign?

A sender identity is a person who has approved you to send documents in their name. Signers see that person as the sender, while your app runs the process through our API.

Does the identity owner have to approve before I can send?

Yes. We email the person when you create the identity, and nothing goes out in their name until they approve.

Can the identity owner revoke access later?

Yes. The identity owner can withdraw your access at any time from the approval they gave.

What is the difference between resendInvitation and rerequest?

Use resendInvitation when the person has not approved yet, for example after a missed email. Use rerequest when the person declined and you want to ask again.

Can I recover a deleted sender identity?

No. A deleted sender identity cannot be retrieved. Create it again, and the person gets a new approval email.

Can other team members use my sender identities?

No. Sender identities are approved for one user account, so only the user who owns the identity can send and manage those documents.

How do I remove one metadata key from a sender identity?

Send an update request with that key and an empty string as its value. Keys you leave out of the request stay as they are.

Do I need a paid plan to test the sender identity API?

You can build and test for free in the API sandbox. Live calls need the Enterprise API plan, from $30 a month with 40 envelopes, billed yearly.

Ranjitha Vazhivittan

Ranjitha is a skilled software developer with 3 years of experience at BoldSign. Alongside her technical expertise, she has a passion for writing and enjoys sharing thoughtful insights on technology and development. Beyond work, she stays curious by exploring emerging tools and trends, constantly seeking opportunities to learn and grow.

More posts by Ranjitha Vazhivittan
Get started

Sign up for your free trial today!

Start free trial
  • 30-day free trial
  • No credit card required