We're exploring using Envelope Connect to receive status updates for our envelopes we create through the DocuSign API.
We'd like the messages to come to us in JSON format, but it seems that no matter what we provide, the messages arrive in XML format.
An example of an eventNotification we're including with our envelopes is below:
{
"envelopeEvents": [
{
"envelopeEventStatusCode": "Completed",
"includeDocuments": false
},
{
"envelopeEventStatusCode": "Declined",
"includeDocuments": false
},
{
"envelopeEventStatusCode": "Voided",
"includeDocuments": false
}
],
"eventData": {
"format": "json",
"includeData": [
"custom_fields"
],
"version": "restv2.1"
},
"loggingEnabled": true,
"recipientEvents": [
{
"includeDocuments": false,
"recipientEventStatusCode": "Completed"
}
],
"requireAcknowledgment": true,
"url": "https://webhook.site/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
The DocuSign Developer API Reference says to use the "events" property of the eventNotification object when using the JSON SIM event model, but when we use this instead of envelopeEvents or recipientEvents, we don't receive any status updates.
I followed the message format in this youtube video, which shows the message coming back as JSON, but when I do the same, we get XML.
https://www.youtube.com/watch?v=bcTaBKf_c50
The Connect logs in the DocuSign Admin center confirm this:
Connect log
Could there be some configuration in our account that is preventing the message format from being JSON?
We do have some account level Connect configurations, could these be interfering?
Yes, you have to do this in the "Settings" page (DocuSign Admin) and go to the Connect section and configure account-wide connect configuration.
There, you can select which format you want used like this:
By selecting REST v2.1, you will get JSON instead of XML.
DocuSign Support was able to identify the issue.
Our API calls were going through /v2/ of the REST API:
https://demo.docusign.net/restapi/v2/
But JSON status updates are only sent with v2.1.
https://demo.docusign.net/restapi/v2.1/
Related
There are several conflicts in the docs about the eventNotification object in the envelopeDefinition type.
First
https://developers.docusign.com/docs/esign-rest-api/reference/Envelopes/Envelopes/create/#eventNotification
Shows the following
{
eventNotification:eventNotification{
eventData:connectEventData{
format:String,
version:String,
includeData:Array
}
}
}
while
https://apiexplorer.docusign.com/#/esign/restapi?categories=Envelopes&tags=Envelopes&operations=create
shows
{
eventNotification:eventNotification{
connectEventData:undeclared_type{
format:String,
version:String
}
}
}
It is unclear which of these is correct.
Secondly
https://developers.docusign.com/docs/platform/webhooks/connect/architecture
Very heavily implies that a valid version and format would be v2.1 and JSON, however after many combinations I'm only ever able to get XML back. I was unable to find any place in the docs that list out the allowed versions and formats.
Lastly
https://developers.docusign.com/docs/platform/webhooks/connect/configuration
Is not what is shown at
https://admindemo.docusign.com/connect/edit-custom?accountId=\
The questions that arose because of this are:
Is there some doc that I just missed in my exploration? If not then an answer to the following would be greatly appreciated.
What are valid format, version and includeData values?
Is the name of the object containing those fields eventData or connectEventData?
Does the webhook support any format other than XML?
To get json formatted connect messages from eventNotifications defined in the envelope create call, I'd refer to this blog for some great detail - https://www.docusign.com/blog/developers/connect-webhooks-json-notifications.
It will look something like:
"eventNotification": {
"url": "https://yourwebhookurl",
"loggingEnabled": "true",
"requireAcknowledgment": "true",
"eventData": {
"version": "restv2.1",
"format": "json",
"includeData": ["tabs"]
},
"envelopeEvents": [
{"envelopeEventStatusCode": "Completed",
"includeDocuments": "false"}
]}
Keep in mind, SIM is not available for json at this time, so make sure your account is set for aggregate messaging.
After contacting support I got the following answer:
Connect publishing in JSON format is planned and near release, but due
to some performance issues that needed to be addressed, the rollout
has been delayed. Unfortunately, this means that some of our
documentation is a bit ahead of schedule.
The notification format is as follows:
"eventNotification": {
"url": "https://example/EventNotifications",
"loggingEnabled": "true",
"requireAcknowledgment": "false",
"envelopeEvents": [{
"envelopeEventStatusCode": "sent",
"includeDocuments": "false"
},
{"envelopeEventStatusCode": "delivered"},
{"envelopeEventStatusCode": "completed"},
{"envelopeEventStatusCode": "declined"},
{"envelopeEventStatusCode": "voided"}
]
}
I'm Using an invite API from MS GRAPH - Invite LINK
Send a sharing invitation – External users
POST /me/drive/items/{item-id}/invite
POST /sites/{siteId}/drive/items/{itemId}/invite
The responses from the above request returns 200 OK response code and a permission object is returned , but the Sharing link(webUrl) under the link object returns “null” most of the times due to which the shareable link cannot be shared to External user for editing the document.
REQUEST BODY:
{
"recipients": [
{
"email": "abc#abc.com"
}
],
"message": "Here's the file that we're collaborating on.",
"requireSignIn": true,
"sendInvitation": false,
"roles": [ "write" ]
}
Here i don't want to share the item throgh mail hence making sendInvitation false and using the webURL recevied from response for collaboration.
Observation :
It works with gmail and outlook account.
For business accounts it's not working receiving url as null.
Samples:
If i invite for the first time , i'm getting below response ,
Sample Excepted Response:
{
"#odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(permission)",
"value": [
{
"#odata.type": "#microsoft.graph.permission",
"roles": [
"write"
],
"grantedToIdentities": [
{
"user": {
"email": "##########.com"
}
}
],
"invitation": {
"signInRequired": true
},
"link": {
"type": "edit",
"webUrl": "https://**********encryptedURL*****/"
}
}
]
}
From the second time link object not coming in the response,
Sample Response Received Without webURL:
{
"#odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(permission)",
"value": [
{
"#odata.type": "#microsoft.graph.permission",
"id": "###############",
"roles": [
"write"
],
"grantedTo": {
"user": {
"email": "#############.com",
"id": "#############",
"displayName": "#######"
}
}
}
]
}
i resolved my problem by using the upload API LINK
, once upload is successful the API returns response which will have "webUrl" link that can be used to share from second time.
(After exploring more with MS GRAPH API's observed that if we are
sharing the same file multiple times it will not give any new link as
the old link only can be used )
Actual Flow : Upload File -> Share File (this was happening everytime)
Changed Logic : First time : Upload File -> Share file
Second Time onwards : as file is already shared , using the url from upload API Response
As file is already shared with user for the first time hence the url which we are getting as response from UPLOAD API can be used , this url can be accessible by already shared user.
So i changed my logic if the user performing the operation for first time then i'm uploading file and sharing with him , if the user wants to perform same operation again instead of sharing the file again using the upload response url it works for me.
Posting this solution as it might help someone
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
I'm trying to use next API method: https://msdn.microsoft.com/office/office365/APi/mail-rest-operations#SendMessages. Sending messages without attachments works just fine, but I can not understand how to send message with attachments.
According to docs, Message structure can contain array of Attachments with items of type https://msdn.microsoft.com/office/office365/APi/complex-types-for-mail-contacts-calendar#RESTAPIResourcesFileAttachment . Problem is in the field ContentBytes -- it is impossible to dump bytes to JSON before sending request to this API method (actually dumping any BLOB to JSON is nonsense).
How should I pass Attachments using REST API at all?
Thanks.
There's an example of passing the attachment on that page: https://msdn.microsoft.com/office/office365/APi/mail-rest-operations#SendMessageOnTheFly
I know I'm 3 years late but, you can look at this example:
https://msdn.microsoft.com/office/office365/APi/mail-rest-operations#create-and-send-messages (if you don't get forwarded to the section "Create and send messages", please scroll manually).
I know it is 365 and not Microsoft Graph but request is absolutely same.
This is basically how JSON representation of the post method looks:
https://outlook.office.com/api/v2.0/me/sendmail
{
"Message":
{
"Subject": "Meet for lunch?",
"Body": {
"ContentType": "Text",
"Content": "The new cafeteria is open."
},
"ToRecipients": [
{
"EmailAddress": {
"Address": "garthf#a830edad9050849NDA1.onmicrosoft.com"
}
}
],
"Attachments": [
{
"#odata.type": "#Microsoft.OutlookServices.FileAttachment",
"Name": "menu.txt",
"ContentBytes": "bWFjIGFuZCBjaGVlc2UgdG9kYXk="
}
]
}
}
I'm currently testing an API call that will ultimately allow for an agent to provide signature and another party to sign in person. In sending the call via API Explorer I continue to receive the following response:
{
"errorCode": "INVALID_EMAIL_ADDRESS_FOR_RECIPIENT",
"message": "The email address for one of the recipients is not valid."
}
I've read in the REST API guide that this needs to be enabled for my account; it may be that my demo dev account does not have this enabled. I just need to verify whether or not that I'm not omitting any essential parameters in this call. I've tried passing in my email (as the account holder) and still receive this error. Here is my request body JSON:
{
"emailBlurb": "test",
"emailSubject": "test",
"documents": [
{
"name": "ChiropractorPlusApplication.pdf",
"documentId": "1"
}
],
"recipients": {
"inPersonSigners": [
{
"hostName": "Joe Host",
"recipientId": "1",
"name": "Name",
"email": "host#gmail.com",
"signerName": "Insured"
}
]
},
"status": "sent"
}
Thanks!
I believe you have found a bug with the REST API Explorer in that it's missing at least one field for In Person Signers. If you look at the REST API documentation you'll see that there's one more required parameter for In Person Signers, which is the hostEmail
Try adding to your JSON
"hostEmail" : "host's email address",
And I have a feeling that will do the trick. See page 275 of REST API v2 PDF for info on In Person Signers recipient type. It first shows a sample request with all the options then below that it lists the required fields for this recipient type:
http://www.docusign.com/sites/default/files/REST_API_Guide_v2.pdf