Bulksign API

With the Bulksign API you get the flexibility and control to scale from simple eSignature integrations to complex enterprise applications. Using the Bulksign APIs you can:

  • Request legally binding signatures on virtually any type of document
  • Embed the signing or sending workflow into your UI
  • Track documents in real-time
  • Retrieve form-field data
  • Enforce recipient authentication
  • Much more...

General information

  • the BulkSign API is exposed in 2 "flavors" : SOAP and REST. There is no difference in functionality between them. Use whichever is best suited to your environment.

  • there are no feature specific limitations to the API. Everything is exposed in the API from free accounts all the way to the premium ones.

Browse annotated API specifications

Api authentication

The API requires authentication for all its methods. The authentication data is :

  • Api token : get this from your tokens page

  • Email address : the email address used to register your Bulksign account.

For SOAP api, the authentication data is passed as first parameter for each method (the authentication type is called BulksignAuthentication). For REST api, the authentication data is passed as the value of a custom HTTP header called X-Bulksign-Authorization. Here's a example of doing a request with curl :

curl --header "X-Bulksign-Authentication:{{ApiToken}};{{Email}}" https://bulksign.com/restapi/v1/GetTemplatesCount -k -X POST -d " " 

Replace {{ApiToken}} and {{Email}} with your valid data.

Results

The api will always return the result wrapped by a object called BulksignResult. This object has the following properties :

  • IsSuccessful : this boolean signals if the call is successful or not. If the value is false look at the ErrorMessage property to see what went wrong.
  • ErrorMessage : In case "IsSuccessful" is false, this contains a descriptive error message.
  • ErrorCode : A specific numeric error code used to identify the error. If the call succeeds, this has value 0. The list of all possible error codes returned by Bulksign is available on GitHub
  • Response : this contains the api call result.

SOAP

The SOAP API endpoint is located at https://bulksign.com/bulksignapi.asmx

REST

The REST root endpoint is located at https://bulksign.com/restapi/v1/

  • all REST API calls should use HTTP POST.

  • by default the REST API returns JSON. If you prefer XML, you need to set the appropriate Accept-Header value or use the SOAP service.

  • complex API parameters are passed in the request body as JSON data. Simple parameters can also be passed in the url (here's a example)

POST https://bulksign.com/restapi/v1/DeleteDraft/?draftPublicId={{CorrectValueHere}} 

List of API methods

Browse annotated API specifications

Callbacks

Callbacks for bundle status

Bulksign supports callbacks (using HTTP for SAAS version and/or custom for private versions) to notify the bundle sender when the status is changing and when a recipient is performing a specific action. The following bundle statuses are supported :

Completed

Canceled

Expired

To enable callback for bundle status, when sending the bundle set a url for "StatusChangedNotificationUrl". The following url parameters are usable :

  • {{#id#}} : this will be replaced with the id of the bundle for which the callback is called.
  • {{#status#}} : this will be replaced with the bundle status value.
Info

Please note the the names of placeholder parameters are case sensitive

Here's a url example for reciving a callback when the bundle status changes :

http://localhost/mysite?id={{#id#}}&status={{#status#}}

Callbacks for recipient actions

Callbacks are also supported for the following recipient actions :

Opened : sent when a signer opened the document for the first time (this is only sent once)

Signed : recipient has signed and finished the document.

Rejected : recipient has rejected to sign the document.

NextSigner : only in a serial bundle, it's triggered when a new recipient has to sign.

To enable push notifications for signer events, when sending one just set a url for "RecipientActionNotificationUrl". The following url parameters are usable :

  • {{#email#}} : recipient email
  • {{#action#}} : recipient action value
  • {{#id#}} : bundle id
Info

Please note the the names of placeholder parameters are case sensitive.

Here's a url example for reciving notifications about the signer actions : http://localhost/mysite?email={{#email#}}&recipientStatus={{#action#}}&id={{#id#}}

Sent Callbacks

It's possible to see the list of sent callbacks in the Bulksign UI. Navigate to the bundle details page, click the "info" button (top right side of the page) and click the "Callbacks" button. You will be redirected to a page which shows all callbacks sent so far for that specific bundle.

Danger!

Please note that the callbacks are only triggered once

We recommend to use callbacks + GetBundleStatus (calling it once per day should be enough) to get the state of a bundle

Error handling

The Bulksign api will return error codes and error messages when a operation fails for some reason. The entire list of error codes is available on github . This class is already part of our .NET SDK

When using the .NET SDK exceptions can be handled by catching "BulksignException". This exception includes a "Response" property which stores the server response and can be used for troubleshooting

Integrate signing directly into your application/website

It's very easy to integrate signing directly into your website/application, here is some sample code for multiple scenarios :

Integration sample for web application

Integration sample for Universal Windows Platforms apps

Integration sample for Android (using Xamarin)

SDKs

.NET

Out .NET SDK can be installed directly from Nuget.org. From the Nuget console, just run :

install-package BulksignSdk
Javascript / Typescript

Our JS/TS SDK is available in this Github repository

Java, Ruby and Python

You can also download bindings for Java , Ruby and Python

FAQ

Is there any sample code that describes different integration scenarios ?

We have lots of sample code on Github

How automatic field mapping works when creating drafts/templates and sending bundles?

Automatic field assignment works depending on the number of recipients per bundle:

  • for 1 recipient, unless FieldMapping is specified, all existing form fields will be by default assigned to that recipient.

  • for bulk bundles , unless FieldMapping is specified, all existing fields will be assigned by default to all recipients.

How do i use the FieldMapping to assign fields already existing in the document to different recipients :

First, for each document that will be part of the bundle to be sent, you will need to call AnalyzeFile. That API method will return a list with all form fields (id and types). With the result of AnalyzeFile, you can build a FieldMapping structure that allows assignment of form fields to specific recipients. The content of FieldMapping is :

FieldId : the id of the form field obtained with AnalyzeFile. 
MappingIdentifier : the mapping identifier can have one of these 3 values : 
- the '*' character to assign that particular field to all recipients (usable for bulk bundles).
- the email address of the recipient to whom the field will be assigned. 
- the name of the recipient (this should be used only in the scenario of disabling email notifications for multiple recipients) 
How can i create a new signature field from the API ?

You can accomplish this using "NewSignature" :

Width : the width of the signature field (in pixels). 
Height : the height of the signature field (in pixels). 
Top : the position (in pixels) from the top side of the page. 
Left : the position (in pixels) from the left side of the page. 
PageIndex : the index of page to which this new signature will be added. 
MappingIdentifier : use the recipient email address to assign this to a specific recipient or character '*' to assign field to all recipients (in bulk scenarios). In case the email address 
is noreply@bulksign.com, use the recipient's name.
How can i found out if a bundle has rejected signing steps ?

This can be done by checking the "Status" of each of the signer recipients. Additionally, if the status is "Rejected" (3) , "RejectionMessage" will contain the message from ther signer.

How can i know if singing has been delegated to a certain recipient ?

The flag is called "HasBeenDelegated" , if that is set to true , it means the current recipient has been delegated to sign.