RecipientId get changed by docusign

Question

I am creating envelope using DocuSign API. While creating envelope I am also passing list of signers and also set my own unique "RecipientId" (GUID) for each signers. But when envelope gets created and checking the list of recipients(signers) and found that recipient id gets changed all time. It is not "RecipientId" which I am passing.

Can you help me how can we set own "RecipientId" while creating envelope?

-- Create envelope request

 { "documents": [{
                    "documentBase64": "<Base64BytesHere>", 
                    "documentId": "1", 
                    "fileExtension": "pdf", 
                    "name": "lite" 
                }], 
    "emailSubject": "test recipient 2", 
    "recipients": { "signers": [ { "email": "[email protected]", 
                                    "name": "xxx yyy", 
                                    "recipientId": "1" 
                                    } ]
                  }, 
    "status": "sent" 
 }

-- Web hook Response see recipient Id --

<DocuSignEnvelopeInformation><EnvelopeStatus>
    <RecipientStatuses>
        <RecipientStatus>
            <Type>Signer</Type>
            <Email>[email protected]</Email>
            <UserName>xxx yyy</UserName>
            <RoutingOrder>1</RoutingOrder>
            <Sent>2017-08-29T02:13:33.853</Sent>
            <DeclineReason xsi:nil="true"/>
            <Status>Sent</Status>
            <RecipientIPAddress/>
            <CustomFields/>
            <AccountStatus>Active</AccountStatus>
            <RecipientId>011eac75-f2fa-4f57-94df-5aedaxxxxxxx</RecipientId>
        </RecipientStatus>
    </RecipientStatuses>
....
<DocuSignEnvelopeInformation><EnvelopeStatus>

Answer 1

Another way around this is to use recipient.customFields. It's an array of strings:

someEnvelopeSigner.customFields = [yourUUID, somethingElse]

In the webhook / event notification, it will come through in DocuSignEnvelopeInformation.EnvelopeStatus[0].RecipientStatuses[0].RecipientStatus[i].CustomFields and look something like (in JSONified form)

{
  "CustomFields": [{
    "CustomField": [
      "6e45cb20-3953-11ea-b02d-dedef9da77b9",
      "something else!"
    ]
  }],
}

Answer 2

You can specify a unique recipientId for each recipient while creating an envelope.

Here is a sample CreateEnvelope request

POST /v2/accounts/{accountId}/envelopes

Json Payload.

{
 "emailSubject": "Please sign the agreement",
 "status": "sent",
 "recipients": {
     "signers": [
         {
             "email": "[email protected]",
             "name": "jane doe",
             "recipientId": 1,
             "routingOrder": 1,
             "tabs": {
                 "signHereTabs": [
                     {
                         "documentId": "1", "pageNumber": "1", "xPosition": "80", "yPosition": "80"
                     }

                 ]
             }
         },
         {
             "email": "[email protected]",
             "name": "john smith",
             "recipientId": 2,
             "routingOrder": 2,
             "tabs": {
                 "signHereTabs": [
                     {
                         "documentId": "1", "pageNumber": "1", "xPosition": "80", "yPosition": "180"
                     }

                 ]
             }
         }
     ]
 },
 "documents": [
     {
         "documentId": "1",
         "name": "Contract",
         "fileExtension": "txt",
         "documentBase64": "RG9jIFRXTyBUV08gVFdP"
     }
 ]
}

---

Use the listEnvelopeRecipients api to retrieve the list of recipients in the envelope.

{
  "signers": [
    {
        "creationReason": "sender",
        "isBulkRecipient": "false",
        "name": "jane doe",
        "email": "[email protected]",
        "recipientId": "1",
        "recipientIdGuid": "98d60cc3-5f67-46e4-9fc0-ca6bb519f1c9",
        "requireIdLookup": "false",
        "userId": "585b8733-b1a9-4329-87e7-4f20bcde00c2",
        "routingOrder": "1",
        "status": "sent"
    },
    {
        "creationReason": "sender",
        "isBulkRecipient": "false",
        "name": "john smith",
        "email": "[email protected]",
        "recipientId": "2",
        "recipientIdGuid": "726bd54d-89ed-41ba-a751-fdb129894b8b",
        "requireIdLookup": "false",
        "userId": "45abe022-ae12-4816-8c42-fd66d207807a",
        "routingOrder": "2",
        "status": "created"
    }
  ],
"agents": [],
"editors": [],
"intermediaries": [],
"carbonCopies": [],
"certifiedDeliveries": [],
"inPersonSigners": [],
"recipientCount": "2",
"currentRoutingOrder": "1"
}