How to use branding with sender identities (OnBehalfOf) in the API?

When sending documents using a sender identity (OnBehalfOf), it is important to understand how branding is applied in BoldSign.

The brand ID configured on a sender identity is used only for sender identity approval, rejection, and revocation emails, as well as related approval pages. The branding displayed to document recipients is determined by the BrandId specified in the document send API request.

This article explains how branding works when using sender identities and how to ensure the correct brand is displayed to recipients.

Understanding branding behavior

When a sender identity is used, branding is applied differently depending on the workflow.

Branding controlled by the sender identity’s brand ID

The brand ID configured on the sender identity is used for:

• Sender identity approval emails
• Sender identity rejection emails
• Sender identity revocation emails
• Sender identity approval pages

Branding controlled by the BrandId in the document send request

The BrandId specified in the document send request is used for:

• Recipient notification emails
• Signing pages
• Recipient-facing branding elements

Important: Once a sender identity is approved, it can be used with any brand available in the account. The brand assigned to the sender identity does not restrict the brand used when sending documents.

Send a document with a specific brand

To ensure recipients see the intended branding, include both the BrandId and OnBehalfOf parameters in the document send request.

Example code snippet

curl -X POST 'https://api.boldsign.com/v1/document/send' \
 -H 'accept: application/json' \
 -H 'X-API-KEY: {your API key}' \
 -H 'Content-Type: multipart/form-data' \
 -F 'BrandId={brandId}' \
 -F 'OnBehalfOf={senderIdentityId}' \
 -F 'Message={message}' \
 -F 'Signers={
     "name":"Hanky",
     "emailAddress":"[email protected]",
     "signerType":"Signer",
     "formFields":[
       {
         "id":"string",
         "name":"string",
         "fieldType":"Signature",
         "pageNumber":1,
         "bounds":{
           "x":50,
           "y":50,
           "width":1,
           "height":1
         },
         "isRequired":true
       }
     ],
     "locale":"EN"
   }' \
 -F 'Files={your file}' \
 -F 'Title={document title}' 

For detailed instructions about sending documents on behalf of another sender, refer to this article Send On Behalf Document

What happens after the document is sent?

After the request is processed:

1. The document is sent using the specified sender identity.
2. Recipients receive email notifications that use the branding associated with the provided BrandId.
3. The signing page displays the selected brand’s logo, colors, and other branding elements.
4. The sender identity continues to use its configured brand only for sender identity approval and management workflows.

Example scenario

Consider the following configuration:

• Sender identity email: [email protected]
• Sender identity brand: Company A
• BrandId used in the API request: Company B

Result

• Sender identity approval, rejection, and revocation communications use Company A branding.
• Recipient emails and signing pages use Company B branding.

When using OnBehalfOf, the brand ID configured on the sender identity applies only to sender identity approval and management workflows. Recipient emails, signing pages, and other recipient-facing branding elements are determined by the BrandId specified in the document send request. If no BrandId is specified, BoldSign uses the account’s default brand.