BoldSignDocumentation
BoldSign Mobile Icon

BoldSign API and Webhooks

Mon, 15 Mar, 2021

BoldSign API

This guide will help you get started with using our API to initiate and track signature requests.

Authentication

The first step is to authenticate by acquiring your credentials from our app and then establishing a connection using those credentials.

Acquiring Credentials

  • Go to API menu item on the app’s left navigation pane and then click on “Developer Apps”.
  • Click the “Create App” button in the top right corner.

Create app button

  • You will be prompted with the Create Application dialog. It is possible to configure separate credentials for test and live production environments.

Create application

  • Specify the Application Name and Client Secret Validity details.
  • In the redirect URL section, add the needed URLs. For ex, local development URL’s could be http://localhost:3000, live application URL’s will be something like https://yourapp.com/.
  • Click Save.
  • You will now be redirected to the App details page of your new API application.

App details page

  • You need to copy the Client ID and Client Secret Key and store it for future reference. These keys are required to configure the OAuth Client in your app.

Note: Client Secret key cannot be viewed again after you have navigated away from this page. A new key has to be created in case you lose this client secret key.

Configuring the Application

BoldSign’s API authentication is done using OAuth2 Client Credential flow. You can use any OAuth2 Client or connector to connect to our token server and get the access token. For this example, I’m using simple HttpClient to fetch the access token. Please find the code sample below.

using var http = new HttpClient();

var parameters = new List<KeyValuePair<string, string>>
{
    new KeyValuePair<string, string>("grant_type", "client_credentials"),
    new KeyValuePair<string, string>("scope", "BoldSign.Documents.All BoldSign.Templates.All")
};

using var encodedContent = new FormUrlEncodedContent(parameters);
using var request = new HttpRequestMessage()
{
    Content = encodedContent,
    Method = HttpMethod.Post,
    RequestUri = new Uri("https://account.boldsign.com/connect/token"),
};

const string clientId = "***client-id***";
const string clientSecret = "***client-secret***";

request.Headers.Authorization = new BasicAuthenticationHeaderValue(clientId, clientSecret);
using var response = await http.SendAsync(request).ConfigureAwait(false);
var content = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
var tokenResponse = JsonConvert.DeserializeObject<Dictionary<string, string>>(content);
tokenResponse.TryGetValue("access_token", out var accessToken);

var configuration = new Configuration
{
    BasePath = "https://api.boldsign.com",
};

// set your OAuth2 Access Token for authentication.
configuration.SetBearerToken(accessToken);

var apiClient = new ApiClient(configuration);

BoldSign API SDK

  • After you have fetched the OAuth2 Access token from Developer Apps, you will be able to use this token to authenticate and use BoldSign API.
  • You can consume BoldSign API either using REST API or C# SDK. BoldSign’s SDK is the simpler way to consume the API from .NET.
  • Download the SDK Nuget package with the name “BoldSign”.
  • After installing the package in your project, create an ApiClient and Configuration for “BoldSign” to use its API. You will be able to reuse this ApiClient in both DocumentClient and TemplateClient.

var configuration = new Configuration();

// set your OAuth2 Access Token for authentication.
configuration.SetBearerToken("your-oauth2-token");

var apiClient = new ApiClient(configuration);
  • This access token configuration will be applied to all the API calls, so you can start creating signature requests using the Document API class.
  • Create new instance of the DocumentClient as shown below.

var documentClient = new DocumentClient(apiClient);
  • Now we can add fields like signature and text boxes for the recipients. These fields can be created as shown below using the “SendForSign” Class.

 var formFields = new List<FormField>();

formFields.Add(new FormField(
            name: "Sign",
            type: FieldType.Signature,
            pageNumber: 1,
            isRequired: true,
            bounds: new Rectangle(x: 50, y: 50, width: 200, height: 30)));
        
var documentDetails = new SendForSign
{
    Title = "Sent from API SDK",
    Message = "This is document message sent from API SDK",
    Signers = new List<DocumentSigner>
    {
        new DocumentSigner(
            name: "Signer Name 1",
            emailAddress: "signer1@email.com",
            signerOrder: 1,
            authenticationCode: "123",
            signerType: SignerType.Signer,
            privateMessage: "This is private message for signer",
            formFields:formFields),
    },
};

// document read from local as byte array
var fileBytes = File.ReadAllBytes("doc-1.pdf");

// document read from local as stream
using var fs = File.OpenRead("doc-2.pdf");

documentDetails.Files = new List<IDocumentFile>
{
    new DocumentFilePath
    {
        ContentType = "application/pdf",
        // directly provide file path
        FilePath = "doc-1.pdf",
    },
    new DocumentFileBytes
    {
        ContentType = "application/pdf",
        FileData = fileBytes,
        FileName = "doc-1.pdf",
    },
    new DocumentFileStream
    {
        ContentType = "application/pdf",
        FileData = fs,
        FileName = "doc-2.pdf",
    },
};
  • We also need to upload a document file on which the form fields will be overlayed. This is the document that will be sent for signature.
  • Finally, we can now send the document for signature as shown below.

documentClient.SendDocument(documentDetails);
  • You can get the embedded sign link for the created document by specifying its document id and signer emails as a parameter. This embedded sign link can be used to embed the document for signature right within your application.

You can also provide a redirect URL where the signer will be redirected to after having successfully signed the document. Please refer the below code.

// This is an example document id, add your own document id upon usage.
var documentId = "949ebf20-45a8-4a3e-91a9-68e9540e0020";

var embeddedSigningLink = documentClient.GetEmbeddedSignLink(
    documentId: documentId,
    signerEmail: "signer1@email.com",
    signLinkValidTill: DateTime.UtcNow.AddDays(1),
    redirectUrl: "https://myapp.com/sign/redirect");
  • There are also other APIs in SDK that will let you perform actions such as List documents, Revoke, Delete and Remind.

Templates

A simpler way to initiate signature requests through API would be to send signature requests based off pre-configured templates in BoldSign.

  • Create your templates within the BoldSign app and then click on the “Copy template ID” menu item in the template listing item context menu.

Copy template id

This template ID is then used to identify the specific template in code.

// This is an example document id, add your own document id upon usage.
var templateId = "949ebf20-45a8-4a3e-91a9-68e9540e0020";

var templateDetails = new SendForSignFromTemplate(
    templateId: templateId,
    title: "Document from Template",
    message: "This document description");

templateApi.SendUsingTemplate(templateDetails);
  • We can also customize the signer name, roles, emails and fields present in the template as shown below.

Customize fields in templates

BoldSign Webhooks

You can use Webhooks to respond to BoldSign’s document workflow events from within your own applications.

Events

There are 11 types of events that can be listened through webhooks.

Sent

Triggered when the document has been successfully created and sent out for signature.

Signed

Triggered when one of the signers has completed signing their document.

Completed

Triggered when all the recipients of the document have completed.

Declined

Triggered when one of the signers has declined the document.

Revoked

Triggered when the document has been revoked.

Reassigned

Triggered when one of the signers has reassigned the document to another signer.

Expired

Triggered when the document has expired.

Viewed

Triggered when the document has been viewed by one of the participants.

AuthenticationFailed

Triggered when one of the signers has failed authentication.

DeliveryFailed

Triggered when email delivery has failed for one of the recipients in the document.

Sample Event data

{
    "event": {
        "id": "e4ca1621-bbc7-4c9a-9e81-81d107589690",
        "created": 1614933645,
        "eventType": "Sent",
        "clientId": "e4ca1621-bbc7-4c9a-9e81-81d107589690",
        "environment": "Test"
    },
    "document": {
        "documentId": "b7a35af1-8524-4f8e-b370-1c470eee2b38",
        "messageTitle": "API Test Document",
        "documentDescription": "This is document message sent from API SDK",
        "status": "InProgress",
        "senderDetail": {
            "name": "Sender",
            "emailAddress": "sender@email.com"
        },
        "signerDetails": [
            {
                "signerName": "Signer",
                "signerRole": "",
                "signerEmail": "sender@email.com",
                "status": "NotCompleted",
                "enableAccessCode": true,
                "isAuthenticationFailed": false,
                "enableEmailOTP": false,
                "isDeliveryFailed": false,
                "isViewed": false,
                "order": 1,
                "signerType": "None",
                "isReassigned": false,
                "reassignMessage": null,
                "declineMessage": null
            }
        ],
        "ccDetails": [],
        "createdDate": 1614862699,
        "expiryDate": 1616158699,
        "enableSigningOrder": true,
        "enableEmbeddedSigning": true,
        "revokeMessage": null
    }
}

Event Metadata

The Event metadata contains information about webhooks event such as event ID, type, created date and time, client ID, and environment.

{
    "event": {
        "id": "e4ca1621-bbc7-4c9a-9e81-81d107589690",
        "created": 1614933645,
        "eventType": "Sent",
        "clientId": "e4ca1621-bbc7-4c9a-9e81-81d107589690",
        "environment": "Test"
    }
}
Property Description
id This is a unique id for the event
created Unix timestamp of the event
eventType Represents the type of event. There are 11 types of events that can be listened through the webhooks
clientId The client id of the developer app that the webhook is currently linked to
environment The environment of the webhooks (either Test or Live)
Copied to clipboard