Looks like we can delete recipient in the REST API but is there a method in the SOAP API that will allow deleting recipients?
Currently we are calling CreateEnvelopeFromTemplatesAndForms() from the SOAP API to create the draft envelope. The template may have multiple recipients and some of them may be optional. Before we can send the envelope by setting ActivateEnvelope to true or calling SendEnvelope(), seems like all the recipients' info (i.e. name, email, etc) must be filled in, otherwise the call will throw an error "...email address is invalid...". So we would like to delete the optional recipients when they are not needed.
Can we somehow define an InlineTemplate for the CreateEnvelopeFromTemplatesAndForms() call to delete recipients?
We also looked at CorrectAndResendEnvelope(), seems like we can edit recipient info but not delete.
Thanks in advance!
No, there is no SOAP equivalent for deleting recipients. This is one of the reasons why DocuSign's REST API is encouraged over the SOAP API, and this feature gap is growing with every monthly release.
Three workarounds I can think of:
Use a recipient type like Editor or Agent to edit the recipient info after envelope has been sent.
Instead of deleting optional recipients, only add them later in the process if needed.
Use REST to delete your optional recipients.
For #1, there are recipient types like Editor, Agent, or Manage Recipients which allow you to edit the recipient info of recipients that are later in the routingOrder.
For #2, instead of adding your recipients at the beginning, only add the required recipients then at a later time if it's decided that optional ones are needed, add them through a Recipient Correction/Addition.
For #3, the nice thing is that you can intermix the APIs, and make some calls in SOAP and others in REST. The only thing you'd have to do is write code to send a REST request and parse the response.
Related
I've been working on an integration that sends an envelope to 2 signers. I am trying to test and program for the case of 1 of the signers having a bad email address. I would need to:
Be notified of this (webhook?)
Update the email address for the signer
Update the email address in the custom fields as that's printed on the agreement
Resend the envelope
When I enable the delivery failure notification in Connect (this is set up at the account level, for now), I don't see where the failure is noted in the webhook response or for which signer the error is happening.
I've found multiple links via Google talking about "correct and resend" but I haven't been able to get anything definitive in terms of what steps need to be taken or a (PHP) code example. I've also found "resend" in the API reference but still no code examples.
I also haven't seen any code examples (PHP) of how I would update a signer's email address and how that would work via the API.
It'd also be good to know how to update custom field data for both signers so the email address in the contract is updated (it's listed separately as part of the custom form data).
And finally, how would I resend the envelope?
Thank you for your thoughts.
Per DocuSign support (customersupport#docusign.com):
Be notified of this (webhook?)
I have updated your account settings and now you should be able to see AutoResponded in your webhook messages when email invalid or unreachable.
(my comments: so it sounds like you have to ask to be able to see this stuff, it's not part of their standard webhook responses)
Update the email address for the signer
I also haven't seen any code examples of how I would update a signer and how that would work.
Unfortunately we don't have an example for recipient update but the logic is to get list of all recipients, pick the one need to be updated, and update.
You can use below to retrieve all recipients per envelope
https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/enveloperecipients/list/
GET /restapi/v2.1/accounts/accountId/envelopes/envelopeId/recipients
Extract the one you need to update edit email and update using the below
https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/enveloperecipients/update/
PUT /restapi/v2.1/accounts/accountId/envelopes/envelopeId/recipients
You can also see example code in C# how to do this in this thread https://github.com/docusign/docusign-csharp-client/issues/307
Update the email address in the custom fields as that's printed on the agreement
There is bug case created ( above link ) regarding this. At the moment you can not update signer custom fields case EC-2944.
Resend the envelope
You can resend the envelope during recipient update
https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/enveloperecipients/update/
PUT /restapi/v2.1/accounts/accountId/envelopes/envelopeId/recipients
My commentary:
Since custom fields can't be updated, this whole use-case goes out the window. We can't have contracts with incorrect data on it, so my client will have to do these corrections by hand. Kind of a bummer.
I've been looking at the API docs on Docusign (e.g. https://developers.docusign.com/esign-rest-api/guides/envelopes) but finding it pretty unclear.
I would like to:
Upload a document (e.g. pdf or docx)
Email signatory #1 that it needs to be signed
Know when they sign e.g. a webbook
Email the next signatory that it's their turn to sign it
I don't want to add all the people who need to sign it at once, but request them one by one (or multiple at each stage).
Can someone please point me in the right direction for doing this? Thanks
I'd recommend checking out DocuSign's Quickstart examples in your favorite language: https://developers.docusign.com/esign-rest-api/code-examples/quickstart-request-signature-email
To have signatories receive the envelope sequentially, you'll want to define a routing order for each recipient. DocuSign automatically moves through the routing order, so after signer 1 completes their portion, signer 2 will be notified.
To receive a notification to your webhook listener, you'll want to look in to DocuSign Connect: https://developers.docusign.com/esign-rest-api/guides/connect
I want to know if this is possible: I would like to have a custom text field on an envelope that I set and if the envelope fails for some reason, like there are missing tabs or email address is bad, I want to be able to look at the exception and see the custom field that I set. Would this info be in the raw data? It is as important to us to know which envelopes failed as to know why they failed. I saved the custom field in a database before sending out the envelope. When it fails, I can look up that custom field and discover which envelope didn't make it and to take some action, like correcting and resending.
If the envelope is created incorrectly (i.e: specifying a conditional parent tab which does not exist, syntax error, etc), then you will know at the time you attempt to create the envelope w/the API. The reason will be included in an error code the API returns
If an envelope was sent to an email address which does not exist/bounces, that information can be discovered using the DS API to see a recipient/envelope status of 'autoresponded', or if you are using DS Connect you can receive a push notification.
Is there additional rationale why you want to use a custom field? Per the above, I do not believe it is necessary or applicable.
With the RestSharp api, I was able to get the Request body. The Request body has a collection of Parameters, and one of those items is the RequestBody.
Sign at Docusign
As per the above thread, it is possible to retrieve Signing console URL for email recipients too by setting EmbeddedRecipientStartURL property to value "SIGN_AT_DOCUSIGN", As per the documentation(Sign at Docusign), below example has to be framed in order to open Docusign Signing console.
http://senderHost/[[mergeField1]]/beginSigningSession?[[mergeField2]]&[[mergeField3]]
Please explain what is senderHost & what should be filled in the mergeField properties accordingly? Let me know if you need any additional information related to this query.
BVS, I believe that's the opposite. If you provide EmbeddedRecipientStartURL field with SIGN_AT_DOCUSIGN, the signature will happen completely on DocuSign, and you don't have to provide any URL or merge fields.
If the value SIGN_AT_DOCUSIGN is used for this node, the recipient
will be directed to an embedded signing or viewing process directly at
DocuSign.
On the other hand, if you want to route the client through your own application BEFORE he or she goes to DocuSign, you could provide this kind of template URL with merge fields to better handle the request.
Information can be appended to the embeddedRecipientStartURL using
merge fields. The available merge fields items are: envelopeId,
recipientId, recipientName, recipientEmail, and customFields. The
customFields must be part of the recipient or envelope. The merge
fields are enclosed in double brackets.
By example: if you wanted to handle the request before the signer goes to DocuSign, you could send something like https://senderHost?envId=[[envelopeId]]&email=[[recipientEmail]]. Sender host is your host, so it can be anything on the internet (www.yoursite.com, by example).
Hope it helps!
Can we "refresh" the document names in envelopes retroactively? We've already sent out our envelopes but need to change the document names inside of the completed/sent out envelopes. There is around a few hundred envelopes to update so updating each one individually will be problematic. The reason we need to do this is that we have a few different envelopes but when setting up the documents inside of the envelope the documents were setup with the same name so when we receive the Document through the API the documents had the same name so each document was overwriting the previous entry.
Sorry but I don't believe this is possible. Once an envelope has been sent and its status is "In-Process" the only aspects you can change are recipient(s), tab(s), and or custom fields (which are at the envelope level, not document level), and if it's in "Completed" status then there's nothing you can change about it.
So there's currently no way to change the document names of a sent envelope, and I'm not sure if there ever will be as that's like having someone sign something, then changing an aspect about that something that they signed underneath them.
With regards to what you CAN change once an envelope has been sent, you can edit the following recipient info:
email, userName, signerName, routingOrder, faxNumber, and deliveryMethod
And you can modify tabs for a given recipient as well. You can also modify any envelope custom fields you might have in the envelope. One final point I'll make, is that in our system a POST http request is always to add or create things, and a PUT http requests is for modifying existing envelopes - so whenever you are modifying a recipient, tab, or custom field make sure your requests are PUT requests.
References:
Modify or Correct and Resend Recipient Information
Modify Envelope Custom Fields for an Envelope
Modify Tabs for a Recipient