How to Validate Sender Identity Using Properties API in BoldSign

TL;DR: The BoldSign Sender Identity Properties API retrieves complete details of a sender identity using either its ID or email address. It returns information such as the identity’s name, email, approval status, notification settings, branding, locale, and metadata. You can use this API as a pre-validation step before sending documents or performing on-behalf-of actions, helping reduce sender identity errors in automated workflows.

The Sender Identity Properties API is a GET endpoint that retrieves full sender identity information using either id or email as query parameters. It gives developers, workflow automation builders, SaaS teams, and admins a reliable way to confirm sender identity approval status, tenant mapping, and configuration before initiating any automated document workflow.

This API solves common issues such as failed sends, invalid identity references, unauthorized on behalf actions, and tenant mismatches, which frequently break automated workflows. By validating sender identity upfront, the Properties API ensures automated document operations stay secure, predictable, and compliant across multi user and multi tenant applications.

What the properties API does and how it improves sender identity validation?

The Properties API in Sender Identity returns all essential fields including name, email, approval status, brand settings, locale preferences, and metadata so your system can confirm that the sender identity exists, is approved, belongs to the correct tenant, and is properly configured before performing any workflow action. This early validation step prevents failures caused by unapproved or misconfigured identities and keeps multi tenant workflows stable and compliant.

What information does the properties API in sender identity return?

This endpoint returns all data required to validate readiness, legitimacy, and tenant mapping.

Which parameters does this API accept when fetching identity details?

To retrieve a sender identity properties, the Properties API requires at least one identifier either the id or the email. These parameters tell the API exactly which sender identity’s properties should be returned.

How to get the sender identity ID in BoldSign

The Properties API requires either a sender identity id or email. If you don’t already have the sender identity ID, you can obtain it through the following methods:

Retrieve ID using the sender identities list API

Use the List API to fetch all sender identities under your BoldSign organization

This endpoint returns each sender identity’s id, name, email, approval status, and other metadata. You can extract the sender identity ID from this response and use it directly in Properties API requests.

Get the ID after creating a sender identity via API

When creating a sender identity using the Sender Identities Create API, the response includes the newly generated sender identity ID.

Find the sender identity Email in the BoldSign dashboard

If you’re using the BoldSign web app, go to the Sender Identities page under the API section.
This page displays each sender identity’s email address, which you can use directly in the Properties API if the ID is not available.

Note: Store the retrieved sender identity ID (via List API or Create API) and reuse it for future requests to avoid repeated lookups.

What validation rules apply to properties API request?

The Properties API enforces clear input rules to ensure accurate identity retrieval:

• At least one of id or email must be provided.
• Providing both id and email is allowed.
• Providing neither id nor email returns a MissingParameter error.

These rules keep the API predictable and help you quickly diagnose integration issues.

Which endpoint is used to get sender identity properties?

You call this endpoint with either an id or an email as query parameter to fetch sender identity properties.

Refer to the official Sender Identity Details API documentation for detailed information and examples.

Sender identity properties API – Quick reference

A fast overview for developers integrating sender identity validation into automated workflows.

• Method: GET
• Endpoint: /v1/senderIdentities/properties
• Required: id or email
• Returns: Sender identity object
• Errors: Status Code – 400(MissingParameter/InvalidId/InvalidEmail)

How to get the sender identity properties using an API request and SDKs?

The following examples show how to fetch sender identity information using the Properties API endpoint in various programming languages.

You may provide either id or email, or both. When both are provided, the API prioritizes the id and retrieves the sender identity properties using the id value.

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 = "[email protected]")

<?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 ="[email protected]");
     

ApiClient client = Configuration.getDefaultApiClient();
client.setApiKey("YOUR_API_KEY");
SenderIdentitiesApi senderIdentitiesApi = new SenderIdentitiesApi(client);
senderIdentitiesApi.getSenderIdentityProperties("SENDER_IDENTITY_ID","[email protected]");
    

import { SenderIdentitiesApi } from "boldsign";
const senderIdentitiesApi = new SenderIdentitiesApi();
senderIdentitiesApi.setApiKey("YOUR_API_KEY");
senderIdentitiesApi.getSenderIdentityProperties("SENDER_IDENTITY_ID","[email protected]");
    

How does a successful properties API response look like?

A success response returns 200 OK and includes full sender identity properties. This structured JSON response allows applications to validate sender identity before executing any workflow operations.

Sample response from the properties API:

{
    "id": "2e96f9ad-xxxx-xxxx-xxxx-3063e73f04f8",
    "name": "Luther Cooper",
    "email": "[email protected]",
    "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 in sender identity handle validation errors?

The API performs strict pre‑validation and returns a 400 Bad Request error before any workflow action is executed.

Common mistakes when calling the sender identity properties API

Avoid these frequent issues that lead to failed validation or incorrect sender identity mapping:

• Calling the API without providing id or email
• Using malformed or non UUID id values
• Assuming the sender identity is approved without checking the status field
• Not validating tenantId in multi tenant applications
• Ignoring brand or locale mismatches that affect workflow routing

How does the properties API in sender identity prevent workflow disruptions?

Identity validation failures are one of the main causes of:

• Failed sends
• Unauthorized “on behalf of” actions
• Cross-tenant mismatches
• Misaligned brand/locale configurations

Calling the Properties API before any action ensures:

• The sender identity is approved
• The sender identity belongs to the correct tenant
• Notification preferences are aligned
• Branding and locale settings are correct
• The identity can legally and operationally perform the action

This dramatically improves reliability in automated sending workflows.

When should you use the properties API during workflow execution?

The Properties API in sender identity should be used whenever your system needs to confirm that a sender identity is valid, approved, and correctly mapped before performing any automated document action. Using it at the right stages eliminates unnecessary errors and ensures stable workflow execution.

Where does the properties API provide value in real workflows?

The Properties API in sender identity is widely used across industries and automation systems that require accurate sender identity validation before initiating document flows.

• HR onboarding systems validating sender identities before issuing offer letters
• Legal teams enforcing proper branding and audit readiness
• SaaS platforms ensuring tenant hierarchy integrity
• Assistant manager delegation workflows
• Scheduled workflows that require pre-send validation
• Customer self-service portals that generate contracts dynamically
• Compliance-driven industries requiring strict sender identity authorization

Final key takeaways

The Properties API in sender identity gives your automation a reliable way to confirm sender identity approval, tenant alignment, notification settings, and brand configuration before any workflow begins. By validating these details upfront, it eliminates common identity related failures, prevents unauthorized operations, and ensures document actions run smoothly across multi tenant environments. Incorporating this API into your validation logic leads to consistent, predictable, and secure document automation at scale.

Ready to streamline your signing workflows? Create a free BoldSign sandbox account and try it now. Need assistance? Reach us via the support portal or book a demo.

FAQs