Skip to content
  1. Blog
  2. API

How to Validate Sender Identity Using the Properties API in BoldSign

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
email 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
email 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.

  1. Call the Properties API with the stored ID.
  2. Confirm that status is Approved.
  3. Compare the tenant ID in metaData with the customer who asked for the send.
  4. Check brandId and locale against what that customer expects.
  5. Send the document with OnBehalfOf set 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.

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.

Gayathri Annamalai

Gayathri Annamalai is a software developer with 1 year of experience at BoldSign. She enjoys continuous learning, strengthening her technical skills, and exploring new tools and technologies. She also has an interest in writing clear and helpful content for developers. Connect with her on LinkedIn.

More posts by Gayathri Annamalai
Get started

Sign up for your free trial today!

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