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 work-flow 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 for you.

API Authentication

The API requires authentication for all its methods (the only exception is GetVersion which is public). The Bulksign platform supports 3 types of authentication keys :

  • personal key : used to authenticate a single user.

  • organization key : along with an email address can be used to authenticate any organization user.

  • global key : strictly only for on-premise version and allows authentication only to a subset of APIs (please see here the list). This is intended only for global integrations and allows access to any envelope.

The authentication data is comprised of :

  • API Key

  • Email address : Only required when using a organization key, this is the email address used to register the Bulksign account.

For SOAP API, the authentication data is passed as first parameter for each method (the authentication type is called AuthenticationApiModel).

For REST API, the authentication data is passed as the value of a custom HTTP header called X-Bulksign-Authentication. Here's a example of doing a request with curl (using a organization key):

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

Replace {{Email}} and {{ApiKey}} with your valid data. For authentication with a personal key, just leave out the email part.


From where these API keys can be obtained ?

  • Personal Keys : can be obtained from the "My API Keys" section of the Bulksign account.

  • Organization Key : can be created and obtained from the Bulksign Organization page (requires administrator rights to access).

  • Global Key : ask your Bulksign instance administrator.



API Response

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 request 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 in the error codes section
  • Response : this contains the result of API request.
  • RequestId : a unique request id, is generated only for failed request. Please provide this value to us when troubleshooting failed requests.

Endpoints

The SOAP API endpoint is located at https://bulksign.com/webapi/bulksignapi.asmx
The REST root endpoint is located at https://bulksign.com/webapi/restapi/

  • 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.

Annotated specifications for REST API

    Browse API Specifications

For invoking our REST API, please also see our Postman collection project on GitHub


Callbacks


Envelope Status callbacks

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

Completed

Canceled

Expired

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

  • {{#id#}} : this will be replaced with the id of the envelope for which the callback is called.
  • {{#status#}} : this will be replaced with the envelope status value.
  • {{#senderEmail#}} : this will be replaced with the envelope sender's email.
Info

Please note the the names of placeholder parameters are case sensitive

Here's a url example for receiving a callback when the envelope status changes :

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


Recipient Action callbacks

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)

Finished : recipient has signed all assigned signature fields and finished the document.

Rejected : recipient has rejected to sign the document.

NextSigner : only sent for serial envelope, it's triggered when a new recipient has to sign.

Delegated : sent when recipient has delegated signing.

Authenticated : sent when recipient has successfully authenticated and accessed the signing document.

EmailError : sent when the signing email sent to a signer/approver recipient bounced and cannot be delivered successfully.

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#}} : envelope id
  • {{#senderEmail#}} : envelope sender email
Info

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

Here's a url example for receiving 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 envelope 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 envelope.

Danger!

Please note that the callbacks are only triggered once

We recommend to use callbacks + GetEnvelopeStatus to get the status of a envelope. Also please see our full integration GitHub sample which handles callbacks, pooling and stores locally the envelope identifiers



Error Handling

The Bulksign API will return error codes and error messages when a operation fails for some reason. The list of error codes is available here
If you are integrating using our .NET SDK , the type "ApiErrorCode" is already part of the 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

Our .NET SDK is available directly from Nuget . To use it, from the Nuget console, just run :

install-package BulksignSdk

If you cannot use the SOAP API, for other language we provide language specific bindings which are generated based on our OpenAPI 3.0 REST API definition.

Bindings for other languages can be generated using Swagger Editor