Get recipient view not working for composite envelope

Question

I want to create a composite envelope and then do an embedded signing. The issue is that the envelope is created but the call to get the url fails.

First I create the composite envelope:

https://demo.docusign.net/restapi/v2/accounts/ACCOUNT/envelopes
{
"emailSubject": "DocuSign API - Composite Templates",
"emailBlurb": "Composite Templates Sample 1",
"status": "sent",
"compositeTemplates": [
    {
        "serverTemplates": [
            {
                "sequence": "1",
                "templateId": "1AA7BA0B-9079-4F8C-915B-739576297D62"
            }
        ],
        "inlineTemplates": [
            {
                "sequence": "1",
                "recipients": {
                    "signers": [
                        {
                            "email": "email@email.com",
                            "name": "Signer Name",
                            "recipientId": "1",
                            "roleName": "Account Holder"
                        }
                    ]
                }
            }
        ]
    },
    {
        "serverTemplates": [
            {
                "sequence": "2",
                "templateId": "77343ECC-391F-46A1-BFC3-92A3CD8C93E3"
            }
        ],
        "inlineTemplates": [
            {
                "sequence": "2",
                "recipients": {
                    "signers": [
                        {
                            "email": "email@email.com",
                            "name": "Signer Name",
                            "recipientId": "1",
                            "roleName": "Account Holder",
                            "tabs": {
                                "textTabs": [
                                    {
                                        "tabLabel": "AccountFirstName",
                                        "value": "Client"
                                    },
                                    {
                                        "tabLabel": "AccountLastName",
                                        "value": "Name"
                                    },
                                    {
                                        "tabLabel": "Email1",
                                        "value": "someEmail@email.com"
                                    }
                                ]
                            }
                        }
                    ]
                }
            }
        ]
    },
    {
        "serverTemplates": [
            {
                "sequence": "3",
                "templateId": "ADADDD87-E831-4EF3-A160-BBE73F449C8E"
            }
        ],
        "inlineTemplates": [
            {
                "sequence": "3",
                "recipients": {
                    "signers": [
                        {
                            "email": "email@email.com",
                            "name": "Signer Name",
                            "recipientId": "1",
                            "roleName": "Account Holder"
                        }
                    ]
                }
            }
        ]
    }
]

}

The response is:

{
"envelopeId": "99f4c73d-6420-4e3b-88eb-2447139a2616",
"uri": "/envelopes/99f4c73d-6420-4e3b-88eb-2447139a2616",
"statusDateTime": "2014-08-14T21:09:09.0430000Z",
"status": "sent"   }

Next I try to get the recipient view

https://demo.docusign.net/restapi/v2/accounts/ACCOUNT/envelopes/99f4c73d-6420-4e3b-88eb-2447139a2616/views/recipient
{
  "authenticationMethod": "email",
  "email": "email@email.com",
  "returnUrl": "www.someUrl.com",
  "userName": "Signer Name"
}

And I get this error:

{
"errorCode": "UNKNOWN_ENVELOPE_RECIPIENT",
"message": "The recipient you have identified is not a valid recipient of the specified      envelope. Envelope recipient could not be determined. 'clientUserId', 'email', or 'userName' in request and envelope may not match."
}

The email and the names match up so I do not understand why I am unable to get the url. I should point out that this all works if I use the same name and email that is on the DocuSign account, but this needs to work for an external recipient.

Answer 1

To designate a recipient as an embedded/captive recipient when creating an Envelope, such that you'll subsequently be able to submit a "Get Recipient View" request to retrieve a URL that can be used to initiate the recipient's signing session, your "Create Envelope" request must specify the clientUserId property for the recipient. This property should appear as a peer to the other recipient properties (i.e.: email, name, etc.) -- like this:

"signers": [
    {
        "email": "email@email.com",
        "name": "Signer Name",
        "recipientId": "1",
        "roleName": "Account Holder",
        "clientUserId": "12345"
    }
]

Then, when you submit the "Get Recipient View" request, you'll need to specify the same value for clientUserId there:

POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes/ENVELOPE_ID/views/recipient

{
  "authenticationMethod": "Email",
  "email": "email@email.com",
  "returnUrl": "www.someUrl.com",
  "userName": "Signer Name",
  "clientUserId": "12345"
}

The value of clientUserId can be anything you wish, but max length is 100 characters. See the DocuSign REST API Guide for more details about embedded signing.