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

    Browse REST API Specifications

General information

The BulkSign API is exposed in 3 "flavors" : SOAP, REST and GRPC. There is no difference in functionality between them. Use whichever is best suited for you as integrator.

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/webapi/rest/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

• Result : this contains the result of API request.

• RequestId : a unique identifier for the request. Please provide this to us when troubleshooting failed requests.
  

API Endpoints

-SOAP API endpoint is located at https://bulksign.com/webapi/soap and the WSDL at https://bulksign.com/webapi?wsdl

• REST root endpoint is located at https://bulksign.com/webapi/rest/ and the Swagger endpoint is available at https://bulksign.com/webapi/swagger/

Error Handling

The Bulksign API will return error codes and 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)

GRPC API Notes

Notes about the GRPC API :

• it is available ONLY for the on-premise version of Bulksign.

• the proto file useable for integrations is available on Github

• due to GRPC protocol limitations (no inheritance, cannot have multiple input parameters, enum specific rules etc), there are some changes in the API models compared with the REST/SOAP API.

1) the authentication model details are built into each input parameter for each method. Because of this, we also renamed the input parameter, their name ends with "Input" (eg EnvelopeApiModelInput instead of EnvelopeApiModel).

2) because the lack of inheritance, the return types for each method are unique. For example the SendEnvelope method return type is SendEnvelopeResult.

3) simple string input are now wrapped in specific types (instead of "string envelopeId" there is a EnvelopeIdInput type).

4) some of the API enums have a new value called "NO_{{enum name}}" which always the value 0. That is not meant to be used, it's present there just to "satisfy" the proto compiler which requires the first value of any enum to be 0.

5) some enum values had to be renamed. For example instead of "InProgress", it was renamed to {enum value}_InProgress. This was done because the proto compiler requires unique name for enum values.

• the port used by the GRPC API can be configurable from settings.json, the setting name is "GrpcApiPort". Setting that to 0 will disable the GRPC API.

Accessing SOAP API using .NET TCP Binding (on-premise version only)

If you integrate from .NET, you can also access the SOAP API using the TCP binding instead of HTTP (which, depending on the payload, is faster).

• to enable the TCP binding, edit settings.json, search for "NetTcpBinding" and set the value "net.tcp://{{localhost}}:{{port}}/tcp" Replace {{localhost}} with the IP address of the server (or the DNS name). Replace {{port}} with the port value.

• make sure IIS WAS is enabled and add "net.tcp" as allowed binding for the Bulksign WebApi IIS website

• make sure the configured port is allowed in the firewall

• to call the API, reference the following Nuget packages

    <PackageReference Include="System.ServiceModel.NetTcp" Version="4.10.2" />
    <PackageReference Include="System.ServiceModel.Primitives" Version="4.10.2" />

and also reference the assembly "Bulksign.Api.dll" that comes with Bulksign.

• sample code to invoke methods :

IClientChannel channel = null;

//replace localhost and the port number with what you have previously configured 
var factory = new ChannelFactory<Bulksign.IBulksignSoapApi>(new NetTcpBinding(), new EndpointAddress("net.tcp://localhost:8900/netTcp"));
factory.Open();
try
{
    Bulksign.IBulksignSoapApi client = factory.CreateChannel();
    channel = client as IClientChannel;
    channel.Open();
    var result = client.GetVersion();
    channel.Close();
    Console.WriteLine(result);
}
finally
{
    factory.Close();
}

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

API related resources on Github

C# API sample code

OpenAPI specification for our REST API

Postman collection

Integration Sample which handles callbacks and polling

Sample which demonstrates integration signing into your application using an iframe