I must use EnvelopeAPI.listStatusChanges() to poll signed envelopes. It provides an object EnvelopeInfo, containig a List.
For each Envelupe I would like to retrive the signed documents' body, but the Envelope.getEnvelopeDocuments() just return null.
ListStatusChangesOptions opt = api.new ListStatusChangesOptions();
opt.setFromDate(DateTimeFormatter.ISO_LOCAL_DATE_TIME.format(lastPoll.minusDays(1)));
EnvelopesInformation info = api.listStatusChanges(authService.getAccountId(),opt);
List<Envelope> envList = info.getEnvelopes();
assert (envList != null);
for (Envelope env : envList) {
String envId = env.getEnvelopeId());
String status = env.getStatus();
LocalDateTime changeTime = LocalDateTime.from(
DateTimeFormatter.ISO_DATE_TIME
.parse(env.getStatusChangedDateTime()));
System.out.format("%s: Changed status of \"%s\" in %s\n",
changeTime.toString(), envId(),status());
if (status.equals("completed")) {
List<EnvelopeDocument> documents = env.getEnvelopeDocuments();
assert(documents != null);
}
}
In the example, the last assert on documents always fails. What am I doing wrong?
The only relevat log I got is:
TraceToken: de41cfce-8a4d-4ef4-9a5f-a47659fa16fd
Timestamp: 2021-11-09T10:17:19.5448174Z
GET https://demo.docusign.net:7801/restapi/v2.1/accounts/<xxx>/envelopes?from_date=2021-11-08T11%3A14%3A13.8906278
Content-Length: 0
Connection: keep-alive
Accept: application/json
Authorization: Bearer [omitted]
Host: demo.docusign.net
User-Agent: Swagger-Codegen/3.15.0/java
X-DocuSign-SDK: Java
X-SecurityProtocol-Version: TLSv1.2
X-SecurityProtocol-CipherSuite: ECDHE-RSA-AES256-GCM-SHA384
x-forwarded-for: 93.34.235.164
200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 9671
X-DocuSign-TraceToken: de41cfce-8a4d-4ef4-9a5f-a47659fa16fd
{
"resultSetSize": "6",
"startPosition": "0",
"endPosition": "5",
"totalSetSize": "6",
"nextUri": "",
"previousUri": "",
"envelopes": [
{
"status": "completed",
"documentsUri": "/envelopes/fe3b2d69-1671-49cb-9af9-4186f0777ae2/documents",
"recipientsUri": "/envelopes/fe3b2d69-1671-49cb-9af9-4186f0777ae2/recipients",
"attachmentsUri": "/envelopes/fe3b2d69-1671-49cb-9af9-4186f0777ae2/attachments",
"envelopeUri": "/envelopes/fe3b2d69-1671-49cb-9af9-4186f0777ae2",
"emailSubject": "Documents to sign",
"envelopeId": "fe3b2d69-1671-49cb-9af9-4186f0777ae2",
"signingLocation": "online",
"customFieldsUri": "/envelopes/fe3b2d69-1671-49cb-9af9-4186f0777ae2/custom_fields",
"notificationUri": "/envelopes/fe3b2d69-1671-49cb-9af9-4186f0777ae2/notification",
"allowMarkup": "false",
"createdDateTime": "2021-11-08T11:28:58.4730000Z",
"lastModifiedDateTime": "2021-11-08T11:28:58.4730000Z",
"deliveredDateTime": "2021-11-08T11:29:17.5000000Z",
"sentDateTime": "2021-11-08T11:28:59.0500000Z",
"completedDateTime": "2021-11-08T11:29:54.1470000Z",
"statusChangedDateTime": "2021-11-08T11:29:54.1470000Z",
"documentsCombinedUri": "/envelopes/fe3b2d69-1671-49cb-9af9-4186f0777ae2/documents/combined",
"certificateUri": "/envelopes/fe3b2d69-1671-49cb-9af9-4186f0777ae2/documents/certificate",
"templatesUri": "/envelopes/fe3b2d69-1671-49cb-9af9-4186f0777ae2/templates",
"expireEnabled": "true",
"expireAfter": "120",
"sender": {
"userName": "Michele Bert",
"userId": "xxx",
"accountId": "xxx",
"email": "michele.bert#xxx.it"
},
"purgeState": "unpurged",
"envelopeIdStamping": "false",
"autoNavigation": "true",
"isSignatureProviderEnvelope": "false",
"anySigner": null,
"envelopeLocation": "not_specified"
},
{
"status": "sent",
"documentsUri": "/envelopes/fb263fbd-6842-48fa-9665-03df9af2accb/documents",
"recipientsUri": "/envelopes/fb263fbd-6842-48fa-9665-03df9af2accb/recipients",
"attachmentsUri": "/envelopes/fb263fbd-6842-48fa-9665-03df9af2accb/attachments",
"envelopeUri": "/envelopes/fb263fbd-6842-48fa-9665-03df9af2accb",
"emailSubject": "Sottoscrizione Mario Rossi",
"emailBlurb": "Buongiorno,\ncome da accordi sono a inviarti la proposta di investimento da sottoscrivere.\nTi ricordo che la proposta ha una validità di 48 ore dalla data di consegna.\n\nCordiali saluti\n",
"envelopeId": "fb263fbd-6842-48fa-9665-03df9af2accb",
"signingLocation": "online",
"customFieldsUri": "/envelopes/fb263fbd-6842-48fa-9665-03df9af2accb/custom_fields",
"notificationUri": "/envelopes/fb263fbd-6842-48fa-9665-03df9af2accb/notification",
"allowMarkup": "false",
"createdDateTime": "2021-11-09T07:15:48.6970000Z",
"lastModifiedDateTime": "2021-11-09T07:17:00.6830000Z",
"sentDateTime": "2021-11-09T07:17:01.4670000Z",
"statusChangedDateTime": "2021-11-09T07:17:01.4670000Z",
"documentsCombinedUri": "/envelopes/fb263fbd-6842-48fa-9665-03df9af2accb/documents/combined",
"certificateUri": "/envelopes/fb263fbd-6842-48fa-9665-03df9af2accb/documents/certificate",
"templatesUri": "/envelopes/fb263fbd-6842-48fa-9665-03df9af2accb/templates",
"expireEnabled": "true",
"expireAfter": "2",
"sender": {
"userName": "Andrea Debortoli",
"userId": "xxx",
"accountId": "xxx",
"email": "andrea.debortoli#xxx.it"
},
"purgeState": "unpurged",
"envelopeIdStamping": "true",
"autoNavigation": "true",
"isSignatureProviderEnvelope": "false",
"anySigner": null,
"envelopeLocation": "not_specified"
},
{
"status": "completed",
"documentsUri": "/envelopes/3d7130d7-b5bb-4579-9c25-f525c22064e7/documents",
"recipientsUri": "/envelopes/3d7130d7-b5bb-4579-9c25-f525c22064e7/recipients",
"attachmentsUri": "/envelopes/3d7130d7-b5bb-4579-9c25-f525c22064e7/attachments",
"envelopeUri": "/envelopes/3d7130d7-b5bb-4579-9c25-f525c22064e7",
"emailSubject": "Documents to sign",
"envelopeId": "3d7130d7-b5bb-4579-9c25-f525c22064e7",
"signingLocation": "online",
"customFieldsUri": "/envelopes/3d7130d7-b5bb-4579-9c25-f525c22064e7/custom_fields",
"notificationUri": "/envelopes/3d7130d7-b5bb-4579-9c25-f525c22064e7/notification",
"allowMarkup": "false",
"createdDateTime": "2021-11-09T09:28:23.3930000Z",
"lastModifiedDateTime": "2021-11-09T09:28:23.3930000Z",
"deliveredDateTime": "2021-11-09T09:28:43.6400000Z",
"sentDateTime": "2021-11-09T09:28:23.9730000Z",
"completedDateTime": "2021-11-09T09:29:24.9800000Z",
"statusChangedDateTime": "2021-11-09T09:29:24.9800000Z",
"documentsCombinedUri": "/envelopes/3d7130d7-b5bb-4579-9c25-f525c22064e7/documents/combined",
"certificateUri": "/envelopes/3d7130d7-b5bb-4579-9c25-f525c22064e7/documents/certificate",
"templatesUri": "/envelopes/3d7130d7-b5bb-4579-9c25-f525c22064e7/templates",
"expireEnabled": "true",
"expireAfter": "120",
"sender": {
"userName": "Michele Bert",
"userId": "xxx",
"accountId": "xxx",
"email": "michele.bert#xxx.it"
},
"purgeState": "unpurged",
"envelopeIdStamping": "false",
"autoNavigation": "true",
"isSignatureProviderEnvelope": "false",
"anySigner": null,
"envelopeLocation": "not_specified"
},
{
"status": "completed",
"documentsUri": "/envelopes/99f3a387-f8e8-4763-9b50-3c2e49fc536a/documents",
"recipientsUri": "/envelopes/99f3a387-f8e8-4763-9b50-3c2e49fc536a/recipients",
"attachmentsUri": "/envelopes/99f3a387-f8e8-4763-9b50-3c2e49fc536a/attachments",
"envelopeUri": "/envelopes/99f3a387-f8e8-4763-9b50-3c2e49fc536a",
"emailSubject": "Documents to sign",
"envelopeId": "99f3a387-f8e8-4763-9b50-3c2e49fc536a",
"signingLocation": "online",
"customFieldsUri": "/envelopes/99f3a387-f8e8-4763-9b50-3c2e49fc536a/custom_fields",
"notificationUri": "/envelopes/99f3a387-f8e8-4763-9b50-3c2e49fc536a/notification",
"allowMarkup": "false",
"createdDateTime": "2021-11-09T09:45:09.1130000Z",
"lastModifiedDateTime": "2021-11-09T09:45:09.1130000Z",
"deliveredDateTime": "2021-11-09T09:45:26.5430000Z",
"sentDateTime": "2021-11-09T09:45:10.0370000Z",
"completedDateTime": "2021-11-09T09:45:53.7670000Z",
"statusChangedDateTime": "2021-11-09T09:45:53.7670000Z",
"documentsCombinedUri": "/envelopes/99f3a387-f8e8-4763-9b50-3c2e49fc536a/documents/combined",
"certificateUri": "/envelopes/99f3a387-f8e8-4763-9b50-3c2e49fc536a/documents/certificate",
"templatesUri": "/envelopes/99f3a387-f8e8-4763-9b50-3c2e49fc536a/templates",
"expireEnabled": "true",
"expireAfter": "120",
"sender": {
"userName": "Michele Bert",
"userId": "xxx",
"accountId": "xxx",
"email": "michele.bert#xxx.it"
},
"purgeState": "unpurged",
"envelopeIdStamping": "false",
"autoNavigation": "true",
"isSignatureProviderEnvelope": "false",
"anySigner": null,
"envelopeLocation": "not_specified"
},
{
"status": "completed",
"documentsUri": "/envelopes/864d7b45-e5a2-4188-a5c3-52693a2909c4/documents",
"recipientsUri": "/envelopes/864d7b45-e5a2-4188-a5c3-52693a2909c4/recipients",
"attachmentsUri": "/envelopes/864d7b45-e5a2-4188-a5c3-52693a2909c4/attachments",
"envelopeUri": "/envelopes/864d7b45-e5a2-4188-a5c3-52693a2909c4",
"emailSubject": "Documents to sign",
"envelopeId": "864d7b45-e5a2-4188-a5c3-52693a2909c4",
"signingLocation": "online",
"customFieldsUri": "/envelopes/864d7b45-e5a2-4188-a5c3-52693a2909c4/custom_fields",
"notificationUri": "/envelopes/864d7b45-e5a2-4188-a5c3-52693a2909c4/notification",
"allowMarkup": "false",
"createdDateTime": "2021-11-09T09:58:49.7900000Z",
"lastModifiedDateTime": "2021-11-09T09:58:49.7900000Z",
"deliveredDateTime": "2021-11-09T09:59:06.0800000Z",
"sentDateTime": "2021-11-09T09:58:50.4330000Z",
"completedDateTime": "2021-11-09T09:59:37.2700000Z",
"statusChangedDateTime": "2021-11-09T09:59:37.2700000Z",
"documentsCombinedUri": "/envelopes/864d7b45-e5a2-4188-a5c3-52693a2909c4/documents/combined",
"certificateUri": "/envelopes/864d7b45-e5a2-4188-a5c3-52693a2909c4/documents/certificate",
"templatesUri": "/envelopes/864d7b45-e5a2-4188-a5c3-52693a2909c4/templates",
"expireEnabled": "true",
"expireAfter": "120",
"sender": {
"userName": "Michele Bert",
"userId": "xxx",
"accountId": "xxx",
"email": "michele.bert#xxx.it"
},
"purgeState": "unpurged",
"envelopeIdStamping": "false",
"autoNavigation": "true",
"isSignatureProviderEnvelope": "false",
"anySigner": null,
"envelopeLocation": "not_specified"
},
{
"status": "completed",
"documentsUri": "/envelopes/f01ef821-b29c-4747-804d-b379644b9bce/documents",
"recipientsUri": "/envelopes/f01ef821-b29c-4747-804d-b379644b9bce/recipients",
"attachmentsUri": "/envelopes/f01ef821-b29c-4747-804d-b379644b9bce/attachments",
"envelopeUri": "/envelopes/f01ef821-b29c-4747-804d-b379644b9bce",
"emailSubject": "Documents to sign",
"envelopeId": "f01ef821-b29c-4747-804d-b379644b9bce",
"signingLocation": "online",
"customFieldsUri": "/envelopes/f01ef821-b29c-4747-804d-b379644b9bce/custom_fields",
"notificationUri": "/envelopes/f01ef821-b29c-4747-804d-b379644b9bce/notification",
"allowMarkup": "false",
"createdDateTime": "2021-11-09T10:14:16.2630000Z",
"lastModifiedDateTime": "2021-11-09T10:14:16.2800000Z",
"deliveredDateTime": "2021-11-09T10:14:36.8400000Z",
"sentDateTime": "2021-11-09T10:14:17.5300000Z",
"completedDateTime": "2021-11-09T10:15:11.1630000Z",
"statusChangedDateTime": "2021-11-09T10:15:11.1630000Z",
"documentsCombinedUri": "/envelopes/f01ef821-b29c-4747-804d-b379644b9bce/documents/combined",
"certificateUri": "/envelopes/f01ef821-b29c-4747-804d-b379644b9bce/documents/certificate",
"templatesUri": "/envelopes/f01ef821-b29c-4747-804d-b379644b9bce/templates",
"expireEnabled": "true",
"expireAfter": "120",
"sender": {
"userName": "Michele Bert",
"userId": "xxx",
"accountId": "xxx",
"email": "michele.bert#xxx.it"
},
"purgeState": "unpurged",
"envelopeIdStamping": "false",
"autoNavigation": "true",
"isSignatureProviderEnvelope": "false",
"anySigner": null,
"envelopeLocation": "not_specified"
}
]
}
The call to Envelope.getEnvelopeDocuments() does not seem to end up in any REST calls. I expected it to request the document list at the URI contained in Envelope.documentsUri field. Am I wrong?
In order for the documents info to be retrieved, the request property include must contain "documents", as stated at [1]. From the java SDK point of view, it correspond to call
listStatusChangesOptions.setInclude("documents,...");
Where the ... states for any other detail type you need to retrieve (in my case, for example, I need also the list of recipients, so I set "recipients, documents").
Then, on Envelope objects returned by the request, the getEnvelopeDocuments() method can be called, which return a list of Document objects. Such objects contain all the summary information, included the "documentUri", in a form like:
/envelopes/c34c029d-1074-4h66-afe1-324b851397c4/documents/1
which, concatenated to the basepath, forms exactly the URL of the REST API to download a document. In other words, using this URI or the EnvelopesApi.getDocument() are exactly the same things.
The conclusion is that there are no way to download documents, without down-counting at least one call from the per-hour available
[1] https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/liststatuschanges/
It is not clear to me what env.getEnvelopeDocuments() is doing.
You should be using the EnvelopeDocuments:get API method.
Here is a code example of calling the API method from Java.
byte[] results = envelopesApi.getDocument(accountId, envelopeId, documentId);
To get all the documents combined into one document, use the reserved value "combined" as the documentId.
Related
I'm trying to send an envelope by using the DocuSign rest API. However I'm facing this error when using a template with an envelope:
{{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes/{{envelopeId}}
{"errorCode": "ENVELOPE_IS_INCOMPLETE",
"message": "The Envelope is not Complete. A Complete Envelope Requires Documents, Recipients, Tabs, and a Subject Line."}
This is my response JSON from the GET envelopes:
{
"status": "created",
"documentsUri": "/envelopes/9d3745dd-33e1-4b2a-a8ab-332d4f18c302/documents",
"recipientsUri": "/envelopes/9d3745dd-33e1-4b2a-a8ab-332d4f18c302/recipients",
"attachmentsUri": "/envelopes/9d3745dd-33e1-4b2a-a8ab-332d4f18c302/attachments",
"envelopeUri": "/envelopes/9d3745dd-33e1-4b2a-a8ab-332d4f18c302",
"emailSubject": "Test 1",
"emailBlurb": "Welcome!",
"envelopeId": "9d3745dd-33e1-4b2a-a8ab-332d4f18c302",
"signingLocation": "online",
"customFieldsUri": "/envelopes/9d3745dd-33e1-4b2a-a8ab-332d4f18c302/custom_fields",
"notificationUri": "/envelopes/9d3745dd-33e1-4b2a-a8ab-332d4f18c302/notification",
"enableWetSign": "true",
"allowMarkup": "false",
"allowReassign": "true",
"createdDateTime": "2022-08-01T05:58:51.1070000Z",
"lastModifiedDateTime": "2022-08-01T05:58:55.6830000Z",
"statusChangedDateTime": "2022-08-01T05:58:51.1070000Z",
"documentsCombinedUri": "/envelopes/9d3745dd-33e1-4b2a-a8ab-332d4f18c302/documents/combined",
"certificateUri": "/envelopes/9d3745dd-33e1-4b2a-a8ab-332d4f18c302/documents/certificate",
"templatesUri": "/envelopes/9d3745dd-33e1-4b2a-a8ab-332d4f18c302/templates",
"sender": {
"userName": "test user",
"userId": "63217fd2-612b-45e7-8d3d-b30b6984925a",
"accountId": "257928273d",
"email": "test.user#asj.com"
},
"purgeState": "unpurged",
"envelopeIdStamping": "true",
"is21CFRPart11": "false",
"signerCanSignOnMobile": "true",
"autoNavigation": "true",
"isSignatureProviderEnvelope": "false",
"hasFormDataChanged": "false",
"allowComments": "true",
"hasComments": "false",
"allowViewHistory": "true",
"envelopeMetadata": {
"allowAdvancedCorrect": "true",
"enableSignWithNotary": "true",
"allowCorrect": "true"
},
"anySigner": null,
"envelopeLocation": "current_site",
"isDynamicEnvelope": "false"}
Then I try to POST the following JSON :
({{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes)
{
"templateId": "ba205a58-9bdc-4de3-82ad-26a432d93966",
"status": "sent"
}
Anything I might be missing?
Instead of:
POST ({{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes)
{
"templateId": "ba205a58-9bdc-4de3-82ad-26a432d93966",
"status": "sent"
}
Try this:
PUT ({{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes/{{envelopeId}}
{
"status": "sent"
}
Background
I am trying to create an envelope with the REST v2.1 API which has a textCustomField associated with it (for some individualised information about each envelope). I also want to set an envelope-level DocuSign Connect webhook (with the eventNotification) which will also include the customFields, so that I can pick this up at the HTTP listener. However, it doesn't seem clear in the documentation how to ensure that the envelope-level webhook includes the customFields (whereas this seems clearly possible when setting a Connect custom configuration at an Account level with the tickboxes when configuring the custom Connect configuration - and I can see this working at an HTTP listener). This Q&A (Does DocuSign Connect support JSON data or payloads?) about Connect seems to indicate that you can includeData for the eventNotification through eventData. When I try to test this with Postman, I seem to be able to create the envelope custom fields when creating the envelope, which I can check with the GET custom field info for an envelope, but these are not being included with the webhook request.
The question
Is it possible to includeData for the Envelope Custom Fields when registering the webhook at an envelope level or is this only possible from an Account level using Connect? If so, what is the correct property for including customFields in the webhook notification when creating the envelope via the REST API (as includeData doesn't seem to work)?
Examples
Excerpts of what I have been trying as the body of the request and what is received by the webhook below (with redactions):
Body of the Create Envelope request:
{
"emailSubject": "Please sign this document",
"documents": [
{
"documentBase64": "dGVzdCBkb2M=",
"name": "Lorem Ipsum",
"fileExtension": "txt",
"documentId": "1"
}
],
"customFields": {
"textCustomFields": [
{
"fieldId": "1",
"name": "Custom Field Name",
"show": "true",
"required": "false",
"value": "Custom Field Value 1"
}
]
},
"recipients": {
"signers": [
{
"email": "x#email.com",
"name": "X Name",
"recipientId": "1",
"routingOrder": "1"
}
]
},
"eventNotification": {
"eventData": {
"version": "restv2.1",
"format": "json",
"inludeData": [
"recipients",
"customFields"
]
},
"envelopeEvents": [
{
"envelopeEventStatusCode": "Sent",
"includeDocuments": "false"
},
{
"envelopeEventStatusCode": "Delivered",
"includeDocuments": "false"
},
{
"envelopeEventStatusCode": "Completed",
"includeDocuments": "false"
}
],
"loggingEnabled": "true",
"requireAcknowledgment": "true",
"url": "https://webhook.sitexxx"
},
"status": "sent"
}
Received by the webhook (customFields not included):
{
"status": "sent",
"documentsUri": "/envelopes/[x]/documents",
"recipientsUri": "/envelopes/[x]/recipients",
"attachmentsUri": "/envelopes/[x]/attachments",
"envelopeUri": "/envelopes/[x]",
"emailSubject": "Please sign this document",
"envelopeId": "[x]",
"signingLocation": "online",
"customFieldsUri": "/envelopes/[x]/custom_fields",
"notificationUri": "/envelopes/[x]/notification",
"enableWetSign": "true",
"allowMarkup": "false",
"allowReassign": "true",
"createdDateTime": "2021-02-21T15:07:38.05Z",
"lastModifiedDateTime": "2021-02-21T15:07:38.05Z",
"initialSentDateTime": "2021-02-21T15:07:39.067Z",
"sentDateTime": "2021-02-21T15:07:39.067Z",
"statusChangedDateTime": "2021-02-21T15:07:40.547Z",
"documentsCombinedUri": "/envelopes/[x]/documents/combined",
"certificateUri": "/envelopes/[x]/documents/certificate",
"templatesUri": "/envelopes/[x]/templates",
"expireEnabled": "true",
"expireDateTime": "2021-06-21T15:07:39.067Z",
"expireAfter": "120",
"sender": {
"userName": "[x]",
"userId": "[x]",
"accountId": "[x]",
"email": "[x]"
},
"purgeState": "unpurged",
"envelopeIdStamping": "true",
"is21CFRPart11": "false",
"signerCanSignOnMobile": "true",
"autoNavigation": "true",
"isSignatureProviderEnvelope": "false",
"hasFormDataChanged": "false",
"allowComments": "true",
"hasComments": "false",
"allowViewHistory": "true",
"envelopeMetadata": {
"allowAdvancedCorrect": "true",
"enableSignWithNotary": "true",
"allowCorrect": "true"
},
"anySigner": null,
"envelopeLocation": "current_site",
"isDynamicEnvelope": "false"
}
You misspelled the attribute name (includeData not inludeData) and item value (custom_fields not customFields). Try:
...
"includeData": [
"recipients",
"custom_fields"
]
The DocuSign API ignores attributes it doesn't recognize.
See the Connect JSON blog post for more info.
I am creating an envelope using this uri:
POST https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes
headers:
Content-Type : application/json
X-DocuSign-Authentication: {"Username" : *****, "Password" : ******, "IntegratorKey" : *********}
body:
{
"status": "sent",
"emailSubject": "Signing Request for Doc2.docx",
"signerCanSignOnMobile": "true",
"documents": [
{
"documentId": "384098342",
"name": "Doc2.docx",
"fileExtension": "docx",
"documentBase64": *****,
"tabs": {
"textTabs": [
{
"xPosition": "2",
"yPosition": "3",
"documentId": "384098342",
"pageNumber": "1",
"value": "Fill in name.",
"locked": "false",
"anchorString": "sign5",
"anchorXOffset": "1.75",
"anchorYOffset": "0",
"anchorUnits": "inches",
"anchorIgnoreIfNotPresent": "true"
}
]
}
}
],
"recipients": {
"signers": [
{
"name": "Tom Ford",
"email": "tom.ford#email.com",
"recipientId": "64000",
"clientUserId": "c7052b97-f9a7-4af4-85de-8c64371467b1"
},
{
"name": "Demand Approvers",
"email": "approvers#email.com",
"signingGroupId": "true",
"signingGroupName": "Demand Approvers",
"recipientId": "626000",
"clientUserId": "123c6d15-1d25-4595-9878-5cbda4ba2823",
"signingGroupUsers": [
{
"userName": "John Smith",
"userId": "9c328221-1e86-41db-a3e7-bde9b4b4a50d",
"email": "josmith#example.com"
}
]
}
]
}
}
and the request succeeds. However, when I try to query the returned envelope, the "Demand Approvers" is listed as a single recipient instead of as a signingGroup.
Here is an example output:
{
"status": "sent",
"documentsUri": "/envelopes/063454a6-dee6-4e86-8d38-56d85e66c61e/documents",
"recipientsUri": "/envelopes/063454a6-dee6-4e86-8d38-56d85e66c61e/recipients",
"attachmentsUri": "/envelopes/063454a6-dee6-4e86-8d38-56d85e66c61e/attachments",
"envelopeUri": "/envelopes/063454a6-dee6-4e86-8d38-56d85e66c61e",
"emailSubject": "Signing Request for Doc2.docx",
"envelopeId": "063454a6-dee6-4e86-8d38-56d85e66c61e",
"signingLocation": "online",
"customFieldsUri": "/envelopes/063454a6-dee6-4e86-8d38-56d85e66c61e/custom_fields",
"notificationUri": "/envelopes/063454a6-dee6-4e86-8d38-56d85e66c61e/notification",
"enableWetSign": "true",
"allowMarkup": "false",
"allowReassign": "true",
"createdDateTime": "2021-02-17T00:43:28.7070000Z",
"lastModifiedDateTime": "2021-02-17T00:43:28.7230000Z",
"initialSentDateTime": "2021-02-17T00:43:29.2570000Z",
"sentDateTime": "2021-02-17T00:43:29.2570000Z",
"statusChangedDateTime": "2021-02-17T00:43:29.2570000Z",
"documentsCombinedUri": "/envelopes/********************/documents/combined",
"certificateUri": "/envelopes/********************/documents/certificate",
"templatesUri": "/envelopes/********************/templates",
"expireEnabled": "true",
"expireDateTime": "2021-06-17T00:43:29.2570000Z",
"expireAfter": "120",
"sender": {
"userName": "********",
"userId": "********",
"accountId": "********",
"email": "sender#email.com"
},
"recipients": {
"signers": [
{
"creationReason": "sender",
"isBulkRecipient": "false",
"recipientSuppliesTabs": "true",
"requireUploadSignature": "false",
"name": "Demand Approvers",
"firstName": "",
"lastName": "",
"email": "approvers#email.com",
"recipientId": "626000",
"recipientIdGuid": "365b2f4d-0968-42d1-805e-55eece700246",
"requireIdLookup": "false",
"userId": "891a3891-f49d-4f14-8bc8-959524e2445a",
"clientUserId": "123c6d15-1d25-4595-9878-5cbda4ba2823",
"routingOrder": "1",
"status": "sent",
"completedCount": "0",
"deliveryMethod": "email",
"recipientType": "signer"
},
{
"creationReason": "sender",
"isBulkRecipient": "false",
"recipientSuppliesTabs": "true",
"requireUploadSignature": "false",
"name": "Tom Ford",
"firstName": "",
"lastName": "",
"email": "tom.ford#email.com",
"recipientId": "64000",
"recipientIdGuid": "c60c5ccd-e49f-4b63-9745-5f283b8520eb",
"requireIdLookup": "false",
"userId": "4a78d305-43bf-4d78-a844-2bdc15e63770",
"clientUserId": "c7052b97-f9a7-4af4-85de-8c64371467b1",
"routingOrder": "1",
"status": "sent",
"completedCount": "0",
"deliveryMethod": "email",
"recipientType": "signer"
}
],
"agents": [],
"editors": [],
"intermediaries": [],
"carbonCopies": [],
"certifiedDeliveries": [],
"inPersonSigners": [],
"seals": [],
"witnesses": [],
"notaries": [],
"recipientCount": "2",
"currentRoutingOrder": "1"
},
"purgeState": "unpurged",
"envelopeIdStamping": "true",
"is21CFRPart11": "false",
"signerCanSignOnMobile": "true",
"autoNavigation": "true",
"isSignatureProviderEnvelope": "false",
"hasFormDataChanged": "false",
"allowComments": "true",
"hasComments": "false",
"allowViewHistory": "true",
"envelopeMetadata": {
"allowAdvancedCorrect": "true",
"enableSignWithNotary": "true",
"allowCorrect": "true"
},
"anySigner": null,
"envelopeLocation": "current_site",
"isDynamicEnvelope": "false"
}
The signingGroup related information for Demand Approvers is missing.
How do I structure my request so that the Demand Approvers will be listed as a signingGroup?
I found the cause. So it seems that when dealing with Signing Groups,
These 2 points must be true:
The Signing Group must be registered in DocuSign. The generated
signingGroupId can then be used as recipient. Setting signingGroupId
to "true" or any random value will not work.
clientUserId must not be provided
From the eSig API, GET /v2.1/accounts/{accountId}/users/{userId}/profile, this will return the authenticationMethods information, but when I tried on sandbox, I didn't get that section.
the whole api url:
https://demo.docusign.net/restapi/v2.1/accounts/xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx/users/xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx/profile
Response:
{
"displayProfile": "true",
"displayOrganizationInfo": "false",
"displayPersonalInfo": "false",
"displayUsageHistory": "false",
"companyName": "dd",
"title": "Z",
"userDetails": {
"userName": "X Y",
"userId": "xxxxxxx-xxxxx-xxxx-a2a2-79cac67194c7",
"uri": "/users/xxxxx-xxxxx-xxxx-a2a2-xxxxxxx",
"email": "xxx#gmail.com",
"createdDateTime": "2019-10-07T12:38:53.2330000Z",
"userAddedToAccountDateTime": "0001-01-01T08:00:00.0000000Z",
"firstName": "X",
"lastName": "Y",
"permissionProfileId": "xxxxxx",
"permissionProfileName": "Account Administrator",
"defaultAccountId": "xxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx"
},
"address": {
"address1": "",
"address2": "",
"city": "",
"stateOrProvince": "",
"postalCode": "",
"phone": "",
"fax": "",
"country": ""
},
"usageHistory": {
"signedCount": "0",
"sentCount": "0"
},
"userProfileLastModifiedDate": "2019-10-07T06:08:49.1700000Z"
}
I tried to use a GET call in POSTMAN to get the List of Templates and include the Custom Field, but the response does not return the custom_fields value, any thoughts?
GET:
https://demo.docusign.net/restapi/v2/accounts/{account_id}/templates?include=recipients,documents,custom_fields
RESPONSE
{
"templateId": "XXXXXXXXXXXXXXXXXXXXX",
"name": "DEMO",
"shared": "true",
"password": "",
"description": "",
"lastModified": "2017-06-20T14:13:57.9270000Z",
"pageCount": 2,
"uri": "xxxxxxxxxxx",
"folderName": "DEMO",
"folderId": "617c1361-8576-4b62-930e-735442256a25",
"folderUri": "xxxxxxxxx",
"owner": {
"userName": "XXXXXXXXXXXXXXX",
"userId": "XXXXXXXXXXXXXXXXXX",
"email": "XXXXXXXXX#XXXX.COM"
},
"documents": [
{
"documentId": "1",
"uri": "xxxxxxxxxxxx",
"name": "DS_DEMO.pdf",
"order": "1",
"pages": "1",
"display": "inline",
"includeInDownload": "true",
"signerMustAcknowledge": "no_interaction",
"templateLocked": "false",
"templateRequired": "false",
"documentGroup": "content"
},
{
"documentId": "54582351",
"uri": "xxxxxxxxxxxx",
"name": "XXXXXXXXXXXXXX.png",
"order": "2",
"pages": "1",
"display": "inline",
"includeInDownload": "true",
"signerMustAcknowledge": "no_interaction",
"templateLocked": "false",
"templateRequired": "false",
"documentGroup": "content"
}
],
"emailSubject": "Please sign this DS Document",
"emailBlurb": "Thank you for reaching and showing us your interest in how DocuSign works. Please, practice here.\n\n",
"signingLocation": "Online",
"authoritativeCopy": "false",
"enforceSignerVisibility": "false",
"enableWetSign": "false",
"allowMarkup": "true",
"allowReassign": "true",
"recipients": {
"signers": [
{
"defaultRecipient": "false",
"signInEachLocation": "false",
"email": "",
"recipientId": "4",
"accessCode": "",
"requireIdLookup": "false",
"routingOrder": "2",
"note": "",
"roleName": "System Analyst",
"status": "created",
"deliveryMethod": "email",
"templateLocked": "false",
"templateRequired": "false",
"inheritEmailNotificationConfiguration": "false",
"documentVisibility": [
{
"documentId": "1",
"visible": "true"
},
{
"documentId": "54582351",
"visible": "true"
}
]
},
{
"defaultRecipient": "false",
"signInEachLocation": "false",
"name": "DS Training",
"email": "",
"signingGroupId": "10749",
"signingGroupName": "DS Training",
"recipientId": "2",
"accessCode": "",
"requireIdLookup": "false",
"routingOrder": "1",
"note": "Please complete it as soon you can",
"roleName": "Sales Analyst",
"status": "created",
"deliveryMethod": "email",
"templateLocked": "false",
"templateRequired": "false",
"inheritEmailNotificationConfiguration": "false",
"documentVisibility": [
{
"documentId": "1",
"visible": "true"
},
{
"documentId": "54582351",
"visible": "true"
}
]
}
],
"agents": [],
"editors": [],
"intermediaries": [],
"carbonCopies": [
{
"email": "",
"recipientId": "3",
"accessCode": "",
"requireIdLookup": "false",
"routingOrder": "3",
"note": "",
"roleName": "Manager",
"status": "created",
"templateLocked": "false",
"templateRequired": "false",
"inheritEmailNotificationConfiguration": "false",
"documentVisibility": [
{
"documentId": "1",
"visible": "true"
},
{
"documentId": "54582351",
"visible": "true"
}
]
}
],
"certifiedDeliveries": [],
"inPersonSigners": [],
"recipientCount": "3"
}
},
Reference:
Templates: list documentation
You're right. It is a bug. Thank you for the report. I've verified it and filed DocuSign internal bug report API-7048.
In the meantime, the work-around is to use Templates: get for each of the templates returned by the Templates: list operation.