Is there sample code to describe different integration options ?

Yes, please see this sample Github repository

Are there any differences between the SOAP, REST and GRPC APIs ?

There are no differences, both API "flavors" use the same types and names.The REST API is even using "POST" to be similar to the SOAP one. Feel free to choose the "flavor" which is best suited for you.

Types of integrations

There are a few types of integration scenarios, the difference being in the content of the PDF file which will be signed and the recipients.

Here are some recommendations for each scenario :

1) Same PDF documents to sign every time, each time signed by different signers.

Recommendation :

  • create a template in Bulksign with the files and "placeholder" recipients and assign the form fields and signature fields to those recipients

  • save the id of the template and use the "SendEnvelopeFromTemplate" API to replace the recipients and send the documents for signing.

Sample code for this scenario on GitHub

2) Same PDF documents to sign (with the possibility to add / remove some of them) and variable number of recipients.

Recommendations :

  • if the PDF documents contain signature fields, you can invoke AnalyzeFile ONCE to obtain the ids of the form / signature fields. This needs to be done only once, independent of the integration code.

  • in the integration code, assigned the hard-coded list of form fields to recipients.

  • if needed, add new form/signature fields as needed and assign them.

  • use SendEnvelope to send the documents for signing, the PDF files should be included with the request.

Sample code for this scenario on GitHub

3) Dynamic : PDF files will always be different and the number of signers differs every time.

  • invoke PrepareEnvelope API with all PDF files which will return a EnvelopeApiModel populated with a placeholder recipient.

  • assign these ids to recipients as required by your integration.

  • if needed add new form/signature fields to documents and assign them to recipients.

  • pass the EnvelopeApiModel received from PrepareEnvelope to SendEnvelope.

Sample code for this scenario on GitHub

Because adding multiple large PDF files to the SendEnvelope input can go over the IIS max request size value, it is recommended to use the StoreTemporaryFile API for each file and use in SendEnvelope the identifiers for all files. Sample code is available here.

For my on premise Bulksign integration, I only need to get the completed documents and copy them in my Document Management System. Is there a easy way to achieve this, without creating a "full integration" ?

Yes, the Bulksign extensibility supports the ICompletedEnvelopeBackupProvider interface which allows you to create a plugin which can copy the documents into the DMS.

Which organization settings can be overwritten individually for each envelope/draft/template from API ?

When sending a envelope (or creating a draft/template), there are a few options which can overwrite the defaults set per organization.

The list of over-writable options :

  • callback URLs can be set for each envelope, the property name is OverwriteCallbackUrls. If this is set it will overwrite the default settings from WebHooks

  • to set a custom signature disclosure text per envelope/draft/template, just set OverwriteSignatureDisclosure

  • to overwrite the signing settings, use OverwriteSignSettings (please note that all fields are required there).

Yes, SendEnvelope returns a RecipientAccess array. For a serial envelope that will contain "SigningUrl" which has the redirection url for signing. On a bulk envelope will return the signing link for all recipients.

Can i disable email notifications for a single recipient ?

Yes. Just set the recipient email to

Can i disable email notifications for signer recipients and manage the signing flow from a integration ?

This can be done by setting the DisableSignerEmailNotifications flag when sending a envelope with the API :

envelope.DisableSignerEmailNotifications = true; 

This will disable signers email notifications and allow the integrator to manage the signing flow using callbacks

How do i integrate with Bulksign using callbacks ? Can these callbacks be triggered using something else than HTTP(S) ?

Please see the callbacks section for details . By default (in SAAS version) callbacks are sent using HTTP(S). For OnPremise version there are 2 additional providers to send them :
- RabbitMQ
- Named pipes
Additional, using the Extensibility API , a custom provider can be written to expose the events using custom protocols.

Can I use my own SMS gateway with Bulksign ?

Yes, this is possible in the private instance and on-premise version versions of Bulksign. See this GitHub sample to get you started.

Can I use my private email server to send email notifications ?

Yes, for private instance and on-premise version versions. Also Bulksign ships with providers for SendGrid, Sparkpost and Mailjet

Is the Bulksign platform extensible ? Can I replace different parts of the functionality ?

Yes, absolutely. Extensibility is one of the core design decisions of the Bulksign platform. The platform is loose coupled and allows the replacement of different "components". You can use, for instance, the envelope routing "component" and integrate a new UI and signer notification scheduler in your solution.

Extending the platform is done by implementing specific interfaces defined in our extensibility library . See also the Extensibility section

After finishing the signing process, can I redirect the user to my own website ?

Yes, please configure in Bulksign UI the redirection URL in Settings / Signing Redirection. Specific redirection for each envelope can also be enabled :

 OverwriteSignSettings.DocumentDownload = SignerDownloadDocumentActionTypeApi.RedirectToUrl;
 OverwriteSignSettings.DocumentDownloadRedirectUrl = "";

Can I redirect the user to my own website when he logs off ?

Yes, this is possible on the private instance and on-premise version. Just set the URL value for the setting named LogOffRedirectionUrlForHostedVersion

Can I import users from Active Directory ?

Yes, the on-premise version allows continuous synchronization of users from Active Directory .

Can a user do API requests before validating his email address ?


My callback handler was down and I've missed it. Is there a way to re-trigger it ?

Yes, open the envelope details page, click the "INFO" icon on the top right side of the page. From there click "Callbacks" to see all triggered callbacks for that envelope and click the link for the one that you want to trigger again.

Is there a way to retrieve the list of language codes supported for my organization ?

Yes, the API is called GetLanguageCodes.

I've added a new language translation to WebSign but GetLanguageCodes codes doesn't returns the identifier for this new language. Why ?

GetLanguage returns the list of supported languages for email templates. You can still us the new language translation, call GetEnvelopeDetails and append/replace the new language code in the SigningUrl (the name of the query parameter is "lng").

I'm using StoreTemporaryFile with a document that has tags. If I enable the DeleteTagText option, subsequent requests to PrepareSendEnvelope are NOT returning the form fields. Why is that ?

DelateTag will enforce the deletion of the tags from the document the first time is processed by the PrepareSendEnvelope request. So if you intend to remove the tags from the document ,DO NOT REUSE the documents but either pass them "inline" in PrepareSendDocument or call StoreTemporaryDocument each time.

How to work with concurrent recipients ?

A concurrent envelope means the order in which the recipients sign is not predefined. The signing link is sent to ALL signers and the signer which opens first the link will temporarily "lock" the envelope until the signing process is done.

Here are some tips about working with concurrent envelopes :

  • you can create a concurrent envelope by specifying the type like this :
    EnvelopeApiModel ev = new EnvelopeapiModel();
    ev.EnvelopeType = EnvelopeTypeApi.Concurrent;
  • the SendEnvelope result for concurrent envelope will ONLY have the signing link (since the order of signing is determined only when a signer opens the link). AccessCode and SignStepIdentifier properties will be empty.

  • the period of time for which signing is locked by a recipient is configurable from "settings.json", the property is called "ConcurrentRecipientAutomaticUnlockHours"

  • "unlocking" signing again can also be done from API, the method is called "UnlockConcurrentRecipient".

  • to find the recipient which currently locked signing, please see the answer to this question

DownloadEnvelopeCompletedAttachments returns ALL attachments from the envelope PDF files. Is this the correct behavior ?

Yes, the result of DownloadEnvelopeCompletedAttachments is intended to give you access to ALL the attachments even if some attachments were already present in the document.

How can I obtain the identification images used by recipients with "Identity Verification" authentication ?

Using the DownloadEnvelopeCompletedAttachments API. For each recipient that used "Identity Verification" you will find 2 attachments files. The file name format is : "recipient-name" + (selfie / id).