How to customize signed document naming using BoldSign API?

In BoldSign, you can customize the naming format for signed documents to suit your needs. By default, a standard naming format is applied, but this can be tailored to include specific details by specifying them using the downloadFileName property. This feature ensures consistent naming conventions and helps keep your signed documents organized.

Customize signed document naming

When sending out a document for signature using BoldSign’s API, set the downloadFileName property to specify the file name format for signed documents and audit trails, which will apply to emails, downloads, and cloud storage. By default, the file name includes the document title and status.
For customized naming, you can use placeholders like {title}, {status}, or {date} to create a format that fits your needs.
Additionally, you can name a file using more than one file format. Here is a list of available file name formats:

• {title} : The title of the document.

• {documentId} : The unique identifier of the document.

• {status} : The status of the document.

• {signername} : The name of the first signer in the document.

• {signername_last} : The name of the last signer in the document.

• {sendername} : The sender of the document.

• {signername_order#1} : When multiple signers are added to a document, specify which signer’s name to use by indicating their placement in the signing order.

• {completeddate} : The document’s completion date.

Below are example code snippets with downloadFileName set to {title}_{signername} in the signature request via API:
cURL

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 'message=sign' \
  -F 'signers={
  "name": "Star",
  "emailAddress": "alexgayle@cubeflakes.com",
  "privateMessage": "sign",
  "authenticationType": "None",
  "deliveryMode": "Email",
  "signerType": "Signer",
  "allowFieldConfiguration": true,
  "formFields": [
    {
      "id": "sign",
      "name": "string",
      "fieldType": "Signature",
      "pageNumber": 1,
      "bounds": {
        "x": 130,
        "y": 130,
        "width": 81,
        "height": 31
      },
      "isRequired": true
    }
  ],
  "locale": "EN"
  
}' \
  -F 'downloadFileName={title}_{signername}' \
  -F 'Files=@{your file}' \
  -F 'title=Sales Agreement' 

C#

var apiClient = new ApiClient("https://api.boldsign.com", "{your API key}");

        var documentClient = new DocumentClient(apiClient);

 

        var documentFilePath = new DocumentFilePath

        {

            ContentType = "application/pdf",

            FilePath = "{Your file path}",  // Replace with actual file path

        };

 

        var filesToUpload = new List<IDocumentFile> { documentFilePath };

 

        var signatureField = new FormField(

            id: "sign",

            isRequired: true,

            type: FieldType.Signature,

            pageNumber: 1,

            bounds: new Rectangle(x: 130, y: 130, width: 81, height: 31));

 

        var formFieldCollections = new List<FormField> { signatureField };

 

        var signer = new DocumentSigner(

            signerName: "Star",

            signerType: SignerType.Signer,

            signerEmail: "alexgayle@cubeflakes.com",

            formFields: formFieldCollections,

            locale: Locales.EN);

 

        signer.DeliveryMode = DeliveryMode.Email;

 

        var documentSigners = new List<DocumentSigner> { signer };

 

        var sendForSign = new SendForSign

        {

            Message = "please sign this",

            Title = "Sales Agreement",

            Signers = documentSigners,

            DownloadFileName = "{title}_{signername}",

            Files = filesToUpload

        };

 

        var documentCreated = documentClient.SendDocument(sendForSign);

        Console.WriteLine(documentCreated);

Python

import boldsign

 

configuration = boldsign.Configuration(host="https://api.boldsign.com", api_key="YOUR_API_KEY")

 

with boldsign.ApiClient(configuration) as api_client:

 

    document_api = boldsign.DocumentApi(api_client)

             

    form_field = boldsign.FormField(

                             fieldType="Signature",

                             pageNumber=1,

                             bounds=boldsign.Rectangle(x=50, y=50, width=200, height=25))

 

    document_signer = boldsign.DocumentSigner(

        name="Star",

        emailAddress="alexgayle@cubeflakes.com",

        signerType="Signer",

        formFields=[form_field])

 

    send_for_sign = boldsign.SendForSign(

        title= "Sales Agreement",

        files=["YOUR_FILE_PATH"],

        downloadFileName= "{title}_{signername}",

        signers=[document_signer])

   

    document_created = document_api.send_document(send_for_sign)

PHP

<?php require_once "vendor/autoload.php";

 

use BoldSign\Configuration;

use BoldSign\Api\DocumentApi;

use BoldSign\Model\{FormField, Rectangle, DocumentSigner, SendForSign, FileInfo};

 

$config = new Configuration();

$config->setHost('https://api.boldsign.com');

$config->setApiKey('YOUR_API_KEY');

 

$document_api = new DocumentApi($config);

 

$form_field = new FormField();

$form_field->setFieldType('Signature');

$form_field->setPageNumber(1);

$bounds = new Rectangle([100, 100, 100, 50]);

$form_field->setBounds($bounds);

 

$document_signer = new DocumentSigner();

$document_signer->setName("Star");

$document_signer->setEmailAddress("alexgayle@cubeflakes.com");

$document_signer->setSignerType("Signer");

$document_signer->setFormFields([$form_field]);

 

$send_for_sign = new SendForSign();

$files = new FileInfo();

$files = 'YOUR_FILE_PATH';

$send_for_sign->setFiles([$files]);

$send_for_sign->setSigners([$document_signer]);

$send_for_sign->setDownloadFileName('{title}_{signername}');

$send_for_sign->setTitle('Sales Agreement');

 

$document_created = $document_api->sendDocument($send_for_sign);

Java

ApiClient client = Configuration.getDefaultApiClient(); 

client.setBasePath("https://api.boldsign.com");

client.setApiKey("YOUR_API_KEY");

      

DocumentApi documentApi = new DocumentApi(client);

 

FormField signatureField = new FormField();

signatureField.setFieldType(FormField.FieldTypeEnum.SIGNATURE);

signatureField.setPageNumber(1);

Rectangle bounds = new Rectangle().x(100f).y(100f).width(100f).height(50f);

signatureField.setBounds(bounds);

 

DocumentSigner signer = new DocumentSigner();

signer.setName("Star");

signer.setEmailAddress("alexgayle@cubeflakes.com");

signer.setSignerType(DocumentSigner.SignerTypeEnum.SIGNER);

signer.setFormFields(Arrays.asList(signatureField));

 

SendForSign sendForSign = new SendForSign();

File file = new File("YOUR_FILE_PATH"); 

sendForSign.setFiles(Arrays.asList(file));

sendForSign.setSigners(Arrays.asList(signer));

sendForSign.setDownloadFileName("{title}_{signername}");

sendForSign.setTitle("Sales Agreement");

 

DocumentCreated documentCreated = documentApi.sendDocument(sendForSign);

Node

import { DocumentApi, DocumentSigner, FormField, Rectangle, SendForSign } from "boldsign";

import * as fs from 'fs';

 

const documentApi = new DocumentApi();

documentApi.setApiKey("YOUR_API_KEY");

 

const bounds = new Rectangle();

bounds.x = 100;

bounds.y = 50;

bounds.width = 100;

bounds.height = 100;

const formField = new FormField();

formField.fieldType = FormField.FieldTypeEnum.Signature;

formField.pageNumber = 1;

formField.bounds = bounds;

 

// Signer

const documentSigner = new DocumentSigner();

documentSigner.name = "Star";

documentSigner.emailAddress = "alexgayle@cubeflakes.com";

documentSigner.signerType = DocumentSigner.SignerTypeEnum.Signer;

documentSigner.formFields = [formField];

 

// File

const files = fs.createReadStream("YOUR_FILE_PATH");

 

// Send for Sign

const sendForSign = new SendForSign();

sendForSign.title = "Sales Agreement";

sendForSign.signers = [documentSigner];

sendForSign.downloadFileName = "{title}_{signername}";

sendForSign.files = [files];

 

// Send Document

const documentCreated =documentApi.sendDocument(sendForSign)

In the code examples above, a document is prepared with signers and signature fields. A title and message are added, and the file path points to the document to be signed. By using a placeholder such as {title}_{signername}, the final signed file name will automatically include the document title and the signer’s name. For example, if the title is Sales Agreement and the signer’s name is Star, the completed file will be saved as: Sales Agreement_Star.pdf.

Rules for naming custom files

• You can use up to three syntax patterns. Use the predefined patterns or custom text. If custom text contains spaces, they will be replaced with underscores (_).

• Allowed characters: A-Z, a-z, 0-9, hyphens (-), and underscores (_).

• Max length: File names can be up to 200 characters long. Longer names will be truncated.

Use cases

1. Client Agreements
   Consider a sales executive who sends a client agreement for signature. To easily track who signed the document and when it was completed, the file name includes the document title, the first signer’s name, and the date of completion.
   Pattern: {title}{signername}{completeddate}
   Example Output: ClientAgreementJohnSmith12092025.pdf

Note: The completed date in the document name will automatically follow the date format defined in the sender’s business profile date field settings.

2. HR Offer Letters
   An HR manager sends out offer letters to new employees. To organize signed documents by candidate and status, the file name includes the document title, the signer’s name, and the status.
   Pattern: {title}{signername}{status}
   Example Output: OfferLetterEmilyBrownCompleted.pdf

3. Legal Contracts
   A law firm wants to archive contracts with unique identifiers. The file name includes the document ID and the completion date for compliance tracking.
   Pattern: {documentId}{completeddate}
   Example Output: 5y59295d-1234-5678-9abc-e7dc88cfff2c-12092025.pdf

Note: The completed date in the document name will automatically follow the date format defined in the sender’s business profile date field settings.

4. Vendor Agreements
   A procurement officer sends agreements to multiple vendors. To distinguish documents by sender and vendor, the file name includes the sender’s name and the last signer’s name.
   Pattern: {sendername}{signername_last}
   Example Output: David_AliceBob.pdf

5. Multi-Signer Projects
   For projects requiring multiple approvals, the project manager wants to track which signer in the order signed. The file name includes the title and the second signer’s name.
   Pattern: {title}{signername_order#2}
   Example Output: ProjectApprovalMariaLopez.pdf

6. Sales Proposals
   A sales team sends proposals to clients. To quickly identify completed proposals, the file name includes the title, status, and completion date.
   Pattern: {title}{status}{completeddate}
   Example Output: SalesProposalCompleted12092025.pdf

Note: The completed date in the document name will automatically follow the date format defined in the sender’s business profile date field settings.

7. Internal Policy Documents
   An HR department circulates updated policy documents. To track who signed acknowledgment, the file name includes the title and the signer’s name.
   Pattern: {title}{signername}
   Example Output: WorkplacePolicyAlexJohnson.pdf

8. Audit Trail Files
   Compliance teams need audit trails tied to document IDs and sender names.
   Pattern: {documentId}{sendername}
   Example Output: 9r78295d-1289-5678-9abc-e7dc88cfff2c_SarahWilliams.pdf