-->

Using DocuSign REST APIs to Get/Set Template Field

2019-03-01 11:03发布

问题:

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):

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.

回答1:

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.