(Tcl) 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 Tcl Extension Downloads Chilkat Tcl Extension Downloads

load ./chilkat.dll

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

set http [new_CkHttp]

# Load a previously obtained OAuth2 access token.
set jsonToken [new_CkJsonObject]

set success [CkJsonObject_LoadFile $jsonToken "qa_data/tokens/docusign.json"]
if {$success == 0} then {
    puts [CkJsonObject_lastErrorText $jsonToken]
    delete_CkHttp $http
    delete_CkJsonObject $jsonToken
    exit
}

# Adds the "Authorization: Bearer eyJ0eXAi.....UE8Kl_V8KroQ" header.
CkHttp_put_AuthToken $http [CkJsonObject_stringOf $jsonToken "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"
# 	    }]
# 	}
#     }
#   ]
# }

set json [new_CkJsonObject]

set i 0
CkJsonObject_put_I $json $i
CkJsonObject_UpdateString $json "carbonCopies[i].email" "support@chilkatsoft.com"
CkJsonObject_UpdateString $json "carbonCopies[i].name" "Chilkat Support"
CkJsonObject_UpdateString $json "carbonCopies[i].recipientId" "101"
CkJsonObject_UpdateNewObject $json "carbonCopies[i].tabs"
set i 0
CkJsonObject_put_I $json $i
CkJsonObject_UpdateString $json "signers[i].email" "admin@chilkatsoft.com"
CkJsonObject_UpdateString $json "signers[i].name" "Chilkat Admin"
CkJsonObject_UpdateString $json "signers[i].recipientId" "1"
CkJsonObject_UpdateString $json "signers[i].tabs.signHereTabs[0].anchorString" "Please Sign Here"
CkJsonObject_UpdateString $json "signers[i].tabs.signHereTabs[0].anchorXOffset" "1"
CkJsonObject_UpdateString $json "signers[i].tabs.signHereTabs[0].anchorYOffset" "0"
CkJsonObject_UpdateString $json "signers[i].tabs.signHereTabs[0].anchorIgnoreIfNotPresent" "false"
CkJsonObject_UpdateString $json "signers[i].tabs.signHereTabs[0].anchorUnits" "inches"
set i [expr $i + 1]
CkJsonObject_put_I $json $i
CkJsonObject_UpdateString $json "signers[i].email" "matt@chilkat.io"
CkJsonObject_UpdateString $json "signers[i].name" "Matt"
CkJsonObject_UpdateString $json "signers[i].recipientId" "2"
CkJsonObject_UpdateString $json "signers[i].tabs.signHereTabs[0].anchorString" "Please Also Sign Here"
CkJsonObject_UpdateString $json "signers[i].tabs.signHereTabs[0].anchorXOffset" "1"
CkJsonObject_UpdateString $json "signers[i].tabs.signHereTabs[0].anchorYOffset" "0"
CkJsonObject_UpdateString $json "signers[i].tabs.signHereTabs[0].anchorIgnoreIfNotPresent" "false"
CkJsonObject_UpdateString $json "signers[i].tabs.signHereTabs[0].anchorUnits" "inches"

set sbJson [new_CkStringBuilder]

CkJsonObject_put_EmitCompact $json 0
CkJsonObject_EmitSb $json $sbJson

CkHttp_SetRequestHeader $http "Cache-Control" "no-cache"
CkHttp_SetRequestHeader $http "Accept" "application/json"

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

set url "https://demo.docusign.net/restapi/v2.1/accounts/{$accountId}/envelopes/{$envelopeId}/recipients"
# resp is a CkHttpResponse
set resp [CkHttp_PTextSb $http "POST" $url $sbJson "utf-8" "application/json" 0 0]
if {[CkHttp_get_LastMethodSuccess $http] == 0} then {
    puts [CkHttp_lastErrorText $http]
    delete_CkHttp $http
    delete_CkJsonObject $jsonToken
    delete_CkJsonObject $json
    delete_CkStringBuilder $sbJson
    exit
}

set jResp [new_CkJsonObject]

CkJsonObject_Load $jResp [CkHttpResponse_bodyStr $resp]
CkJsonObject_put_EmitCompact $jResp 0

puts "Response Body:"
puts [CkJsonObject_emit $jResp]

# If you get a 401 response status code, it's likely you need to refresh the DocuSign OAuth2 token).
set respStatusCode [CkHttpResponse_get_StatusCode $resp]
puts "Response Status Code = $respStatusCode"
if {$respStatusCode >= 400} then {
    puts "Response Header:"
    puts [CkHttpResponse_header $resp]
    puts "Failed."
    delete_CkHttpResponse $resp

    delete_CkHttp $http
    delete_CkJsonObject $jsonToken
    delete_CkJsonObject $json
    delete_CkStringBuilder $sbJson
    delete_CkJsonObject $jResp
    exit
}

delete_CkHttpResponse $resp

# 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

set recipientCount [CkJsonObject_stringOf $json "recipientCount"]
set i 0
set count_i [CkJsonObject_SizeOfArray $json "signers"]
while {$i < $count_i} {
    CkJsonObject_put_I $json $i
    set creationReason [CkJsonObject_stringOf $json "signers[i].creationReason"]
    set requireUploadSignature [CkJsonObject_stringOf $json "signers[i].requireUploadSignature"]
    set email [CkJsonObject_stringOf $json "signers[i].email"]
    set recipientId [CkJsonObject_stringOf $json "signers[i].recipientId"]
    set requireIdLookup [CkJsonObject_stringOf $json "signers[i].requireIdLookup"]
    set routingOrder [CkJsonObject_stringOf $json "signers[i].routingOrder"]
    set status [CkJsonObject_stringOf $json "signers[i].status"]
    set completedCount [CkJsonObject_stringOf $json "signers[i].completedCount"]
    set deliveryMethod [CkJsonObject_stringOf $json "signers[i].deliveryMethod"]
    set recipientType [CkJsonObject_stringOf $json "signers[i].recipientType"]
    set i [expr $i + 1]
}
set i 0
set count_i [CkJsonObject_SizeOfArray $json "agents"]
while {$i < $count_i} {
    CkJsonObject_put_I $json $i
    #    ...
    set i [expr $i + 1]
}
set i 0
set count_i [CkJsonObject_SizeOfArray $json "editors"]
while {$i < $count_i} {
    CkJsonObject_put_I $json $i
    #    ...
    set i [expr $i + 1]
}
set i 0
set count_i [CkJsonObject_SizeOfArray $json "intermediaries"]
while {$i < $count_i} {
    CkJsonObject_put_I $json $i
    #    ...
    set i [expr $i + 1]
}
set i 0
set count_i [CkJsonObject_SizeOfArray $json "carbonCopies"]
while {$i < $count_i} {
    CkJsonObject_put_I $json $i
    set email [CkJsonObject_stringOf $json "carbonCopies[i].email"]
    set recipientId [CkJsonObject_stringOf $json "carbonCopies[i].recipientId"]
    set requireIdLookup [CkJsonObject_stringOf $json "carbonCopies[i].requireIdLookup"]
    set routingOrder [CkJsonObject_stringOf $json "carbonCopies[i].routingOrder"]
    set status [CkJsonObject_stringOf $json "carbonCopies[i].status"]
    set completedCount [CkJsonObject_stringOf $json "carbonCopies[i].completedCount"]
    set deliveryMethod [CkJsonObject_stringOf $json "carbonCopies[i].deliveryMethod"]
    set recipientType [CkJsonObject_stringOf $json "carbonCopies[i].recipientType"]
    set i [expr $i + 1]
}
set i 0
set count_i [CkJsonObject_SizeOfArray $json "certifiedDeliveries"]
while {$i < $count_i} {
    CkJsonObject_put_I $json $i
    #    ...
    set i [expr $i + 1]
}
set i 0
set count_i [CkJsonObject_SizeOfArray $json "inPersonSigners"]
while {$i < $count_i} {
    CkJsonObject_put_I $json $i
    #    ...
    set i [expr $i + 1]
}
set i 0
set count_i [CkJsonObject_SizeOfArray $json "seals"]
while {$i < $count_i} {
    CkJsonObject_put_I $json $i
    #    ...
    set i [expr $i + 1]
}
set i 0
set count_i [CkJsonObject_SizeOfArray $json "witnesses"]
while {$i < $count_i} {
    CkJsonObject_put_I $json $i
    #    ...
    set i [expr $i + 1]
}

# 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"
# }
# 

delete_CkHttp $http
delete_CkJsonObject $jsonToken
delete_CkJsonObject $json
delete_CkStringBuilder $sbJson
delete_CkJsonObject $jResp