(Ruby) DocuSign Add Recipients to a Draft Envelope

See more DocuSign Examples

Demonstrates how to add one or more recipients to a DocuSign draft envelope.

For more information, see https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/enveloperecipients/create/

Chilkat Ruby Downloads install from rubygems.org gem install chilkat or download... Ruby Library for Windows, MacOS, Linux, Alpine Linux

require 'chilkat'

# This example assumes the Chilkat API to have been previously unlocked.
# See Global Unlock Sample for sample code.

http = Chilkat::CkHttp.new()

# Load a previously obtained OAuth2 access token.
jsonToken = Chilkat::CkJsonObject.new()
success = jsonToken.LoadFile("qa_data/tokens/docusign.json")
if (success == false)
    print jsonToken.lastErrorText() + "\n";
    exit
end

# Adds the "Authorization: Bearer eyJ0eXAi.....UE8Kl_V8KroQ" header.
http.put_AuthToken(jsonToken.stringOf("access_token"))

# Send the following request.
# Make sure to use your own account ID (obtained from Get Docusign User Account Information)

# POST https://demo.docusign.net/restapi/v2.1/accounts/<account ID>/envelopes/<envelope ID>/recipients HTTP/1.1
# Accept: application/json
# Cache-Control: no-cache
# Authorization: Bearer eyJ0eX...
# Content-Length: ...
# Content-Type: application/json
# 
# {
#   "carbonCopies": [
#     {
#       "email": "support@chilkatsoft.com",
#       "name": "Chilkat Support",
#       "recipientId": "101",
#       "tabs": {}
#     }
#   ],
#   "signers": [
#     {
#       "email": "admin@chilkatsoft.com",
#       "name": "Chilkat Admin",
#       "recipientId": "1",
# 	 "tabs": {
# 	    "signHereTabs": [{
# 	        "anchorString": "Please Sign Here",
# 	        "anchorXOffset": "1",
# 	        "anchorYOffset": "0",
# 	        "anchorIgnoreIfNotPresent": "false",
# 	        "anchorUnits": "inches"
# 	    }]
# 	}
#     },
#     {
#       "email": "matt@chilkat.io",
#       "name": "Matt",
#       "recipientId": "2",
# 	 "tabs": {
# 	    "signHereTabs": [{
# 	        "anchorString": "Please Also Sign Here",
# 	        "anchorXOffset": "1",
# 	        "anchorYOffset": "0",
# 	        "anchorIgnoreIfNotPresent": "false",
# 	        "anchorUnits": "inches"
# 	    }]
# 	}
#     }
#   ]
# }

json = Chilkat::CkJsonObject.new()
i = 0
json.put_I(i)
json.UpdateString("carbonCopies[i].email","support@chilkatsoft.com")
json.UpdateString("carbonCopies[i].name","Chilkat Support")
json.UpdateString("carbonCopies[i].recipientId","101")
json.UpdateNewObject("carbonCopies[i].tabs")
i = 0
json.put_I(i)
json.UpdateString("signers[i].email","admin@chilkatsoft.com")
json.UpdateString("signers[i].name","Chilkat Admin")
json.UpdateString("signers[i].recipientId","1")
json.UpdateString("signers[i].tabs.signHereTabs[0].anchorString","Please Sign Here")
json.UpdateString("signers[i].tabs.signHereTabs[0].anchorXOffset","1")
json.UpdateString("signers[i].tabs.signHereTabs[0].anchorYOffset","0")
json.UpdateString("signers[i].tabs.signHereTabs[0].anchorIgnoreIfNotPresent","false")
json.UpdateString("signers[i].tabs.signHereTabs[0].anchorUnits","inches")
i = i + 1
json.put_I(i)
json.UpdateString("signers[i].email","matt@chilkat.io")
json.UpdateString("signers[i].name","Matt")
json.UpdateString("signers[i].recipientId","2")
json.UpdateString("signers[i].tabs.signHereTabs[0].anchorString","Please Also Sign Here")
json.UpdateString("signers[i].tabs.signHereTabs[0].anchorXOffset","1")
json.UpdateString("signers[i].tabs.signHereTabs[0].anchorYOffset","0")
json.UpdateString("signers[i].tabs.signHereTabs[0].anchorIgnoreIfNotPresent","false")
json.UpdateString("signers[i].tabs.signHereTabs[0].anchorUnits","inches")

sbJson = Chilkat::CkStringBuilder.new()
json.put_EmitCompact(false)
json.EmitSb(sbJson)

http.SetRequestHeader("Cache-Control","no-cache")
http.SetRequestHeader("Accept","application/json")

# Use your own account ID here.
http.SetUrlVar("accountId","7f3f65ed-5e87-418d-94c1-92499ddc8252")
# Use the envelope ID returned by DocuSign when creating the draft envelope).
http.SetUrlVar("envelopeId","191838e0-4f61-4b78-96fd-d9dd97bb003a")

url = "https://demo.docusign.net/restapi/v2.1/accounts/{$accountId}/envelopes/{$envelopeId}/recipients"
# resp is a CkHttpResponse
resp = http.PTextSb("POST",url,sbJson,"utf-8","application/json",false,false)
if (http.get_LastMethodSuccess() == false)
    print http.lastErrorText() + "\n";
    exit
end

jResp = Chilkat::CkJsonObject.new()
jResp.Load(resp.bodyStr())
jResp.put_EmitCompact(false)

print "Response Body:" + "\n";
print jResp.emit() + "\n";

# If you get a 401 response status code, it's likely you need to refresh the DocuSign OAuth2 token).
respStatusCode = resp.get_StatusCode()
print "Response Status Code = " + respStatusCode.to_s() + "\n";
if (respStatusCode >= 400)
    print "Response Header:" + "\n";
    print resp.header() + "\n";
    print "Failed." + "\n";

    exit
end

# Sample JSON response:
# (Sample code for parsing the JSON response is shown below)

# {
#     "signers": [
#         {
#             "creationReason": "sender",
#             "requireUploadSignature": "false",
#             "email": "admin@chilkatsoft.com",
#             "recipientId": "1",
#             "requireIdLookup": "false",
#             "routingOrder": "1",
#             "status": "created",
#             "completedCount": "0",
#             "deliveryMethod": "email",
#             "recipientType": "signer"
#         },
#         {
#             "creationReason": "sender",
#             "requireUploadSignature": "false",
#             "email": "matt@chilkat.io",
#             "recipientId": "2",
#             "requireIdLookup": "false",
#             "routingOrder": "1",
#             "status": "created",
#             "completedCount": "0",
#             "deliveryMethod": "email",
#             "recipientType": "signer"
#         }
#     ],
#     "agents": [],
#     "editors": [],
#     "intermediaries": [],
#     "carbonCopies": [
#         {
#             "email": "support@chilkatsoft.com",
#             "recipientId": "101",
#             "requireIdLookup": "false",
#             "routingOrder": "1",
#             "status": "created",
#             "completedCount": "0",
#             "deliveryMethod": "email",
#             "recipientType": "carboncopy"
#         }
#     ],
#     "certifiedDeliveries": [],
#     "inPersonSigners": [],
#     "seals": [],
#     "witnesses": [],
#     "recipientCount": "3"
# }

# Sample code for parsing the JSON response...
# Use the following online tool to generate parsing code from sample JSON:
# Generate Parsing Code from JSON

recipientCount = json.stringOf("recipientCount")
i = 0
count_i = json.SizeOfArray("signers")
while i < count_i
    json.put_I(i)
    creationReason = json.stringOf("signers[i].creationReason")
    requireUploadSignature = json.stringOf("signers[i].requireUploadSignature")
    email = json.stringOf("signers[i].email")
    recipientId = json.stringOf("signers[i].recipientId")
    requireIdLookup = json.stringOf("signers[i].requireIdLookup")
    routingOrder = json.stringOf("signers[i].routingOrder")
    status = json.stringOf("signers[i].status")
    completedCount = json.stringOf("signers[i].completedCount")
    deliveryMethod = json.stringOf("signers[i].deliveryMethod")
    recipientType = json.stringOf("signers[i].recipientType")
    i = i + 1
end
i = 0
count_i = json.SizeOfArray("agents")
while i < count_i
    json.put_I(i)
    #    ...
    i = i + 1
end
i = 0
count_i = json.SizeOfArray("editors")
while i < count_i
    json.put_I(i)
    #    ...
    i = i + 1
end
i = 0
count_i = json.SizeOfArray("intermediaries")
while i < count_i
    json.put_I(i)
    #    ...
    i = i + 1
end
i = 0
count_i = json.SizeOfArray("carbonCopies")
while i < count_i
    json.put_I(i)
    email = json.stringOf("carbonCopies[i].email")
    recipientId = json.stringOf("carbonCopies[i].recipientId")
    requireIdLookup = json.stringOf("carbonCopies[i].requireIdLookup")
    routingOrder = json.stringOf("carbonCopies[i].routingOrder")
    status = json.stringOf("carbonCopies[i].status")
    completedCount = json.stringOf("carbonCopies[i].completedCount")
    deliveryMethod = json.stringOf("carbonCopies[i].deliveryMethod")
    recipientType = json.stringOf("carbonCopies[i].recipientType")
    i = i + 1
end
i = 0
count_i = json.SizeOfArray("certifiedDeliveries")
while i < count_i
    json.put_I(i)
    #    ...
    i = i + 1
end
i = 0
count_i = json.SizeOfArray("inPersonSigners")
while i < count_i
    json.put_I(i)
    #    ...
    i = i + 1
end
i = 0
count_i = json.SizeOfArray("seals")
while i < count_i
    json.put_I(i)
    #    ...
    i = i + 1
end
i = 0
count_i = json.SizeOfArray("witnesses")
while i < count_i
    json.put_I(i)
    #    ...
    i = i + 1
end

# If the recipient already exists within the envelope, we would get
# a success (201) response status code, but errors within the JSON response, such as this:

# {
#   "signers": [
#     {
#       "creationReason": "sender",
#       "requireUploadSignature": "false",
#       "email": "admin@chilkatsoft.com",
#       "recipientId": "1",
#       "requireIdLookup": "false",
#       "routingOrder": "1",
#       "status": "error",
#       "completedCount": "0",
#       "deliveryMethod": "email",
#       "errorDetails": {
#         "errorCode": "RECIPIENT_ALREADY_EXISTS_IN_ENVELOPE",
#         "message": "This recipientId already exists."
#       },
#       "recipientType": "signer"
#     },
#     {
#       "creationReason": "sender",
#       "requireUploadSignature": "false",
#       "email": "matt@chilkat.io",
#       "recipientId": "2",
#       "requireIdLookup": "false",
#       "routingOrder": "1",
#       "status": "error",
#       "completedCount": "0",
#       "deliveryMethod": "email",
#       "errorDetails": {
#         "errorCode": "RECIPIENT_ALREADY_EXISTS_IN_ENVELOPE",
#         "message": "This recipientId already exists."
#       },
#       "recipientType": "signer"
#     }
#   ],
#   "agents": [
#   ],
#   "editors": [
#   ],
#   "intermediaries": [
#   ],
#   "carbonCopies": [
#     {
#       "email": "support@chilkatsoft.com",
#       "recipientId": "101",
#       "requireIdLookup": "false",
#       "routingOrder": "1",
#       "status": "error",
#       "completedCount": "0",
#       "deliveryMethod": "email",
#       "errorDetails": {
#         "errorCode": "RECIPIENT_ALREADY_EXISTS_IN_ENVELOPE",
#         "message": "This recipientId already exists."
#       },
#       "recipientType": "carboncopy"
#     }
#   ],
#   "certifiedDeliveries": [
#   ],
#   "inPersonSigners": [
#   ],
#   "seals": [
#   ],
#   "witnesses": [
#   ],
#   "recipientCount": "3"
# }
#