TL;DR: The Properties API returns one sender identity’s details, such as its status, settings and metadata, from its ID or email. Call it before you send in someone’s name, and your app can stop when the identity is not approved or belongs to another tenant. Our sender identity page explains the feature.
Say your app sends offer letters in a hiring manager’s name. One morning the sends start failing. The manager never approved the request, or the identity belongs to a different customer account in your app.
A quick read of the identity before each send catches both problems. This guide shows what the Properties API returns, how to call it and what to check in the reply.
What does the Properties API do for sender identity validation?
The Properties API reads the stored details of one sender identity. Your app uses those details to confirm that the identity exists, is approved and is set up the way you expect.
Think of it as checking a parcel label before you post it. The parcel may be fine, but a wrong address sends it nowhere.
A sender identity lets you send documents in another person’s name once they approve by email. Our guide on how to manage sender identities with the BoldSign API covers creating, updating and deleting them.
What information does the Properties API return?
Each reply describes one identity in full. The table lists every field and what it tells you.
| Property | What it holds |
|---|---|
| id | The sender identity’s unique ID |
| name | The display name of the identity |
| The email address used for sends in that person’s name | |
| status | The approval state, such as Approved or Pending |
| createdBy | The ID of the user who created the identity |
| approvedDate | When the person approved, empty until then |
| redirectUrl | The page the person sees after they answer the request |
| brandId | The brand linked to the identity |
| notificationSettings | True or false for each email event the person receives |
| metaData | Your own key and value pairs, such as a tenant ID |
| locale | The language of the emails and approval page |
Which parameters does the Properties API accept?
The call takes two query parameters, and you need at least one. Both tell the API which identity to look up.
| Parameter | Type | Description |
|---|---|---|
| id | string | The sender identity ID |
| string | The sender identity’s email address |
How do you get the sender identity ID in BoldSign?
Use the list endpoint or keep the ID from the create call. You can also skip the ID and pass the person’s email address instead.
Get the ID from the list endpoint
The list endpoint returns every sender identity in your account. Each entry includes its ID, name, email and approval status.
| Method | Endpoint |
|---|---|
| GET | https://api.boldsign.com/v1/senderIdentities/list |
Keep the ID from the create call
The create endpoint returns the new identity’s ID in its reply. Store it with the user record in your app, and you avoid repeat lookups later.
| Method | Endpoint |
|---|---|
| POST | https://api.boldsign.com/v1/senderIdentities/create |
What validation rules apply to a Properties API request?
Each request must include an ID, an email address or both. A request with neither returns a MissingParameter error.
Our code samples pass both values. Passing the ID alone is the simplest choice once you have stored it.
Which endpoint returns sender identity properties?
Send a read-only request (GET) to the properties endpoint with an ID or email as a query parameter. The reply holds the full sender identity.
| Task | Method | Endpoint |
|---|---|---|
| Get sender identity properties | GET | https://api.boldsign.com/v1/senderIdentities/properties |
Our identity details API reference has the full field list and samples.
How do you call the Properties API with client URL (cURL) and the software development kits (SDKs)?
The samples below call the endpoint in six languages. Replace the API key and the ID with your own values.
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\Api\SenderIdentitiesApi;
$config = new BoldSign\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");
senderIdentitiesApi.getSenderIdentityProperties(
"SENDER_IDENTITY_ID",
"alex@example.com",
);
What does a successful Properties API response look like?
A successful call returns 200 Success with the identity as JavaScript Object Notation (JSON). In this sample, the status is Pending and approvedDate is empty, so the person has not approved yet.
Sample response from the Properties API:
{
"id": "2e96f9ad-xxxx-xxxx-xxxx-3063e73f04f8",
"name": "Alex",
"email": "alex@example.com",
"status": "Pending",
"createdBy": "516f5251-xxxx-xxxx-xxxx-04b5e34c5968",
"approvedDate": "",
"redirectUrl": "https://boldsign.com",
"brandId": "6f4020a7-xxxx-xxxx-xxxx-ef071e143867",
"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"
}
How does the Properties API report validation errors?
A failed lookup returns an error type that names the problem. Check the type in your code and show the user a clear message.
| Error type | Meaning |
|---|---|
| MissingParameter | The request has neither an ID nor an email address |
| InvalidId | The sender identity ID is invalid |
| InvalidEmail | The sender identity email address is invalid |
What mistakes should you avoid with the Properties API?
Most failed checks come from a few habits. Watch for these in your code.
- Calling the endpoint with an empty ID and an empty email address.
- Passing an ID that is not a valid universally unique identifier (UUID).
- Sending in someone’s name before the status field says Approved.
- Skipping the tenant ID check in an app that serves many customers.
- Reading the brand or locale once and missing later changes.
How does a validation check prevent failed sends?
A check before each send stops a request that would fail or go out under the wrong name. Your app reads the identity, compares a few fields and only then sends.
- Call the Properties API with the stored ID.
- Confirm that status is Approved.
- Compare the tenant ID in metaData with the customer who asked for the send.
- Check brandId and locale against what that customer expects.
- Send the document with
OnBehalfOfset to the identity’s email.
A multi-tenant app serves many customer accounts from one system. Step 3 keeps one customer’s identity out of another customer’s documents.
When should you call the Properties API in your workflow?
Call it whenever your app is about to act in someone’s name or needs fresh identity details. The table shows the usual moments.
| Moment | Why you check |
|---|---|
| Before an automatic send | Confirms the identity is approved |
| Before a remind, revoke or reassign action in someone’s name | Confirms the identity matches the right user |
| When you map identities to customer accounts | Keeps identities with the right tenant |
| After an invalid sender identity error | Shows which setting is wrong |
| After you invite a new identity | Lets you poll until the status changes |
| When you update user records | Keeps brand, locale and alerts in step |
Where does a sender identity check help in real workflows?
Any app that sends in other people’s names benefits from a check first. Here are a few common cases.
- An HR system that sends offer letters in each hiring manager’s name.
- A software as a service (SaaS) platform that sends contracts for many customer accounts.
- A self-service portal that builds and sends contracts on demand.
- A scheduled job that sends documents overnight with no one watching.
Which BoldSign plan do you need for the Properties API, and what does it cost?
Live API calls, including sender identities, need the Enterprise API plan. It starts at $30 a month with 40 envelopes, and each extra envelope costs $0.75.
The plan includes unlimited templates and brands. You can build and test first in our free sandbox. Prices are in USD, billed yearly, as listed on the BoldSign pricing page in November 2026.
How can you start validating sender identities today?
Add one Properties API call before each send, and test it in the sandbox first.
- Create a free API sandbox account and call the endpoint with a test identity.
- Book a demo to talk through your sender identity setup with our team.
- Ask a question on our support portal when a call returns an error you do not expect.
Frequently asked questions
How many sender identities can I fetch with one Properties API call?
One. Each call returns the sender identity that matches the ID or email you pass. Use the list endpoint when you need every identity at once.
Can I update a sender identity with the Properties API?
No. The Properties API only reads details. Use the update, delete or create endpoints when you need to change an identity.
Can I call the Properties API without an ID or email?
No. The call needs at least one of the two, or you get a MissingParameter error.
Does the response show whether the sender identity is approved?
Yes. The status field holds the approval state, such as Approved or Pending. The approvedDate field stays empty until the person approves.
Does the Properties API return notification settings?
Yes. The notificationSettings object lists each email event, such as viewed, signed or reminders, with true or false. Your app can match its own alerts to these values.
What does the metaData field in the response hold?
It holds the key and value pairs you saved when you created or updated the identity. You can store a tenant ID there and check the owner later.
How do I find a sender identity ID if I lost it?
Call the list endpoint, which returns every sender identity with its ID. You can also pass the person's email address to the Properties API instead of the ID.
Do I need a paid plan to use the Properties API?
You can test it for free in our API sandbox. Live calls need the Enterprise API plan, from $30 a month with 40 envelopes, billed yearly.