DocuSign模板自定义字段无法通过API填充的技术求助

Hey, I’ve been in this exact situation before—template custom fields can be tricky because it’s easy to mix up the different field types and how the API expects them to be populated. Let’s break down the common issues and fix this step by step.

First, Clarify What Type of "Custom Field" You’re Working With #

DocuSign has two key field types that often get confused, and each requires a different API approach:

• Envelope-level Custom Fields: These are stored at the envelope level (not directly embedded in the document) — you create them in the template’s "Custom Fields" tab, then add a display tab to show their value on the template.
• Template Text Tabs: These are direct text input fields you drag onto the template (under the "Fields" tab). If you named one "Custom", this is a separate entity from an envelope custom field.

Case 1: You’re Using an Envelope-level Custom Field #

If you created the field in the template’s "Custom Fields" tab and added a display tab for it, your API request needs to set the value in the top-level customFields section of the envelope payload, not under template roles. Here’s a working JSON example:

{
  "templateId": "YOUR_TEMPLATE_GUID",
  "status": "sent",
  "templateRoles": [
    {
      "email": "signer@example.com",
      "name": "John Doe",
      "roleName": "Signer" // Match the exact role name from your template
    }
  ],
  "customFields": {
    "textCustomFields": [
      {
        "name": "Custom", // Exact case-sensitive name of your field
        "value": "Your desired field value",
        "show": true, // Ensures the value is visible in the envelope
        "required": false
      }
    ]
  }
}

Case 2: You’re Using a Template Text Tab (Dragged Directly onto the Template) #

If you actually dragged a text field (not an envelope custom field) onto the template and named it "Custom", you need to populate it under the tabs section of the template role. Here’s how that payload looks:

{
  "templateId": "YOUR_TEMPLATE_GUID",
  "status": "sent",
  "templateRoles": [
    {
      "email": "signer@example.com",
      "name": "John Doe",
      "roleName": "Signer",
      "tabs": {
        "textTabs": [
          {
            "tabLabel": "Custom", // Match the tab's label exactly (case-sensitive!)
            "value": "Your desired field value"
          }
        ]
      }
    }
  ]
}

Common Pitfalls to Double-Check #

• Case Sensitivity: DocuSign treats Custom and custom as completely different fields. Make sure the name in your JSON matches the exact name you set in the template.
• API Permissions: Ensure your integration key has the envelope_custom_fields_write scope (for envelope-level fields) or envelope_write/template_write for text tabs.
• Verify Your Request: Use DocuSign’s API Logs (under Admin > API Logs) to inspect the raw JSON you sent. Typos or missing sections are easy to miss until you see the actual request.
• Field Association: If using an envelope custom field, confirm the display tab in your template is linked to the correct field (check the tab’s settings to see if it references your "Custom" field).

内容的提问来源于stack exchange，提问作者Mauri1OA