Custom Document Fields

Question

I'm using the dev account and the demo.docusign.net site to test out the API. I want to create a template with a document that has custom data fields. I created a template and on the page where you drag fields on to the document, I created a custom field. I called it "Last Name". I saved the custom field and saved the template. Now I want to create a new document for signing through the API and populate that field. Using the Walkthroughs as a guide, I was able to create a new draft envelope from a template. I then wanted to populate the custom field with data. However, this is failing. I'm getting the following error:

{ "errorCode": "INVALID_REQUEST_BODY", "message": "The request body is missing or improperly formatted." }'

Below is my code based off the Walkthroughs. In addition to having a custom field attached at design time, I wanted to test dynamically adding a new custom field and modifying it as well. So, first I make a POST request to add a new field and set it using the Recipients/Tabs API. Then I make a GET request to get the Tabs for the recipient so I can capture the Tag ID. Then I make a PUT request to modify the field and that's where I get the error message. But the request body looks fine to me and it contains the only required field for TagId. I assume the only other needed field is one to set the value. The same request body works fine for the POST request. I just copied it and changed the fields. The POST works fine and I can validate the added field by opening it in the Console. The new field is there. It's just the PUT to modify that isn't working.

/////////////////////////////////////////////////////////////////////////////////////////////////
// STEP 1 - Add New Tab
/////////////////////////////////////////////////////////////////////////////////////////////////                                                                                  
$curl = curl_init($baseUrl . "/envelopes/" . $envelopeId . "/recipients/1/tabs" );
$data = array (
  'textTabs' => 
  array (
    0 => 
    array (
      'documentId' => '1',
      'pageNumber' => '1',
      'tabLabel' => 'test tab',
      'value' => 'test',
    ),
  ),
);

$data_string = json_encode($data);  


curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);                                                                  
curl_setopt($curl, CURLOPT_HTTPHEADER, array(                                                                          
    'Content-Type: application/json',                                                                                
    'Content-Length: ' . strlen($data_string),
    "X-DocuSign-Authentication: $header" )                                                                       
);

$json_response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
if ( $status != 201 ) {
    echo "error calling webservice, status is:" . $status;

    exit(-1);
}

$response = json_decode($json_response, true);
curl_close($curl);

//--- display results



/////////////////////////////////////////////////////////////////////////////////////////////////
// STEP 2 - Get recipient tab information
/////////////////////////////////////////////////////////////////////////////////////////////////                                                                                  
$curl = curl_init($baseUrl . "/envelopes/" . $envelopeId . "/recipients/1/tabs" );
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array(                                                                          
    "X-DocuSign-Authentication: $header" )                                                                       
);

$json_response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
if ( $status != 200 ) {
    echo "error calling webservice, status is:" . $status;

    exit(-1);
}

$response = json_decode($json_response, true);
curl_close($curl);

$lastNameTabID = $response['textTabs'][0]['tabId'];
$testTabID = $response['textTabs'][1]['tabId'];
//--- display results

/////////////////////////////////////////////////////////////////////////////////////////////////
// STEP 3 - update tab value
/////////////////////////////////////////////////////////////////////////////////////////////////                                                                                  
$curl = curl_init($baseUrl . "/envelopes/" . $envelopeId . "/recipients/1/tabs" );
$data = array (
  'textTabs' => 
  array (
    0 => 
    array (
      'tabId' => $testTabID,
      'value' => 'Some Value',
    ),
  ),
);

$data_string = json_encode($data);  


curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_PUT, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);                                                                  
curl_setopt($curl, CURLOPT_HTTPHEADER, array(                                                                          
    'Content-Type: application/json',                                                                                
    'Content-Length: ' . strlen($data_string),
    "X-DocuSign-Authentication: $header" )                                                                       
);

$json_response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
if ( $status != 201 ) {
    echo "error calling webservice, status is:" . $status;

    exit(-1);
}

$response = json_decode($json_response, true);
curl_close($curl);

And here is the output of the Request Body

data_string= '{"textTabs":[{"tabId":"627883d0-542c-40c7-a58c-ce68d9e057e1","value":"Some Value"}]}'

I appreciate some guidance.

Thanks Joe

Answer 1

Alright, so I did a little digging and think I have what we need here. First, to get the Recipient ID as well as associated Tab ID's for the envelope, use the following GET: v2/accounts/:accountId/envelopes/:envelopeId/recipients. This will give you what you need to edit existing tags. Once you have the info here, you can use the PUT v2/accounts/:accountId/envelopes/:envelopeId/recipients/:recipientId/tabs to edit the tabs you're looking to edit. Here is a sample JSON request I sent using Postman to successfully update a text tabs value.

{
  "textTabs": [
    {
      "tabId": "c75d32c4-8024-48c0-975a-acc232b20212",
      "value": "ABC Corp",
    }
  ]
}

To add tabs to that recipient, use the same URL as the edit, but use a POST.

Answer 2

I think this is easier than we think. You should be able to define the additional tag in the post to create the envelope. Below is part of my json to define a template role and text tabs. The first one is a field defined in the Template labeled "Company". The second one is a data field I'm adding on the fly and placing on the 3rd page with XY coordinates. You can also place this using anchor text.

"templateRoles": [
{
  "tabs": {
    "textTabs": [
      {
        "tabLabel": "Company",
        "value": "Acme Inc"
      },
      {
        "tabLabel": "business",
        "value": "widgets",
        "pageNumber": "3",
        "documentId": "1",
        "yPosition": "300",
        "xPosition": "300",
        "locked": false
      }
    ]
  },
  "roleName": "Customer",
  "name": "Customer Bob",
  "email": "signerrob@outlook.com"
}

],