eventNotification XML structure

Question

I'm sending a document for signature following "Send an Envelope or Create a Draft Envelope" in the docusign rest api v2, page 93.

The document gets sent and signed, but I'm having a problem with the event notification feature.

I'm a little confused about the xml structure for this feature. I've tried a lot of different combinations, but I can't figure it out. Any help?

This is one of the many I tried...

<eventNotification>
    <url>xxxxxx</url>
    <includeDocuments>false</includeDocuments>
    <loggingEnabled>true</loggingEnabled>
    <envelopeEvents>
        <envelopeEvent>
            <envelopeEventStatusCode>completed</envelopeEventStatusCode>
        </envelopeEvent>
    </envelopeEvents>
</eventNotification>

When you say you can't figure it out, does that mean you are getting an error? If so, what's it say? — Ergin, Oct 29 '13 at 17:00
Sorry, I was away for a week and just got back! I don't get an error, but docusign just doesn't send a message. Your xml format is pretty much the same with mine, but I'll to match the uppercase letters and see if it makes a difference — Trying..., Nov 04 '13 at 12:55

Kim Brandl · Answer 1 · 2013-10-29T17:42:21.397

Although technically speaking, the DocuSign REST API supports both XML format and JSON format, a majority of the DocuSign REST API documentation, code samples, and developer resources are in JSON. Unfortunately that means trying to use XML format with the DocuSign REST API (to do anything beyond the very basic tasks) can be extremely frustrating -- because when your XML request doesn't work as expected, you have virtually no resources to figure out what the correct format is.

For that reason, I'd recommend that you consider using JSON instead of XML with the DocuSign REST API. Here's a JSON request that successfully creates the notification for the envelope.

POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes
{
  "templateId": "TEMPLATE_ID",
  "templateRoles": [
   {
      "roleName": "Signer1",
      "name": "John Doe",
      "email": "johnsemail@outlook.com"
    }
  ],
  "eventNotification":       {
    "url": "http://www.google.com",
    "loggingEnabled": "true",
    "requireAcknowledgement": "true",
    "includeDocuments" : "false",
    "envelopeEvents" : [{
      "envelopeEventStatusCode" : "completed"     
    }]
  },
  "status": "sent"
}

UPDATE: Using information provided by Ergin below, I was able to get this to work using XML -- the key is to use uppercase for both 'Envelope' and 'Events' in the EnvelopeEvents element. Here's an example of a request that successfully triggers the Connect notification:

POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes
<envelopeDefinition xmlns="http://www.docusign.com/restapi">
   <accountId>ACCOUNT_ID</accountId>
   <status>sent</status>
   <templateId>TEMPLATE_ID</templateId>
   <templateRoles>
      <templateRole>
         <email>johnsemail@outlook.com</email>
         <name>John Doe</name>
         <roleName>Signer1</roleName>
      </templateRole>
   </templateRoles>
   <eventNotification>
    <EnvelopeEvents>
      <envelopeEvent>
        <envelopeEventStatusCode>completed</envelopeEventStatusCode>
      </envelopeEvent>
    </EnvelopeEvents>
    <includeDocuments>false</includeDocuments>
    <loggingEnabled>true</loggingEnabled>
    <requireAcknowledgement>true</requireAcknowledgement>
    <url>http://www.google.com</url>
   </eventNotification>
</envelopeDefinition>

I don't want to use json and xml in the code, and I don't want to convert all of my xml code to json. I'm going to wait to see if someone knows the answer. I understand json has more examples but I think they need to document the xml structure. All of their java api walkthroughs use xml... — Trying..., Oct 29 '13 at 16:31
Yep, AFAIK the "walkthrough" examples are the only place that you'll find examples of XML format with the REST API. Unfortunately the walkthroughs illustrate only the very basic scenarios, with minimal parameters (elements) used in the request. Totally agree that it'd be great for DocuSign to actually document full request/response structure for XML with REST. Good luck! — Kim Brandl, Oct 29 '13 at 16:53

score 2 · Accepted Answer · answered Oct 29 '13 at 16:57

Kim is right in that DocuSign currently does not have good documentation for XML formatted request bodies. However sometimes JSON is not an option due to technical limitations, you don't want to re-write parsing code, or other reasons, and developers are stuck with XML format.

With that said, here is the proper XML format for the eventNotifications object, along with all the possible properties you can set on it:

<eventNotification>
   <EnvelopeEvents>
      <envelopeEvent>
         <envelopeEventStatusCode>sample string 1</envelopeEventStatusCode>
         <includeDocuments>sample string 2</includeDocuments>
      </envelopeEvent>
      <envelopeEvent>
         <envelopeEventStatusCode>sample string 1</envelopeEventStatusCode>
         <includeDocuments>sample string 2</includeDocuments>
      </envelopeEvent>
   </EnvelopeEvents>
   <includeCertificateWithSoap>sample string 6</includeCertificateWithSoap>
   <includeDocuments>sample string 8</includeDocuments>
   <includeEnvelopeVoidReason>sample string 9</includeEnvelopeVoidReason>
   <includeSenderAccountAsCustomField>sample string 11</includeSenderAccountAsCustomField>
   <includeTimeZone>sample string 10</includeTimeZone>
   <loggingEnabled>sample string 2</loggingEnabled>
   <recipientEvents>
      <recipientEvent>
         <includeDocuments>sample string 2</includeDocuments>
         <recipientEventStatusCode>sample string 1</recipientEventStatusCode>
      </recipientEvent>
      <recipientEvent>
         <includeDocuments>sample string 2</includeDocuments>
         <recipientEventStatusCode>sample string 1</recipientEventStatusCode>
      </recipientEvent>
   </recipientEvents>
   <requireAcknowledgment>sample string 3</requireAcknowledgment>
   <signMessageWithX509Cert>sample string 7</signMessageWithX509Cert>
   <soapNameSpace>sample string 5</soapNameSpace>
   <url>sample string 1</url>
   <useSoapInterface>sample string 4</useSoapInterface>
</eventNotification>

Thanks, Ergin! Seems that the key to getting this to work is using the proper "case" for the EnvelopeEvents element -- i.e., capitalize both "Envelope" and "Events". If you use "envelopeEvents" instead (lowercase 'envelope' and uppercase 'Events'), it doesn't work. Not consistent with naming of DocuSign REST API elements in general (which tend to start with a lowercase letter), but nice to know that this is how it works. I'll update my prior response to include an XML request that successfully triggers the Connect notification. — Kim Brandl, Oct 29 '13 at 17:38

eventNotification XML structure

2 Answers2