Custom template fields with docusign_rest

Question

I'm using the docusign rest gem to create and send DocuSign envelopes. But I'm having problems having custom fields I have set on my template to show up. I have 2 signers on my template, that have common fields to both of them so I had to set up each custom field twice since DocuSign doesn't allow for shared fields it seems.

This is the API call I'm doing when setting up my envelope, as per the DocuSign API docs:

custom_fields = {
      textCustomFields: [
        {
          name: "host_address",
          value: "Testing Host Address",
          required: "true",
          show: "true",
        },
        {
          name: "host_civil_status",
          value: "Host Civil Status",
          required: "true",
          show: "true",
        },
        {
          name: "host_id_number",
          value: "123HOSTID",
          required: "true",
          show: "true",
        },
        {
          name: "host_tax_number",
          value: "123HOSTTAX",
          required: "true",
          show: "true",
        },
        {
          name: "nomad_address",
          value: "Testing Nomad Address",
          required: "true",
          show: "true",
        },
        {
          name: "nomad_civil_status",
          value: "Nomad Civil Status",
          required: "true",
          show: "true",
        },
        {
          name: "nomad_id_number",
          value: "123NOMADID",
          required: "true",
          show: "true",
        },
        {
          name: "nomad_tax_number",
          value: "123NOMADTAX",
          required: "true",
          show: "true",
        },
        {
          name: "property_addres",
          value: booking.listing.property.full_address,
          required: "true",
          show: "true",
        },
        {
          name: "property_address",
          value: booking.listing.property.full_address,
          required: "true",
          show: "true",
        },
        {
          name: "property_deposit",
          value: (booking.deposit * booking.price).to_s,
          required: "true",
          show: "true",
        },
        {
          name: "property_description",
          value: "Property Description",
          required: "true",
          show: "true",
        },
        {
          name: "property_start_date",
          value: booking.start_date.strftime("%d/%m/%Y"),
          required: "true",
          show: "true",
        },
        {
          name: "property_end_date",
          value: booking.end_date.strftime("%d/%m/%Y"),
          required: "true",
          show: "true",
        },
        {
          name: "property_stay_length",
          value: distance_of_time_in_words(booking.start_date, booking.end_date),
          required: "true",
          show: "true",
        },
        {
          name: "property_montly_rent",
          value: booking.price.to_s,
          required: "true",
          show: "true",
        },
      ]

    }
    @envelope = client.create_envelope_from_template(
      status: 'sent',
      email: {
        subject: "The test email subject envelope",
        body: "Envelope body content here"
      },
      template_id: "77xxxxxxxxxxxxxxxxxxxxxxxxxx",
      signers: [
        {
          embedded: true,
          name: booking.listing.user.name,
          email: booking.listing.user.email,
          role_name: 'Host',
        },
        {
          embedded: true,
          name: booking.user.name,
          email: booking.user.email,
          role_name: 'Nomad',
        }
      ],
      custom_fields: custom_fields
    )

Answer 1

Unfortunately, there are two different objects in the DocuSign system that essentially have the same name of "custom field." You're using the wrong one.

The two objects are:

1. Metadata custom data fields

These objects come in two flavors: textCustomFields and listCustomFields.

These objects can be set at the account level to require that every every (or some) envelopes sent include additional metadata at the envelope level.

The objects can also be set at the envelope level programmatically.

These "custom fields" are not visible to the signer. They are not fields (tabs) visible on the documents. They are associated with the envelope as additional metadata. These are the type of custom fields that your code example is using.

Adding/listing the custom fields set at the account level: docs.

Adding a custom metadata field to an envelope: use the customFields attribute of the envelope definition.

2. Customized tabs (fields)

A customized tab (called a 'field' in the DocuSign web tool) is a version of a DocuSign tab (text tab, sign here tab, date tab, etc) that has been customized. Then, later, instead of re-customizing another instance of the tab, the customized tab can be re-used.

This is what you want to use.

To use the API to list them, update them, etc: docs.

To use them in a document

Disclaimer: I'm reading the docs, I have not tried this. Please add a comment after you try it:

1. You will need the customTabId for the customized tab. Use the CustomTabs::list API call.
2. You also need to know the base tab type: Text, etc. Use the type value which is also returned by the CustomTabs::list API call.
3. Then, when creating your document, for each recipient who gets a customized, tab, create the tab as usual, but include the customTabId as part of the tab's definition. Eg, see the text tab object definition in Envelopes::create API call.