My use case is, create an envelope with an agent to specify the following signer's name and email.
I created the envelop by POST {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes, with request body:
{
"recipients": {
"agents": [
{
"clientUserId": "1",
"email": "[email protected]",
"name": "Agent",
"recipientId": "1",
"routingOrder": "1"
}
],
"signers": [
{
"clientUserId": "2",
"email": "",
"name": "",
"recipientId": "2",
"routingOrder": "2",
"tabs": {
"signHereTabs": [
{
"anchorIgnoreIfNotPresent": "false",
"anchorString": "Signature_anchor_1",
"anchorUnits": "pixels",
"anchorYOffset": "0",
"name": "Please sign here",
"recipientId": "1"
}
]
}
}
]
},
"emailSubject": "DocuSign API - Signature Request on Document Call",
"documents": [
{
"documentId": "1",
"name": "{{fileName}}",
"documentBase64": "{{fileBase64}}"
}
],
"status": "sent"
}
After the agent specify the name and email address of the signer, I could not obtain the signing URL by POST {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes/{{envelopeId}}/views/recipient , with request body:
{
"clientUserId": "2",
"userName": "",
"email": "",
"recipientId": "2",
"returnUrl": "https://www.sample.com",
"authenticationMethod": "email"
}
The response is:
{
"errorCode": "INVALID_REQUEST_PARAMETER",
"message": "The request contained at least one invalid parameter. A value was not found for parameter 'userName'."
}
I tried to get it with the new specified name and email:
{
"clientUserId": "2",
"userName": "new",
"email": "new@example",
"recipientId": "2",
"returnUrl": "https://www.sample.com",
"authenticationMethod": "email"
}
But still got the error response:
{
"errorCode": "UNKNOWN_ENVELOPE_RECIPIENT",
"message": "The recipient you have identified is not a valid recipient of the specified envelope."
}
I tried to get the recipientId by calling the get envelop API and use the recipientId to retrieve the view but still not working.
How can this URL be generated? What request body should it be?
Update: With scenario below:
- Envelope has 1 Agent and 1 Recipient, when the sender sends out the envelop, the email and name of the recipient are unknown for the sender, only agent knows the info (that's why I put the name and email as empty for the recipient).
- Agent received the request and put in the name and email address for that recipient
- We want to get that embedded signing link for the recipient, but now seems that we could not retrieve it even with the info obtained by calling GET
GET /restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients
Update 2:
As suggested to put a place holder for the name and email and also add the clientUserId for the signer, I call the create envelope API with request body:
{
"recipients": {
"agents": [
{
"clientUserId": "1",
"email": "[email protected]",
"name": "Agent",
"recipientId": "1",
"routingOrder": "1"
}
],
"signers": [
{
"clientUserId": "2",
"email": "[email protected]",
"name": "example",
"recipientId": "2",
"routingOrder": "2",
"tabs": {
"signHereTabs": [
{
"anchorIgnoreIfNotPresent": "false",
"anchorString": "Signature_anchor_1",
"anchorUnits": "pixels",
"anchorYOffset": "0",
"name": "Please sign here",
"recipientId": "1"
}
]
}
}
]
},
"emailSubject": "DocuSign API - Signature Request on Document Call",
"documents": [
{
"documentId": "1",
"name": "{{fileName}}",
"documentBase64": "{{fileBase64}}"
}
],
"status": "sent"
}
For the agent, he cannot change the email/name for the signer, since when he accesses the DocuSign signing link, DocuSign pops a message "All recipients have been assigned".
So I tried to use intermediaries instead of agents and call with the request body:
{
"recipients": {
"intermediaries": [
{
"clientUserId": "1",
"email": "[email protected]",
"name": "Intermediary",
"recipientId": "1",
"routingOrder": "1"
}
],
"signers": [
{
"clientUserId": "2",
"email": "[email protected]",
"name": "example",
"recipientId": "2",
"routingOrder": "2",
"tabs": {
"signHereTabs": [
{
"anchorIgnoreIfNotPresent": "false",
"anchorString": "Signature_anchor_1",
"anchorUnits": "pixels",
"anchorYOffset": "0",
"name": "Please sign here",
"recipientId": "1"
}
]
}
}
]
},
"emailSubject": "DocuSign API - Signature Request on Document Call",
"documents": [
{
"documentId": "1",
"name": "{{fileName}}",
"documentBase64": "{{fileBase64}}"
}
],
"status": "sent"
}
The intermediary can update the name/email for the signer. But after the intermediary change the info, DocuSign will send an email to the updated email address even the clientUserId is already set in the request body for that signer.
I'm wondering if this is the expected behaviour:
- Whenever an intermediary updates a signer's name/email, DocuSign will send the email to the updated email address regardless whether the
clientUserIdis set for that signer
This might be another question, but it seems DocuSign handles the update email event for signer and witness differently. I'm wondering scenario I observed is the expected one:
- When a signer updates/adds the name/email for his witness, DocuSign will not send the email to the updated email address if the
clientUserIdis set for that witness
Update3:
After calling with the intermediaries param, I can retrieve the Signer's signing URL by either calling with request body:
{
"clientUserId": "2",
"userName": "example",
"email": "[email protected]",
"recipientId": "2",
"returnUrl": "https://www.google.com",
"authenticationMethod": "email"
}
OR
{
"clientUserId": "2",
"userId": {{userId retrieved from get envelope recipients}},
"recipientId": "2",
"returnUrl": "https://www.google.com",
"authenticationMethod": "email"
}
But after the intermediary changed the email/name of the recipient, none of the above request body could retrieve the signing URL. I tried both original and updated clientId and (email + name) combination, but still not working.
I assume this is a design of DocuSign: it's not allowed to retrieve the recipient's signing URL after an intermediary changes the recipient'e email/name, this signing URL can be only obtained by that email sent by DocuSign. This email cannot be turned off event the clientUserId is set. Is it correct?
Update 4:
As suggested, I tried with the workflow option with request body:
{
"recipients": {
"intermediaries": [
{
"clientUserId": "1",
"email": "[email protected]",
"name": "Intermediary",
"recipientId": "1",
"routingOrder": "1"
}
],
"signers": [
{
"clientUserId": "2",
"email": "[email protected]",
"name": "example",
"recipientId": "2",
"routingOrder": "2",
"tabs": {
"signHereTabs": [
{
"anchorIgnoreIfNotPresent": "false",
"anchorString": "Signature_anchor_1",
"anchorUnits": "pixels",
"anchorYOffset": "0",
"name": "Please sign here",
"recipientId": "1"
}
]
}
}
]
},
"workflow": {
"workflowSteps": [
{
"action": "pause_before",
"itemId": "2",
"triggerOnItem": "routing_order"
}
]
},
"emailSubject": "DocuSign API - Signature Request on Document Call",
"documents": [
{
"documentId": "1",
"name": "{{fileName}}",
"documentBase64": "{{fileBase64}}"
}
],
"status": "sent"
}
I can only pause the workflow before routing order 2, since there would be a 400 error if I put the workflow param as to achieve "insert a workflow pause immediately after the intermediaterecipient":
"workflow": {
"workflowSteps": [
{
"action": "pause_after",
"itemId": "1",
"triggerOnItem": "routing_order"
}
]
},
After the intermediate recipient updated the name/email, I did an API call to set the clientUserId for the signer and it works fine. But I was not able to resume the workflow by calling URL {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes/{{envelopeId}}?resend_envelope=true with request body:
{
"workflow": {
"workflowStatus": "in_progress"
}
}
The status of the signer stayed as created and could not be updated to sent, thus could not retrieve the signing URL for the signer. How can we unpause the workflow?
