Yes, please see this sample Github repository
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.
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.
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.
2) Same PDF documents to sign (with the possibility to add / remove some of them) and variable number of recipients.
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.
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.
What is the recommended way to send to signing a large number of PDF files as part of the envelope ?
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.
Yes. Just set the recipient email to email@example.com
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 :
- Named pipes
Additional, using the Extensibility API , a custom provider can be written to expose the events using custom protocols.
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.
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 = "https://yourdomain.com";
Yes, the on-premise version allows continuous synchronization of users from Active Directory .
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.
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.
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).