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.

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


API Methods :


SendBundle

SOAP method description : https://bulksign.com/bulksignapi.asmx?op=SendBundle
REST endpoint : https://bulksign.com/restapi/v1/SendBundle
Description : This sends a bundle of documents for signing (this will create a serial bundle). Here's how the JSON structure looks like :
Parameters :
{
Subject : Set the subject of the sign email notification . If left empty, the default email subject will be used.
Message : Set the email body for sign notification. If left empty, the default email body will be used.
DaysUntilExpire : the number of days until the bundle will expire. If left empty it will use the default value (28 days).
Name : name of the bundle.
DisableNotifications : flag to disable notifications (see the Push Notifications section )
Documents [] : array of documents files to be included in the bundle.
FileName : name of the file.
Index - index of the file inside the bundle. In signing mode, the files are sorted according to this index.
ContentBytes - file content as byte[] .
ContentAsBase64String - file content as base64 string. Please set either ContentBytes or ContentAsBase64String, do NOT set them both
FieldMapping - allows you to assign fields to different recipients. See the FAQ section for details.
NewSignatures - allows you to add a new signature field to the document. See the FAQ section for details.
Recipients [] :
Email : the recipient's email address.
Name : the recipient's full name.
Index : the index of the recipients when seeding serial bundles. This determines the orders in which the recipients sign the documents. When sending a bulk bundle, this value is not used.
PersonalMessage : set a personal message for this recipient.
RecipientAuthenticationMethods : set authentication methods for the recipient. These can be :
AuthenticationType : the type of authentication to use.
AuthorizationDetails : details about the authorization. If "Password" is the selected authorization type, this field should contain the actual password.

RecipientType : the type of recipient : Signer or "Receives a Copy".
}

SendBulkBundle

SOAP method description : https://bulksign.com/bulksignapi.asmx?op=SendBulkBundle
REST endpoint : https://bulksign.com/restapi/v1/SendBulkBundle
Description : This sends a bundle of documents for signing in bulk mode
Parameters : Same parameters as SendBundle, the single exception is the Index value for all recipients must have the same value.

SendBundleFromDraft

SOAP method description : https://bulksign.com/bulksignapi.asmx?op=SendBundleFromDraft
REST endpoint : https://bulksign.com/restapi/v1/SendBundleFromDraft
Description : sends a bundle of documents for signing from a already existing draft (draft must already have documents and recipients).
Parameters :
string draftPublicId

GetBundleDetails

SOAP method description : https://bulksign.com/bulksignapi.asmx?op=GetBundleDetails
REST endpoint : https://bulksign.com/restapi/v1/GetBundleDetails
Description : returns details about the specified bundle.
Parameters :
string bundlePublicId

GetBundlesByStatus

SOAP method description : https://bulksign.com/bulksignapi.asmx?op=GetBundlesByStatus
REST endpoint : https://bulksign.com/restapi/v1/GetBundlesByStatus
Description : returns the list of bundles which are currenty in the specified status.
Parameters :
int status

The value can be one of the following
1 (for InProgress bundles)
2 (for Completed bundles)
3 (for Canceled bundles),
4 (for Expired bundles)

GetFinishedDocuments

SOAP method description : https://bulksign.com/bulksignapi.asmx?op=GetFinishedDocuments
REST endpoint : https://bulksign.com/restapi/v1/GetFinishedDocuments
Description : returns a zip file which contains the finished documents and the bundle audit trail. This works only for completed and expired bundles.
Parameters :
string bundlePublicId

DeleteDraft

SOAP method description : https://bulksign.com/bulksignapi.asmx?op=DeleteDraft
REST endpoint : https://bulksign.com/restapi/v1/DeleteDraft
Deletes the specified draft.

GetDraftsCount

SOAP method description : https://bulksign.com/bulksignapi.asmx?op=GetDraftsCount
REST endpoint : https://bulksign.com/restapi/v1/GetDraftsCount
This returns the number of drafts you have.

GetDraftsList

SOAP method description : https://bulksign.com/bulksignapi.asmx?op=GetDraftsList
REST endpoint : https://bulksign.com/restapi/v1/GetDraftsList
This returns a list with current drafts.

GetDraftsDetails

SOAP method description : https://bulksign.com/bulksignapi.asmx?op=GetDraftsDetails
REST endpoint : https://bulksign.com/restapi/v1/GetDraftsCount
This returns the draft details.

CreateDraft

SOAP method description : https://bulksign.com/bulksignapi.asmx?op=CreateDraft
REST endpoint : https://bulksign.com/restapi/v1/CreateDraft
This creates a new draft. The new draft can contain recipients and or documents.

CreateBulkDraft

SOAP method description : https://bulksign.com/bulksignapi.asmx?op=CreateDraft
REST endpoint : https://bulksign.com/restapi/v1/CreateDraft
Same as CreateDraft but this will contain bulk recipients.

GetTemplatesCount

SOAP method description : https://bulksign.com/bulksignapi.asmx?op=GetTemplatesCount
REST endpoint : https://bulksign.com/restapi/v1/GetTemplatesCount
Description : this returns the number of templates the user has access to. Please note this also contains the shared templates.

Curl sample code for REST call :

curl --header "X-Bulksign-Authentication:xxUserTokenxx;xxOrgTokenxx" https://bulksign.com/restapi/v1/GetTemplatesCount -k -X POST -d " "


GetTemplatesList

SOAP method description : https://bulksign.com/bulksignapi.asmx?op=GetTemplatesList
REST endpoint : https://bulksign.com/restapi/v1/GetTemplatesList
This returns a list with current drafts.

GetTemplatesDetails

SOAP method description : https://bulksign.com/bulksignapi.asmx?op=GetTemplatesDetails
REST endpoint : https://bulksign.com/restapi/v1/GetTemplatesCount
This returns the templates details.

CreateTemplate

SOAP method description : https://bulksign.com/bulksignapi.asmx?op=CreateTemplates
REST endpoint : https://bulksign.com/restapi/v1/CreateTemplates
This creates a new templates.

CreateBulkTemplate

SOAP method description : https://bulksign.com/bulksignapi.asmx?op=CreateBulkTemplate
REST endpoint : https://bulksign.com/restapi/v1/CreateBulkTemplate
Creates a template with bulk recipients.

GetContacts

SOAP method description : https://bulksign.com/bulksignapi.asmx?op=GetContacts
REST endpoint : https://bulksign.com/restapi/v1/GetContacts
Returns a list of your contacts.

AnalyzeFile

SOAP method description : https://bulksign.com/bulksignapi.asmx?op=AnalyzeFile
REST endpoint : https://bulksign.com/restapi/v1/AnalyzeFile
This analyzes a pdf file and returns a list with the id and type of all form fields it finds in the pdf file. This can be used to map fields for the SendBundle call.

AnalyzeFileBase64

SOAP method description : https://bulksign.com/bulksignapi.asmx?op=AnalyzeFileBase64
REST endpoint : https://bulksign.com/restapi/v1/AnalyzeFileBase64
Same as AnalyzeFile except the input is a base64 encoded string instead of byte[].



Push Events

Bulksign supports push events (using HTTP for SAAS version and/or custom for private versions) when the bundle status is changing and when a recipient is finishing/rejecting the document to sign.

Notifications for following bundle statuses are supported :

2 - Completed
3 - Canceled
4 - Expired

Notifications are also supported for the following signer events :

2 - Signed
3 - Rejected

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

- {{#bundleid#}} : 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.

Here's a url example for reciving notifications about the bundle status changes :
http://localhost/mysite/notifications?id={{#bundleid#}}&status={{#status#}}

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

- {{#recipientEmail#}} : the email of the recipient.
- {{#recipientstatus#}} : this will be replaced with the recipient status value.

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


FAQ

1. Is there any sample code that describes different integration scenarios ?

Please see this sample code on Github

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

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

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



Integrate signing application directly into your website

It's very easy to integrate signing directly into your website for your users.

We have a full sample (running in .Net Core) on GitHub which showcases this type of integration.


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 a Github repository