I'm trying to use DocuSign via Rest API and ran into a question. After a user signed document and is redirected to the URL that is specified on RecipientView (/accounts/{accountId}/envelopes/{envelopeId}/views/recipient), Considering both best and worst case scenarios, how long should we wait before we download the signed document?
I'm asking this question because we saw some issues with SigniX in the past where, after SigniX returning the control to redirectUrl, the signed document was not available to download. Even though this happened very little number of times which might be <1% of all requests, Every single document is $$ and cannot afford to lose it.
If answer to my question is Yes, Please provide a C# example on using webhook.
Thanks.
You can setup DocuSign WebHook aka Connect notifications at your account level or envelope level and automatically receive the Documents when an envelope is completed.
Here is a sample CreateEnvelope request to setup configuration for the connect notifications per envelope level. Look at eventNotification property. All you have to do is host a listener to which DocuSign can send messages.
{
"emailSubject": "Testing connect notification",
"status": "sent",
"eventNotification": {
"url": "<Add your listener URL here>",
"loggingEnabled": "true",
"requireAcknowledgment": "true",
"envelopeEvents": [
{
"envelopeEventStatusCode": "Completed"
}
],
"includeDocuments": "true"
},
"recipients": {
"signers": [
{
"name": "john smith",
"email": "johnsmith#acme.com",
"recipientId": "1",
"routingOrder": "1"
}
]
},
"documents": [
{
"documentId": "1",
"name": "Contract",
"fileExtension": "contract",
"documentBase64": "DQoNCg0KDQogICAgICAgICBEdW1teSBDb250cmFjdA=="
}
]
}
Here are some useful links which help you to setup your connect listener
WebHook c# recipe
More Api Recipes
Blog Posts
Webhooks: Don’t Poll Us, We’ll Call You!
Adding Connect Webhooks to your Application
Securing Your Connect Webhook Listener
Related
When using agents/intermediaries to assign signers in DocuSign, we set the clientUserId for the signers to use the embedded signing feature. But DocuSign will automatically send out the email to the assigned signers and we are not able to obtain the signing URL through the API POST {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes/{{envelopeId}}/views/recipient.
As suggested in this thread: https://stackoverflow.com/a/63810135/13191875 . It's due to the clientUserId was removed when agents/intermediaries change the signer's email/name info. It suggests that a workflow could be added to pause the process after the signer's email/name info is changed, and then add the clientUserId to the signer, then resume the workflow.
I tried with request body:
{
"recipients": {
"intermediaries": [
{
"clientUserId": "1",
"email": "aaa#example.com.au",
"name": "Intermediary",
"recipientId": "1",
"routingOrder": "1"
}
],
"signers": [
{
"clientUserId": "2",
"email": "example#example.com",
"name": "example",
"recipientId": "2",
"routingOrder": "2",
"tabs": {
"signHereTabs": [
{
"anchorIgnoreIfNotPresent": "false",
"anchorString": "Signature_anchor_1",
"anchorUnits": "pixels",
"anchorYOffset": "0",
"name": "Please sign here",
"recipientId": "1"
}
]
}
}
]
},
"workflow": {
"workflowSteps": [
{
"action": "pause_before",
"itemId": "2",
"triggerOnItem": "routing_order"
}
]
},
"emailSubject": "DocuSign API - Signature Request on Document Call",
"documents": [
{
"documentId": "1",
"name": "{{fileName}}",
"documentBase64": "{{fileBase64}}"
}
],
"status": "sent"
}
I can set the clientUserId after the signer's email/name is changed. But the workflow cannot be resumed by calling the API PUT {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes/{{envelopeId}}?resend_envelope=true. So the signer's signing URL cannot be obtained since the process is paused, the signer's status stays in created.
I also tried the with agents:
{
"recipients": {
"agents": [
{
"clientUserId": "1",
"email": "aaa#example.com.au",
"name": "Agent",
"recipientId": "1",
"routingOrder": "1"
}
],
"signers": [
{
"clientUserId": "2",
"email": "",
"name": "",
"recipientId": "2",
"routingOrder": "2",
"tabs": {
"signHereTabs": [
{
"anchorIgnoreIfNotPresent": "false",
"anchorString": "Signature_anchor_1",
"anchorUnits": "pixels",
"anchorYOffset": "0",
"name": "Please sign here",
"recipientId": "1"
}
]
}
}
]
},
"workflow": {
"workflowSteps": [
{
"action": "pause_before",
"itemId": "2",
"triggerOnItem": "routing_order"
}
]
},
"emailSubject": "DocuSign API - Signature Request on Document Call",
"documents": [
{
"documentId": "1",
"name": "{{fileName}}",
"documentBase64": "{{fileBase64}}"
}
],
"status": "sent"
}
After the name/email is added by the agent, the process is paused and I set the clientUserId for the signer, I verified that it is added by calling the get recipients info API. After I resume the process, an email is sent by DocuSign to the signer and I cannot get the embedded signing URL for that signer. I can see the clientUserId is removed for that signer by calling the get recipients info API again.
My question is:
when using agents/intermediaries in DocuSign, is it possible that we can obtain the embedded signing URL for the assigned signer whose email is updated/added by agents/intermediaries?
when using agents/intermediaries in DocuSign, is it possible that we can turn off that email from DocuSign to the signer, whose email is updated/added by agents/intermediaries?
when using agents/intermediaries in DocuSign, is it possible that we can obtain the embedded signing URL for the assigned signer whose email is updated/added by agents/intermediaries?
Yes, but you'll first need to assign a clientUserId to the recipient.
And since the recipient has already been sent an email invite to the signing ceremony, adding a clientUserId attribute is problematic since doing so will invalidate the email invite.
when using agents/intermediaries in DocuSign, is it possible that we can turn off that email from DocuSign to the signer, whose email is updated/added by agents/intermediaries?
To do this, you need to stop the workflow as I described in the other answer.
Much better would be to expand your API application so that it is used to change the name/email of the signer. That way your application can also set the clientUserId at the same time and the signer won't receive any email.
Basically, embedded signing is only intended to work if the envelope is created/edited via an API program. Your goal of using an API program and using the regular DocuSign Web App (which focuses on email delivery, not embedded signing) is mixing apples and oranges. It is possible but problematic.
You can potentially use the new Advanced Recipient Routing (ARR) feature to pause the envelope, obtain the information about the next recipient (via GET call to listRecipients) and then modify it to add the clientUserId. I have not tried this, but in theory that should work.
ARR is now available in demo/developer accounts for all new accounts created.
https://developers.docusign.com/docs/esign-rest-api/how-to/pause-workflow has information about how to create the envelope such that it pauses after a specific routing number.
https://developers.docusign.com/docs/esign-rest-api/how-to/unpause-workflow shows how to resume the envelope once you made your change.
The other thing you may need to do is add a webhook call for when the status of the intermediary was updated so you know when to update the next recipient (but before you can do that you would have to obtain the information about the new recipient).
I am trying to add the new witness functionality to my API call. Heres the json that I am sending now:
POST https://demo.docusign.net/restapi/v2/accounts/[my id]/envelopes
{
"emailSubject":"test",
"status":"sent",
"templateId":"[Valid template id]",
"templateRoles":[
{
"roleName":"sign1",
"email":"valid#email.com",
"name":"John",
"recipientId":"1",
"routingOrder":"1",
"tabs":{}
},
{
"roleName":"Witness for sign1",
"witnessFor":"sign1",
"witnessForGuid":"1",
"recipientId":"2",
"routingOrder":"2",
"recipientType":"witness"
}
]
}
I have configured the template in DocuSign and verified the functionality by sending an envelope via the DocuSign website. However, the envelopes created from my API call does not trigger the witness functionality. I am not sure what I am missing, and I really appreciate any help/feedbacks.
Cheers
Here is a successful Envelopes::create call that includes the witness recipient type:
"recipients": {
"witnesses": [
{
"name": "Witness Name",
"email": "witness#example.com",
"recipientId": "2",
"witnessFor": "1"
}
],
"signers": [
{
"email": "someone#example.com",
"name": "Signer name",
"recipientId": "1",
"clientUserId": "1000",
"tabs": {
"signHereTabs": [
{
"anchorString": "/sig1/",
"anchorXOffset": "20",
"anchorUnits": "pixels"
}
]
}
}
]
},
Suggested changes in your templateRoles attributes:
(Not tested)
I'm assuming that you have a witness role set in the template.
If you don't, then I think you'll need to add the additional witness recipient to the envelope via composite templates.
You can also try your idea of including "recipientType":"witness"
At the API level, the witness is a distinct recipient for the envelope. It could also the case that the DocuSign web tool creates a hidden recipient (and recipient role) for the witness. To determine if this is the case, use API logging to see what the DocuSign web tool is actually doing.
"templateRoles":[
{
"roleName":"sign1",
"email":"valid#email.com",
"name":"John",
"recipientId":"1",
"routingOrder":"1",
"tabs":{}
},
{
"roleName":"Witness for sign1",
"witnessFor":"1",
OMIT THIS: "witnessForGuid":"1",
"recipientId":"2",
OMIT THIS: "routingOrder":"2",
OMIT THIS: "recipientType":"witness"
}
]
Note
Older developer sandbox accounts don't include the witness feature. If you receive the error message of not having the witness feature, contact go-live --at-- docusign.com to have the feature added to your developer account.
Turns out to be a bug in DocuSign, I had to split the creation step into 2.
1st POST /envelopes:
{
"emailSubject":"Template Action Test",
"status":"created",
"templateId":"866fcb03-1342-4678-9dc3-107772c59e89",
"templateRoles":[
{"roleName":"sign1","email":"email#test.com","name":"JK","tabs":{}}
]
}
2nd PUT /envelopes/envelope-id:
{
"status":"sent"
}
I have a situation where I want to be able to differentiate between envelopes based on a 'type'. For example, I'll have quotes and invoices, both of these can be sent to the same person so I'd like to know if there's a way of checking some sort of field that could differentiate the two. Currently I'm rather crudely post processing the API results and checking for 'quote' in the document type and I'd like a rather more reliable solution
thanks,
Oliver
You can use Envelope Custom Fields aka Document labels to specify additional metadata for an envelope.
Envelope Custom fields aka Document labels can be used in the envelopes for your account to record information about the envelope, help search for envelopes and track information. The envelope custom fields are not seen by the envelope recipients.
The DocuSign Web sending tool refers to the Envelope Custom fields as Document Labels. You can configure Document Labels as an Administrator on the Account. See instructions here
Once the Document labels are configured at the account level, you can provide label values for each envelope you send through the web sending tool. See instructions here
The other option is to specify Envelope Custom fields using the API. Here is a sample createEnvelope api request that specifies custom Fields associated with the envelope
{
"emailSubject": "Envelope with custom fields",
"status": "sent",
"customFields": {
"listCustomFields": [
{
"listItems": [
"sample string 1"
],
"name": "myListField",
"required": "true",
"show": "true",
"value": "MyListValue"
}
],
"textCustomFields": [
{
"name": "MyOwnTextField",
"required": "true",
"show": "true",
"value": "MyValue"
}
]
},
"recipients": {
"signers": [
{
"recipientId": 1,
"email": "kaysmith#acme.com",
"name": "kay smith",
"routingOrder": "1"
}
]
},
"documents": [
{
"documentId": "1",
"name": "Agreement",
"fileExtension": "txt",
"documentBase64": "RG9jIFRXTyBUV08gVFdP"
}
]
}
More good news: the DocuSign Sending web tool automatically enables the sender, from the web tool, to set the Envelope Custom Fields.
So if you are sending envelopes programmatically or your users are sending them, it is easy to set custom field values.
I'm having an issue with the following request:
/accounts/{accountId}/envelopes/{envelopeId}/documents
Request:
GET https://na2.docusign.net/restapi/v2/accounts/ACCT_ID/envelopes/ENVELOPE-GUID/documents
And the response looks like this:
{
"envelopeId": "ENVELOPE-GUID"
}
That's the full response I get. It does reproduce at least for several envelopes for me. The envelopes in question are all in 'Completed' or 'Awaiting my signature' sate and have been sent from other DocuSign accounts.
If requested using the sender account, I get a normal response containing the envelopeDocuments array. Same goes for other recipients accounts present in the envelope. The request for those accounts however uses **www.**docusign.net as the baseUrl based on the login_information response.
This also reproduces if I send from the na2 account and later try to retrieve documents list from the www ones so I would say it's some kind of sharding issue.
The request used to work fine with the same accounts earlier.
This is a bug and I've filled it as such with DocuSign's support department.
Authenticating as the sender will be the only workaround you could do for now.
Here's the actual issue:
Create envelope on NA2 and send it to an active account on NA1
Run the following call against REST (v2 or vdev, same results) with the Signer's account information
GET:https://www.docusign.net/restapi/v2/accounts/{accountId}/envelopes/{envelopeId}/documents
Actual Results:
{
envelopeId: "EnvelopeIdGUID"
}
Desired Results:
{
"envelopeId": "EnvelopeIdGUID",
"envelopeDocuments": [
{
"documentId": "1",
"name": "Document1.pdf",
"type": "content",
"uri": "/envelopes/{EnvelopeId}/documents/1",
"order": "1",
"pages": "1"
},
{
"documentId": "2",
"name": "Document2.pdf",
"type": "content",
"uri": "/envelopes/{EnvelopeId}/documents/2",
"order": "2",
"pages": "1"
},
{
"documentId": "certificate",
"name": "Summary",
"type": "summary",
"uri": "/envelopes/{EnvelopeId}/documents/certificate",
"order": "999",
"pages": "4"
}
]
}
Hi Trying to use the DocuSign createsendEnvelope API for a recipient with delivery method FAX and fax number. However in the demo environment the API needs a recipients email and always send out the email. The document is not faxed to the number provided. Can any one confirm if the demo environment is disabled for faxing options?
Thanks in Advance!
The release notes for the "Fax Out" feature in the DocuSign SOAP API describe how to send via fax with the SOAP API (http://www.docusign.com/sites/default/files/DocuSignReleaseNotes-Jun-1-2012-Final.pdf). I tried to apply the same rational to send an envelope via fax with the REST API -- here's my "Create Envelope" request:
POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes
{
"emailSubject": "Please sign this",
"emailBlurb": "Please sign...thanks!",
"status": "sent",
"enableWetSign": "true",
"recipients": {
"signers": [
{
"name": "John Doe",
"email": "johnsemail#outlook.com",
"faxNumber": "2069347947",
"recipientId": "1",
"routingOrder": "1",
"deliveryMethod": "Fax",
}]
},
"documents": [
{
"name": "TestFile.pdf",
"documentId": "1",
"fileExtension": "pdf",
"documentBase64" : "DOCUMENT_BYTES"
}
]
}
Unfortunately, I receive the following error in response to the request (even though the fax number I specified is a valid fax number):
{
"errorCode": "INVALID_FAXNUMBER",
"message": "Fax Number is invalid."
}
To troubleshoot further, I tried a little reverse-engineering in an attempt to determine what properties DocuSign expects you to set for a Fax recipient.
First, using the DocuSign web console, I created/sent a new Envelope with a single recipient where the delivery method = fax. Here's a screenshot of the Status pane from the DocuSign web console for this envlope (immediately after I sent it):
Next, I used the REST API to execute a "Get Recipients" request (GET https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes/{{envId}}/recipients) -- with the goal of examining the recipient object in the response to determine which properties need to be set for a Fax recipient. Here's the response I received:
{
"signers": [
{
"signInEachLocation": "false",
"name": "John Doe",
"email": "johnsemail#outlook.com",
"recipientId": "1",
"recipientIdGuid": "977e571d-6613-492c-8a75-9c207d46c03c",
"requireIdLookup": "false",
"userId": "03c8a856-c0ae-41bf-943d-ac6e92db66a8",
"routingOrder": "1",
"status": "sent"
}
],
"agents": [],
"editors": [],
"intermediaries": [],
"carbonCopies": [],
"certifiedDeliveries": [],
"inPersonSigners": [],
"recipientCount": "1",
"currentRoutingOrder": "1"
}
Interestingly, the API response contains no mention of "deliveryMethod", and no mention of the fax number that was specified for the recipient. This would lead me to believe that perhaps the "fax" delivery method isn't fully supported via the REST API at this time. (If it is supported, then perhaps someone with DocuSign can chime in here and explain how to send via fax (with the API).)
In the meantime, if using the DocuSign SOAP API is an option for you, you might try that route, as it appears that the "Fax Out" feature was initially designed for and implemented in the SOAP API (so I'd expect it to work there, although I haven't personally tested it).