How to pre-fill custom fields when creating an envelope?

Question

My business process is like this: I have one template with one document. The document must have several fields that must be filled in differently for each signatory. For example: fields "company_name", "signer_name", etc. I assume that when creating an envelope, the fields must be pre-filled for each signer: Signer 1 should receive values for the fields: "Alice's company", "Alice", Signer 2 should receive values for the fields: "Bob's company", "Bob".

To do that, I make POST request to endpoint:

/restapi/v2.1/accounts/{accountId}/envelopes

Body:

{
  "emailSubject": "Email Subject",
  "templateId": "my-template-id",
  "status": "sent",
  "customFields": {
    "textCustomFields": [
      {
        "fieldId": "10851848897",
        "name": "company_name",
        "required": "true",
        "show": "true",
        "value": "Alice's company"
      },
      {
        "fieldId": "10851848898",
        "name": "signer_name",
        "required": "true",
        "show": "true",
        "value": "Alice"
      }
    ]
  },
  "templateRoles": [
    {
      "email": "alice@maildomain.com",
      "emailNotification": {
        "emailBody": "email body",
        "emailSubject": "email subject",
        "supportedLanguage": "en"
      },
      "roleName": "signer",
      "routingOrder": "1"
    }
  ]
}

Alice recieve link to sign the document without pre-filled fields.

Also, GET request to list document's fields

/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/documents/{documentId}/fields

gives no fields:

{
    "documentFields": []
}

Answer 1

Envelope Custom fields can be obtained by a different endpoint:

/restapi/v2.1/accounts/${account_id}/envelopes/${envelope_id}/custom_fields

Now, I assume you actually want something else, which is to show values to the recipients on the envelope.

That is done by actually adding tabs and settings their values like this: (giving you here a complete example with various different tabs)

ENVELOPE

   {
        "customFields": {
            "textCustomFields": [{
                "name": "salary",
                "required": "false",
                "show": "true",
                "value": "123000"
            }]
        },
        "documents": [
          {
            "documentBase64": "' > $request_data
              cat $doc1_base64 >> $request_data
              printf '",
            "documentId": "1",
            "fileExtension": "docx",
            "name": "Lorem Ipsum"
         }
        ],
        "emailBlurb": "Sample text for email body",
        "emailSubject": "Please Sign",
        "envelopeIdStamping": "true",
        "recipients": {
            "signers": [{
                "clientUserId": "1000",
                "email": "{USER_EMAIL}",
                "name": "{USER_NAME}",
                "recipientId": "1",
                "routingOrder": "1",
                "tabs": {
                    "signHereTabs": [{
                        "anchorString": "/sn1/",
                        "anchorUnits": "pixels",
                        "anchorXOffset": "20",
                        "anchorYOffset": "10"
                    }],
                    "textTabs": [{
                        "anchorString": "/legal/",
                        "anchorUnits": "pixels",
                        "anchorXOffset": "5",
                        "anchorYOffset": "-9",
                        "bold": "true",
                        "font": "helvetica",
                        "fontSize": "size11",
                        "locked": "false",
                        "tabId": "legal_name",
                        "tabLabel": "Legal name",
                        "value": "{USER_NAME}"
                    }, {
                        "anchorString": "/familiar/",
                        "anchorUnits": "pixels",
                        "anchorXOffset": "5",
                        "anchorYOffset": "-9",
                        "bold": "true",
                        "font": "helvetica",
                        "fontSize": "size11",
                        "locked": "false",
                        "tabId": "familiar_name",
                        "tabLabel": "Familiar name",
                        "value": "{USER_NAME}"
                    }, {
                        "anchorString": "/salary/",
                        "anchorUnits": "pixels",
                        "anchorXOffset": "5",
                        "anchorYOffset": "-9",
                        "bold": "true",
                        "font": "helvetica",
                        "fontSize": "size11",
                        "locked": "true",
                        "tabId": "salary",
                        "tabLabel": "Salary",
                        "value": "$123,000.00"
                    }]
                }
            }]
        },
        "status": "Sent"
    }

TEMPLATE

{
        "customFields": {
            "textCustomFields": [{
                "name": "app metadata item",
                "required": "false",
                "show": "true",
                "value": "1234567"
            }]
        },
        "status": "Sent",
        "templateId": "'"${template_id}"'",
        "templateRoles": [{
            "clientUserId": "1000",
            "email": "'"${SIGNER_EMAIL}"'",
            "name": "'"${SIGNER_NAME}"'",
            "roleName": "signer",
            "tabs": {
                "checkboxTabs": [{
                    "selected": "true",
                    "tabLabel": "ckAuthorization"
                }, {
                    "selected": "true",
                    "tabLabel": "ckAgreement"
                }],
                "listTabs": [{
                    "documentId": "1",
                    "pageNumber": "1",
                    "tabLabel": "list",
                    "value": "green"
                }],
                "radioGroupTabs": [{
                    "groupName": "radio1",
                    "radios": [{
                        "selected": "true",
                        "value": "white"
                    }]
                }],
                "textTabs": [{
                    "tabLabel": "text",
                    "value": "Jabberwocky!"
                }, {
                    "bold": "true",
                    "documentId": "1",
                    "font": "helvetica",
                    "fontSize": "size14",
                    "height": "23",
                    "locked": "false",
                    "pageNumber": "1",
                    "required": "false",
                    "tabId": "name",
                    "tabLabel": "added text field",
                    "value": "'"${SIGNER_NAME}"'",
                    "width": "84",
                    "xPosition": "280",
                    "yPosition": "172"
                }]
            }
        }, {
            "email": "'"${CC_EMAIL}"'",
            "name": "'"${CC_NAME}"'",
            "roleName": "cc"
        }]
    }