3

I've created a test template within the DocuSign sandbox in preparation for some automation with another system. I'm trying to populate these custom fields as there will be dynamically entered data that will need to be included.

So far, I've had no trouble with authentication, or creating an "envelope" built off of the template, or assigning the roles. I can get the IDs of the templates, envelopes, documents no problem. However, none of my attempts to retrieve a list of the custom fields or populate them through the REST APIs have been successful.

I've made attempts to pull fields from the template, and from the envelope after applying the template. I've even manually set the values through the UI, but still got nothing. And the requests aren't failing. They're successful. There's just either empty respond data structures, or no update performed.

For example, when I attempt to retrieve the custom fields, this is what I get:

{
  "textCustomFields": [],
  "listCustomFields": []
}

This is despite having created custom fields through the UI and applying them to template and such. I also tried getting the document fields instead, but received essentially the same response:

{
  "documentFields": []
}

I can't help but think I'm missing something here and don't know what. I pull the base URL from the authentication response, and I've made calls to the following API URLs:

  • /envelopes/{1}/custom_fields
  • /envelopes/{1}/documents/{2}/fields
  • /envelopes/{1}/recipients/{2}/tabs
  • /templates/{1}/custom_fields
  • /templates/{1}/documents/{2}/fields

-- EDIT --

Ok, so following on suggestions from an answer below, I found that the fields are all actually "tabs", despite how they were actually referenced in the UI during creation of the template. Now the question remains why they are only returned for a single recipient role. Here's a screenshot of how the roles are on the envelope (email addresses are edited over):

DocuSign envelope roles

The tabs are not returned for "That Guy", even though that role is marked "Needs to Sign". They are returned for "Other Guy", even though that role is just meant to get copied. So, maybe it now looks like the problem has more to do with role definition than anything else. Or I have to go back review all this again because these fields in need of pre-population have to be set for all recipients and are not role-dependent. Everyone is meant to see the same thing.

Michael McCauley
  • 853
  • 1
  • 12
  • 37

1 Answers1

5

DocuSign uses the term "custom fields" in (at least) 3 different ways:

  • Envelope Custom Fields let you specify metadata that gets associated at the Envelope level. This data isn't visible to recipients; it's just extra metadata that you can associate with an Envelope and query later (via API). See here for more info.

  • Document Custom Fields let you specify metadata that gets associated at the Document level. This data isn't visible to recipients in any way; it's just extra metadata that you can associate with a specific Document and query later (via API). See here for more info.

  • Custom Fields (aka "custom tabs") let you create (and save) your own customized tabs for use in your documents -- see here and here for more info.

Based on the information you've provided in you're question, I'd guess that you're using the term "custom fields" to refer to the tabs you placed throughout the document(s) in the template, some of which you want to dynamically populate with data via API when the envelope gets created, and others that recipients will populate with data during signing. Is that correct?

If this is what you mean, you can get a list of tabs (fields) that a specific recipient owns by executing a List Envelope Tabs request, as described here.

GET /v2/accounts/{accountId}/envelopes/{envelopeId}/recipients/{recipientId}/tabs

To retrieve tabs for a template (rather than an envelope), use this same URI, but specify the Template ID value in place of {envelopeId}. Also, note that the value that you specify for {recipientId} should identify the recipient who "owns" the tabs in the template/envelope. (Each tab in a template/envelope is "owned" by a specific recipient.)

If I've misunderstood your issue (or what you mean by "custom fields"), please comment on this answer and I'll attempt to clarify further.

Kim Brandl
  • 13,125
  • 2
  • 16
  • 21
  • From what you've said here, actually, I don't think I've added any tabs, and maybe what I did add was just metadata containers. I'll have to poke at the template a little more and create a new envelope to test. It would be nice if their documentation made this a little more clear. But even so, whether or not fields were populating via REST, I'm still not certain why the API calls aren't returning any of the fields. – Michael McCauley Feb 21 '17 at 15:54
  • Ok, so even though a couple fields were created in the UI as "custom fields", everything apparently was a "tab", but only show up for a single recipient. I never thought to check tabs for that recipient because of the two roles defined, that one isn't a signer. I'm going to make an edit to my post, hopefully that will help. – Michael McCauley Feb 21 '17 at 16:32
  • If you execute a "List Envelope Tabs" request (using the URI I posted above), and specify the recipientId corresponding to the Recipient who was assigned the tabs in the template/envelope, you should see the tabs returned in the response. Note - you can see the recipients (and each one's Id) by executing a "Get Recipients" request: GET /v2/accounts/{accountId}/envelopes/{envelope-or-template-Id}/recipients. That response contains a couple of different recipient-id-related properties -- you'll want to use the value of "recipientIdGuid" in the "List Envelope Tabs" request. – Kim Brandl Feb 21 '17 at 16:43
  • Well, now certain things are making sense. During the envelope creation call, I was assigning the signer as recipientId 1, and the cc as recipientId 2, but the system itself was giving them their own recipientId values and I didn't catch it. So now I understand why I received tabs back for what I thought was the cc recipient. So now would I be correct in thinking that in order to set "tabs" that need to be pre-populated for all signers, once the roles are assigned I would need to pull all recipient info per this API, then loop through the signers to push a tab update back to the envelope? – Michael McCauley Feb 21 '17 at 17:20
  • part 1 of 2: If you add a "text tab" (i.e., textbox) to a document in the Envelope, and assign it to the first recipient of the envelope. The first recipient will see that field as a textbox (containing the value you specified when creating the envelope, if any -- otherwise empty). Then, after they complete/submit the envelope, let's assume it goes to the second recipient in the routing order. That recipient would not see the textbox on the document -- but they *will* see the value that was specified in that field when the first recipient submitted the envelope. – Kim Brandl Feb 21 '17 at 18:16
  • part 2 of 2: The second recipient (and any other subsequent recipients) will see the value as plain text within the document. So, when creating the envelope via API -- assign each tab to the recipient who you want to be responsible for populating it, and pre-populate tab(s) as you desire. Then, any value(s) that exist in tab(s) when a recipient submits their envelope will appear as plain text in the doc from that point forward (to all future recipients, and once the envelope is completed as well). Give it a try in your Demo account (developer sandbox), and you'll see this in action. – Kim Brandl Feb 21 '17 at 18:17
  • One more thing -- if you have a field (tab) that you want any/all recipients to see as a field and be able to populate when viewing their envelope, DocuSign does support this functionality. I believe you simply set the "shared" property to "true" for a tab to enable any/all recipients to populate it. – Kim Brandl Feb 21 '17 at 18:35
  • I have seen this in my testing, to a point. But the deal is that I'm wanting to have data added to what's being sent out before it even gets sent out. As in there will be information taken from, say, a quote. In my scenario I doubt there will be more than one or two signers, but there will be people CC'd, and information needs to be added before being sent to the signers. All I've managed to so so far is add badly formatted tabs laid on top of each other in the corner instead of populating existing tabs. – Michael McCauley Feb 21 '17 at 20:23
  • Rather than continuing this conversation via comments, can you please post a new question. Seems like we've resolved your initial problem (i.e., identified that you should have been querying "tabs", not "custom fields", and figured out that you weren't seeing any tabs returned because of specifying an invalid recipient Id). If that's the case, can you please upvote and/or mark the answer as accepted (so that others can benefit from the info in the future)? Then, if you can ask a new question about how to prepoplate tabs, I'm sure you'll get feedback to that one. – Kim Brandl Feb 22 '17 at 14:36