Explore BoldSign eSignature APIs in Postman: A Step-by-Step Guide

In today’s digital age, electronic signatures (eSignatures) have become indispensable for businesses of all sizes. They streamline document workflows, reduce costs, and enhance security. BoldSign is a leading eSignature solution that offers a robust set of APIs (Application Programming Interfaces) for integrating eSignature functionality into your applications. This comprehensive guide will walk you through the process of exploring BoldSign’s eSignature APIs using Postman, a popular API client.

Table of Contents

1. Introduction to BoldSign APIs and Postman
2. Prerequisites
3. Setting Up Your BoldSign Account and API Key
4. Setting Up Postman
5. Importing the BoldSign Postman Collection
6. Authentication with BoldSign APIs
7. Exploring Key BoldSign API Endpoints
   1. Creating a Document
   2. Sending a Document for Signature
   3. Getting Document Status
   4. Downloading a Signed Document
   5. Canceling a Document
   6. Generating Signer View Link
8. Exploring Advanced Features with APIs
   1. Using Templates
   2. Customizing Branding
   3. Implementing Webhooks
9. Best Practices for Using BoldSign APIs
10. Troubleshooting Common Issues
11. Conclusion
12. Resources

Introduction to BoldSign APIs and Postman

BoldSign APIs provide a programmatic way to interact with the BoldSign eSignature platform. This allows you to integrate eSignature capabilities directly into your applications, websites, and workflows. Using the APIs, you can automate document sending, signature collection, and document management.

Postman is a popular API client used by developers to test, document, and share APIs. It provides a user-friendly interface for sending HTTP requests, inspecting responses, and managing API collections. Postman simplifies the process of interacting with RESTful APIs like those offered by BoldSign.

Prerequisites

Before you begin, ensure you have the following:

1. A BoldSign Account: If you don’t have one already, sign up for a free BoldSign account at BoldSign Website.
2. Postman Installed: Download and install Postman from Postman Downloads.
3. Basic Understanding of REST APIs: Familiarity with RESTful API concepts like HTTP methods (GET, POST, PUT, DELETE), request headers, and JSON payloads is helpful.

Setting Up Your BoldSign Account and API Key

To use the BoldSign APIs, you need an API key. Follow these steps to obtain your API key:

1. Log in to your BoldSign Account: Go to the BoldSign website and log in using your credentials.
2. Navigate to the API Settings: Look for a section labeled “API” or “Integrations” in your account settings. This is usually under “Settings,” “Profile,” or “Account.”
3. Generate an API Key: If you don’t have an API key, click the button to generate one. If you already have a key, you may need to generate a new one. Treat your API key like a password and keep it secure. Never share your API key publicly.
4. Copy Your API Key: Copy the generated API key to a safe place. You will need it later to authenticate your requests in Postman.

Setting Up Postman

Once you have Postman installed, you need to configure it to work with the BoldSign APIs. Here’s how:

1. Launch Postman: Open the Postman application on your computer.
2. Create a New Workspace (Optional): Consider creating a new workspace specifically for BoldSign API exploration to keep things organized.
3. Import the BoldSign Collection (See next section): This is the most efficient way to get started.

Importing the BoldSign Postman Collection

BoldSign provides a Postman collection that includes pre-configured requests for various API endpoints. This collection simplifies the process of exploring the APIs.

Unfortunately, I cannot directly provide you with the BoldSign Postman collection. You typically need to download it from the BoldSign documentation or a dedicated resource provided by BoldSign. Here’s how you would generally import a Postman collection:

1. Find the BoldSign Postman Collection: Check the BoldSign API documentation (BoldSign API Documentation – replace with the actual documentation URL) for a link to download the Postman collection (usually a JSON file). The documentation might also provide a “Run in Postman” button.
2. Import the Collection in Postman:
   • Click the “Import” button in the top-left corner of the Postman window.
   • Choose the option to “Import from File.”
   • Select the JSON file you downloaded.
   • Alternatively, if the documentation offers a “Run in Postman” button, clicking it will automatically import the collection into your Postman application.

Authentication with BoldSign APIs

All requests to the BoldSign APIs require authentication using your API key. You typically include the API key in the request headers.

1. Locate the API Key Variable (if available): The BoldSign Postman collection often defines a variable to store your API key. Look for a variable named something like `apiKey` or `X-API-KEY`. This variable might be defined at the collection level or as an environment variable.
2. Set the API Key Value:
   • If using a collection variable: Edit the collection and find the `apiKey` variable. Enter your API key as the *initial value* and the *current value*. The current value is what Postman will actually use in the requests.
   • If using an environment variable: Create a new Postman environment (or select an existing one). Add a variable named `apiKey` (or whatever the collection uses) and set its value to your actual API key. Select this environment in Postman before making requests.
3. Verify Authentication: Most of the pre-configured requests in the BoldSign collection will include the `X-API-KEY` header automatically. Make sure this header is present in the “Headers” tab of your Postman requests and that it’s referencing the `apiKey` variable (e.g., `{{apiKey}}`).
4. If no pre-configured variable: You may need to manually add the `X-API-KEY` header to each request and paste your API key directly into the value field. This is less ideal, so try to use the variable approach if possible.

The X-API-KEY header is the most common authentication method. BoldSign might support other methods (like OAuth 2.0) depending on the specific API endpoint. Check the BoldSign API documentation for details.

Exploring Key BoldSign API Endpoints

Now that you have Postman set up and authenticated, you can start exploring the BoldSign API endpoints. This section will guide you through some of the most common and important endpoints.

1. Creating a Document

The “Create Document” endpoint allows you to upload a document to BoldSign and prepare it for sending.

1. Select the “Create Document” Request: In the Postman collection, find and select the request typically named “Create Document” or similar.
2. Configure the Request Body: This endpoint usually requires a `multipart/form-data` request. The body will typically include:
   • `file` (Required): The actual document file you want to upload. Select the “File” type in Postman and choose the document from your computer. Supported formats might include PDF, DOC, DOCX, etc.
   • `title` (Optional): A title for the document.
   • `message` (Optional): A message to be included in the email sent to signers.
   • `signer_details` (Optional but crucial): An array of signer objects. Each object specifies the signer’s email address, name, and signing order (if applicable). The format might look like this:

     
                 [
                   {
                     "email": "signer1@example.com",
                     "name": "Signer One",
                     "order": 1
                   },
                   {
                     "email": "signer2@example.com",
                     "name": "Signer Two",
                     "order": 2
                   }
                 ]
               

3. Set Request Headers (if needed): The `Content-Type` header should be set to `multipart/form-data`. Postman usually handles this automatically when you select “File” in the request body. Double check to be sure!
4. Send the Request: Click the “Send” button in Postman.
5. Inspect the Response:
   • Success: A successful response (usually a 200 OK or 201 Created status code) will return a JSON object containing details about the created document, including the `documentId`. This ID is *critical* for subsequent API calls.
   • Error: An error response (e.g., 400 Bad Request, 401 Unauthorized, 500 Internal Server Error) will provide information about what went wrong. Check your API key, request body, and headers.

Important: Make sure the file you are uploading is not corrupted and is in a supported format. Carefully check the `signer_details` to ensure the email addresses and names are correct.

2. Sending a Document for Signature

Once you’ve created a document, you need to send it to the signers for signature. This endpoint typically requires the `documentId` obtained in the previous step.

1. Select the “Send Document” Request: Find and select the “Send Document” request in the Postman collection.
2. Set the `documentId` as a Path Parameter or in the Request Body: The `documentId` is usually passed as a path parameter (e.g., `/documents/{documentId}/send`) or as part of the request body. Check the BoldSign API documentation to determine the correct method. If it’s a path parameter, add the `documentId` to the URL in Postman (replacing `{documentId}` with the actual ID). If it’s in the request body, the request will likely be `application/json`.
3. Configure the Request Body (if applicable): Some implementations require an empty JSON object `{}`, while others don’t require a body at all. Check documentation.
4. Send the Request: Click the “Send” button.
5. Inspect the Response:
   • Success: A successful response (usually 200 OK or 204 No Content) indicates that the document has been sent to the signers.
   • Error: Common errors include an invalid `documentId`, incorrect API key, or issues with the signers’ email addresses.

3. Getting Document Status

This endpoint allows you to check the current status of a document (e.g., “Draft,” “Sent,” “Signed,” “Completed,” “Cancelled”).

1. Select the “Get Document Status” Request: Locate and select this request in Postman.
2. Set the `documentId` as a Path Parameter: The `documentId` is almost always passed as a path parameter in the URL (e.g., `/documents/{documentId}/status`). Replace `{documentId}` with the actual ID.
3. Send the Request: Click the “Send” button.
4. Inspect the Response:
   • Success: A successful response will return a JSON object containing the document’s status and other relevant information, such as the signing progress of each signer.
   • Error: An invalid `documentId` is the most common cause of errors.

4. Downloading a Signed Document

Once a document has been fully signed, you can download it using this endpoint.

1. Select the “Download Document” Request: Find this request in Postman.
2. Set the `documentId` as a Path Parameter: The `documentId` is passed as a path parameter in the URL (e.g., `/documents/{documentId}/download`).
3. Send the Request: Click the “Send” button.
4. Inspect the Response:
   • Success: A successful response will typically return the document data as a binary file (e.g., a PDF). Postman should prompt you to save the file to your computer.
   • Error: Ensure the document has been fully signed and that the `documentId` is correct.

5. Canceling a Document

This endpoint allows you to cancel a document that is in progress (before it has been fully signed).

1. Select the “Cancel Document” Request: Find this request in Postman.
2. Set the `documentId` as a Path Parameter: The `documentId` is passed as a path parameter in the URL (e.g., `/documents/{documentId}/cancel`).
3. Configure the Request Body (if required): Some APIs might require a reason for cancellation to be included in the request body (e.g., in JSON format). Consult the documentation.
4. Send the Request: Click the “Send” button.
5. Inspect the Response:
   • Success: A successful response (usually 200 OK or 204 No Content) indicates that the document has been successfully canceled.
   • Error: You might receive an error if the document has already been fully signed or if the `documentId` is invalid.

6. Generating Signer View Link

This is useful for providing a direct link to the signing page to each signer, bypassing the email notification.

1. Select the “Get Signer View Link” Request: Find this request in Postman.
2. Set the `documentId` as a Path Parameter: The `documentId` is usually a path parameter.
3. Configure the Request Body: The request body typically requires the signer’s email address.

   
           {
               "email": "signer1@example.com"
           }
       

4. Send the Request: Click the “Send” button.
5. Inspect the Response:
   • Success: The response will contain a URL that the signer can use to access and sign the document directly.
   • Error: A common error is providing an incorrect email address or an invalid `documentId`.

Exploring Advanced Features with APIs

Beyond the basic document creation and signing workflow, BoldSign APIs offer a range of advanced features.

1. Using Templates

Templates allow you to predefine the structure and layout of documents, including form fields and signing locations. Using templates can significantly speed up the document creation process.

1. Create a Template in BoldSign: First, create a template using the BoldSign web interface. Define the roles for each signer and add fields where they need to sign or enter information.
2. Identify the Template ID: Note the unique ID assigned to your template. You’ll need this to use the template in your API requests.
3. Use the “Create Document from Template” Endpoint: The BoldSign API will have a dedicated endpoint for creating documents from templates. The request body will likely include:
   • `templateId` (Required): The ID of the template you want to use.
   • `signer_details` (Required): An array of signer objects, similar to the “Create Document” endpoint.
   • `field_values` (Optional): A JSON object containing values to pre-populate the fields in the template. This allows you to automate the process of filling in information in the document.
4. Send the Request and Handle the Response: The response will be similar to the “Create Document” endpoint, providing the `documentId` of the newly created document.

2. Customizing Branding

BoldSign allows you to customize the appearance of the signing experience to match your brand. This includes adding your logo, changing the colors, and customizing the email messages sent to signers.

1. Configure Branding in BoldSign: Use the BoldSign web interface to configure your desired branding settings.
2. Check API Documentation: Determine which API endpoints allow you to override the default branding settings. This might involve passing parameters in the request body, such as:
   • `brand_id` (Optional): The ID of your custom branding configuration.
   • `logo_url` (Optional): A URL to your logo image.
   • `primary_color` (Optional): The primary color to use in the signing experience.
3. Send the Request: Include the branding parameters in your API requests when creating documents or sending them for signature.

3. Implementing Webhooks

Webhooks allow you to receive real-time notifications when certain events occur in BoldSign, such as when a document is signed, completed, or canceled. This enables you to automate tasks and integrate BoldSign with other applications.

1. Configure a Webhook Endpoint: Create a publicly accessible URL on your server that will receive the webhook notifications. This endpoint needs to be able to handle POST requests.
2. Register the Webhook in BoldSign: Use the BoldSign API (or the web interface) to register your webhook endpoint. You’ll need to specify:
   • `url` (Required): The URL of your webhook endpoint.
   • `events` (Required): The events you want to receive notifications for (e.g., `document.signed`, `document.completed`, `document.canceled`).
3. Handle Webhook Notifications: When an event occurs, BoldSign will send a POST request to your webhook endpoint. The request body will contain a JSON object with details about the event. Your endpoint should:
   • Verify the Request: Implement security measures to verify that the request is actually coming from BoldSign. This might involve checking a shared secret or verifying the signature of the request.
   • Process the Event: Parse the JSON data and perform the necessary actions based on the event.
   • Return a 200 OK Status: Your endpoint should return a 200 OK status code to acknowledge that the notification was received successfully.
4. Testing Webhooks: BoldSign usually provides a way to trigger test webhooks. You should use this feature to verify that your webhook endpoint is working correctly.

Best Practices for Using BoldSign APIs

Following these best practices will help you ensure a smooth and efficient integration with BoldSign APIs:

1. Read the Documentation: Always refer to the official BoldSign API documentation for the most up-to-date information on endpoints, parameters, and authentication methods.
2. Handle Errors Gracefully: Implement proper error handling in your application to gracefully handle API errors and provide informative messages to the user.
3. Use Secure Storage for Your API Key: Never hardcode your API key directly into your code. Store it securely using environment variables or a configuration management system.
4. Rate Limiting: Be aware of BoldSign’s API rate limits and implement appropriate throttling mechanisms in your application to avoid exceeding those limits.
5. Test Thoroughly: Thoroughly test your integration with the BoldSign APIs to ensure that it is working correctly and handling all possible scenarios.
6. Use a Dedicated API Client: Using a tool like Postman is crucial for testing, debugging, and understanding the API calls and responses.
7. Implement Logging: Log API requests and responses to help you troubleshoot issues and monitor the performance of your integration.
8. Use Asynchronous Processing: For long-running operations (e.g., creating or sending large documents), consider using asynchronous processing to avoid blocking the main thread of your application. This often involves using queues or background workers.

Troubleshooting Common Issues

Here are some common issues you might encounter when working with the BoldSign APIs and how to troubleshoot them:

1. Authentication Errors (401 Unauthorized):
   • Problem: Invalid or missing API key.
   • Solution: Double-check that you have entered your API key correctly in Postman. Ensure that the `X-API-KEY` header is present in your requests and that the value matches your API key.
2. Bad Request Errors (400 Bad Request):
   • Problem: Invalid request parameters or missing required parameters.
   • Solution: Carefully review the API documentation for the endpoint you are using and ensure that you are providing all the required parameters in the correct format. Check for typos in the parameter names and values. Use Postman’s “Pre-request Script” feature to validate parameters before sending the request.
3. Resource Not Found Errors (404 Not Found):
   • Problem: The requested resource (e.g., document, template) does not exist.
   • Solution: Verify that the `documentId` or `templateId` you are using is correct and that the resource exists in your BoldSign account.
4. Rate Limit Exceeded Errors (429 Too Many Requests):
   • Problem: You have exceeded the API rate limit.
   • Solution: Implement throttling in your application to limit the number of requests you are sending to the BoldSign APIs. Check the BoldSign API documentation for the current rate limits and retry-after header.
5. File Upload Errors:
   • Problem: Issues uploading document files.
   • Solution: Ensure the file is in a supported format (e.g., PDF, DOCX) and that the file size is within the limits specified in the BoldSign API documentation. Verify that the `Content-Type` header is set to `multipart/form-data` and that you are using the correct file upload method in Postman.
6. Webhook Issues:
   • Problem: Webhooks are not being delivered or are not being processed correctly.
   • Solution: Check that your webhook endpoint is publicly accessible and that it is returning a 200 OK status code. Examine your server logs for errors related to the webhook notifications. Use a tool like RequestBin to inspect the webhook requests being sent by BoldSign. Ensure your webhook URL is correct and the events selected are appropriate.
7. Postman Configuration Issues:
   • Problem: Postman is not sending the requests correctly.
   • Solution: Double-check that you have configured Postman correctly, including setting the API key, headers, and request body. Try clearing Postman’s cache and cookies. Ensure Postman is updated to the latest version.

Conclusion

This guide provided a step-by-step introduction to exploring BoldSign eSignature APIs using Postman. By following these steps, you can quickly get started integrating BoldSign’s powerful eSignature capabilities into your applications and workflows. Remember to consult the official BoldSign API documentation for the most comprehensive and up-to-date information.

Resources

1. BoldSign API Documentation: BoldSign API Documentation (Replace with the actual URL). This is the most important resource.
2. Postman Documentation: Postman Learning Center
3. BoldSign Support: Contact BoldSign support for assistance with any issues you encounter.