Back to Docusign.com
SCENARIO
When calling:
PUT {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes/{{envelopeId}}/docGenFormFields
With the following payload:
"docGenFormFields": [
{
"docGenFormFieldList": [
{
"value": "2024 Carbon",
"name": "Z1TKH6C",
"required": "true"
}
],
"documentId": "1"
}
]
}
Returns the following error response body:
{
"errorCode": "INVALID_REQUEST_PARAMETER",
"message": "The request contained at least one invalid parameter. Value for 'documentId' is invalid."
}
The endpoint is NOT honoring the standard value of 1, which has been the normal approach for other DocuSign REST endpoints.
RESEARCH
A DocuSign Blog and documentation states to call the GET endpoint first and map the documentId and other properties to the request payload. Our application currently uses Redis cache to store all Tab information and JSON PATCH value mappers, therefore this GET operation is overly 'expensive'. Going into DocuSign/ Envelopes/ Drafts, I can see that the template I added is indeed document '1'. The preview URL endpoint shows '1' as a path parameter to documents resource.
Indeed, calling the GET returns the documentId as a guid.
{
"docGenFormFields": [
{
"documentId": "2fc8e042-1dac-478b-91a4-1a4babbff427",
"docGenFormFieldList": [
{
"label": "ProgramName",
"type": "TextBox",
"required": "True",
"name": "Z1TKH6C",
"description": "The name of a Truterra Program"
}
],
"docGenDocumentStatus": "created"
}
]
}
Using the PUT endpoint with the following payload:
{
"docGenFormFields": [
{
"docGenFormFieldList": [
{
"value": "2024 Carbon",
"name": "Z1TKH6C",
"required": "true"
}
],
"documentId": "2fc8e042-1dac-478b-91a4-1a4babbff427"
}
]
}
Shows a successful response body:
{
"docGenFormFields": [
{
"documentId": "96b16603-9402-460a-b7f5-a4cffabcebb7",
"docGenFormFieldList": [
{
"required": "True",
"name": "Z1TKH6C",
"value": "2024 Carbon"
}
],
"docGenDocumentStatus": "mergesucceeded"
}
]
}
Oddly, a new guid is generated -- would not have expected that either. Perhaps DocuSign creates a new document, vs an actual PUT to update the existing.
SUMMARY
This endpoint does NOT follow other endpoint design patterns and should be fixed.
In the spirit of REST, the full endpoint should be:PUT {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes/{{envelopeId}}/documents/{documentId}/docGenFormFields
specifically:PUT {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes/{{envelopeId}}/documents/1/docGenFormFields
for a single document.
I am sure this 'works as designed', but it is not consistent to other endpoints, aka it SHOULD NOT have passed internal design reviews. Perhaps this is due to another product team within DocuSign and there isn’t an overall governance approach.
