(SQL Server) 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 ActiveX Downloads ActiveX for 32-bit and 64-bit Windows

-- Important: See this note about string length limitations for strings returned by sp_OAMethod calls.
--
CREATE PROCEDURE ChilkatSample
AS
BEGIN
    DECLARE @hr int
    DECLARE @iTmp0 int
    -- Important: Do not use nvarchar(max).  See the warning about using nvarchar(max).
    DECLARE @sTmp0 nvarchar(4000)
    -- This example assumes the Chilkat API to have been previously unlocked.
    -- See Global Unlock Sample for sample code.

    DECLARE @http int
    -- Use "Chilkat_9_5_0.Http" for versions of Chilkat < 10.0.0
    EXEC @hr = sp_OACreate 'Chilkat.Http', @http OUT
    IF @hr <> 0
    BEGIN
        PRINT 'Failed to create ActiveX component'
        RETURN
    END

    -- Load a previously obtained OAuth2 access token.
    DECLARE @jsonToken int
    -- Use "Chilkat_9_5_0.JsonObject" for versions of Chilkat < 10.0.0
    EXEC @hr = sp_OACreate 'Chilkat.JsonObject', @jsonToken OUT

    DECLARE @success int
    EXEC sp_OAMethod @jsonToken, 'LoadFile', @success OUT, 'qa_data/tokens/docusign.json'
    IF @success = 0
      BEGIN
        EXEC sp_OAGetProperty @jsonToken, 'LastErrorText', @sTmp0 OUT
        PRINT @sTmp0
        EXEC @hr = sp_OADestroy @http
        EXEC @hr = sp_OADestroy @jsonToken
        RETURN
      END

    -- Adds the "Authorization: Bearer eyJ0eXAi.....UE8Kl_V8KroQ" header.
    EXEC sp_OAMethod @jsonToken, 'StringOf', @sTmp0 OUT, 'access_token'
    EXEC sp_OASetProperty @http, 'AuthToken', @sTmp0

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

    DECLARE @json int
    -- Use "Chilkat_9_5_0.JsonObject" for versions of Chilkat < 10.0.0
    EXEC @hr = sp_OACreate 'Chilkat.JsonObject', @json OUT

    DECLARE @i int
    SELECT @i = 0
    EXEC sp_OASetProperty @json, 'I', @i
    EXEC sp_OAMethod @json, 'UpdateString', @success OUT, 'carbonCopies[i].email', 'support@chilkatsoft.com'
    EXEC sp_OAMethod @json, 'UpdateString', @success OUT, 'carbonCopies[i].name', 'Chilkat Support'
    EXEC sp_OAMethod @json, 'UpdateString', @success OUT, 'carbonCopies[i].recipientId', '101'
    EXEC sp_OAMethod @json, 'UpdateNewObject', @success OUT, 'carbonCopies[i].tabs'
    SELECT @i = 0
    EXEC sp_OASetProperty @json, 'I', @i
    EXEC sp_OAMethod @json, 'UpdateString', @success OUT, 'signers[i].email', 'admin@chilkatsoft.com'
    EXEC sp_OAMethod @json, 'UpdateString', @success OUT, 'signers[i].name', 'Chilkat Admin'
    EXEC sp_OAMethod @json, 'UpdateString', @success OUT, 'signers[i].recipientId', '1'
    EXEC sp_OAMethod @json, 'UpdateString', @success OUT, 'signers[i].tabs.signHereTabs[0].anchorString', 'Please Sign Here'
    EXEC sp_OAMethod @json, 'UpdateString', @success OUT, 'signers[i].tabs.signHereTabs[0].anchorXOffset', '1'
    EXEC sp_OAMethod @json, 'UpdateString', @success OUT, 'signers[i].tabs.signHereTabs[0].anchorYOffset', '0'
    EXEC sp_OAMethod @json, 'UpdateString', @success OUT, 'signers[i].tabs.signHereTabs[0].anchorIgnoreIfNotPresent', 'false'
    EXEC sp_OAMethod @json, 'UpdateString', @success OUT, 'signers[i].tabs.signHereTabs[0].anchorUnits', 'inches'
    SELECT @i = @i + 1
    EXEC sp_OASetProperty @json, 'I', @i
    EXEC sp_OAMethod @json, 'UpdateString', @success OUT, 'signers[i].email', 'matt@chilkat.io'
    EXEC sp_OAMethod @json, 'UpdateString', @success OUT, 'signers[i].name', 'Matt'
    EXEC sp_OAMethod @json, 'UpdateString', @success OUT, 'signers[i].recipientId', '2'
    EXEC sp_OAMethod @json, 'UpdateString', @success OUT, 'signers[i].tabs.signHereTabs[0].anchorString', 'Please Also Sign Here'
    EXEC sp_OAMethod @json, 'UpdateString', @success OUT, 'signers[i].tabs.signHereTabs[0].anchorXOffset', '1'
    EXEC sp_OAMethod @json, 'UpdateString', @success OUT, 'signers[i].tabs.signHereTabs[0].anchorYOffset', '0'
    EXEC sp_OAMethod @json, 'UpdateString', @success OUT, 'signers[i].tabs.signHereTabs[0].anchorIgnoreIfNotPresent', 'false'
    EXEC sp_OAMethod @json, 'UpdateString', @success OUT, 'signers[i].tabs.signHereTabs[0].anchorUnits', 'inches'

    DECLARE @sbJson int
    -- Use "Chilkat_9_5_0.StringBuilder" for versions of Chilkat < 10.0.0
    EXEC @hr = sp_OACreate 'Chilkat.StringBuilder', @sbJson OUT

    EXEC sp_OASetProperty @json, 'EmitCompact', 0
    EXEC sp_OAMethod @json, 'EmitSb', @success OUT, @sbJson

    EXEC sp_OAMethod @http, 'SetRequestHeader', NULL, 'Cache-Control', 'no-cache'
    EXEC sp_OAMethod @http, 'SetRequestHeader', NULL, 'Accept', 'application/json'

    -- Use your own account ID here.
    EXEC sp_OAMethod @http, 'SetUrlVar', @success OUT, 'accountId', '7f3f65ed-5e87-418d-94c1-92499ddc8252'
    -- Use the envelope ID returned by DocuSign when creating the draft envelope).
    EXEC sp_OAMethod @http, 'SetUrlVar', @success OUT, 'envelopeId', 'cee4191c-f94e-4089-9d7c-8033685cbc1a'

    DECLARE @url nvarchar(4000)
    SELECT @url = 'https://demo.docusign.net/restapi/v2.1/accounts/{$accountId}/envelopes/{$envelopeId}/recipients'
    DECLARE @resp int
    EXEC sp_OAMethod @http, 'PTextSb', @resp OUT, 'POST', @url, @sbJson, 'utf-8', 'application/json', 0, 0
    EXEC sp_OAGetProperty @http, 'LastMethodSuccess', @iTmp0 OUT
    IF @iTmp0 = 0
      BEGIN
        EXEC sp_OAGetProperty @http, 'LastErrorText', @sTmp0 OUT
        PRINT @sTmp0
        EXEC @hr = sp_OADestroy @http
        EXEC @hr = sp_OADestroy @jsonToken
        EXEC @hr = sp_OADestroy @json
        EXEC @hr = sp_OADestroy @sbJson
        RETURN
      END

    DECLARE @jResp int
    -- Use "Chilkat_9_5_0.JsonObject" for versions of Chilkat < 10.0.0
    EXEC @hr = sp_OACreate 'Chilkat.JsonObject', @jResp OUT

    EXEC sp_OAGetProperty @resp, 'BodyStr', @sTmp0 OUT
    EXEC sp_OAMethod @jResp, 'Load', @success OUT, @sTmp0
    EXEC sp_OASetProperty @jResp, 'EmitCompact', 0


    PRINT 'Response Body:'
    EXEC sp_OAMethod @jResp, 'Emit', @sTmp0 OUT
    PRINT @sTmp0

    -- If you get a 401 response status code, it's likely you need to refresh the DocuSign OAuth2 token).
    DECLARE @respStatusCode int
    EXEC sp_OAGetProperty @resp, 'StatusCode', @respStatusCode OUT

    PRINT 'Response Status Code = ' + @respStatusCode
    IF @respStatusCode >= 400
      BEGIN

        PRINT 'Response Header:'
        EXEC sp_OAGetProperty @resp, 'Header', @sTmp0 OUT
        PRINT @sTmp0

        PRINT 'Failed.'
        EXEC @hr = sp_OADestroy @resp

        EXEC @hr = sp_OADestroy @http
        EXEC @hr = sp_OADestroy @jsonToken
        EXEC @hr = sp_OADestroy @json
        EXEC @hr = sp_OADestroy @sbJson
        EXEC @hr = sp_OADestroy @jResp
        RETURN
      END
    EXEC @hr = sp_OADestroy @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

    DECLARE @creationReason nvarchar(4000)

    DECLARE @requireUploadSignature nvarchar(4000)

    DECLARE @email nvarchar(4000)

    DECLARE @recipientId nvarchar(4000)

    DECLARE @requireIdLookup nvarchar(4000)

    DECLARE @routingOrder nvarchar(4000)

    DECLARE @status nvarchar(4000)

    DECLARE @completedCount nvarchar(4000)

    DECLARE @deliveryMethod nvarchar(4000)

    DECLARE @recipientType nvarchar(4000)

    DECLARE @recipientCount nvarchar(4000)
    EXEC sp_OAMethod @json, 'StringOf', @recipientCount OUT, 'recipientCount'
    SELECT @i = 0
    DECLARE @count_i int
    EXEC sp_OAMethod @json, 'SizeOfArray', @count_i OUT, 'signers'
    WHILE @i < @count_i
      BEGIN
        EXEC sp_OASetProperty @json, 'I', @i
        EXEC sp_OAMethod @json, 'StringOf', @creationReason OUT, 'signers[i].creationReason'
        EXEC sp_OAMethod @json, 'StringOf', @requireUploadSignature OUT, 'signers[i].requireUploadSignature'
        EXEC sp_OAMethod @json, 'StringOf', @email OUT, 'signers[i].email'
        EXEC sp_OAMethod @json, 'StringOf', @recipientId OUT, 'signers[i].recipientId'
        EXEC sp_OAMethod @json, 'StringOf', @requireIdLookup OUT, 'signers[i].requireIdLookup'
        EXEC sp_OAMethod @json, 'StringOf', @routingOrder OUT, 'signers[i].routingOrder'
        EXEC sp_OAMethod @json, 'StringOf', @status OUT, 'signers[i].status'
        EXEC sp_OAMethod @json, 'StringOf', @completedCount OUT, 'signers[i].completedCount'
        EXEC sp_OAMethod @json, 'StringOf', @deliveryMethod OUT, 'signers[i].deliveryMethod'
        EXEC sp_OAMethod @json, 'StringOf', @recipientType OUT, 'signers[i].recipientType'
        SELECT @i = @i + 1
      END
    SELECT @i = 0
    EXEC sp_OAMethod @json, 'SizeOfArray', @count_i OUT, 'agents'
    WHILE @i < @count_i
      BEGIN
        EXEC sp_OASetProperty @json, 'I', @i
        --    ...
        SELECT @i = @i + 1
      END
    SELECT @i = 0
    EXEC sp_OAMethod @json, 'SizeOfArray', @count_i OUT, 'editors'
    WHILE @i < @count_i
      BEGIN
        EXEC sp_OASetProperty @json, 'I', @i
        --    ...
        SELECT @i = @i + 1
      END
    SELECT @i = 0
    EXEC sp_OAMethod @json, 'SizeOfArray', @count_i OUT, 'intermediaries'
    WHILE @i < @count_i
      BEGIN
        EXEC sp_OASetProperty @json, 'I', @i
        --    ...
        SELECT @i = @i + 1
      END
    SELECT @i = 0
    EXEC sp_OAMethod @json, 'SizeOfArray', @count_i OUT, 'carbonCopies'
    WHILE @i < @count_i
      BEGIN
        EXEC sp_OASetProperty @json, 'I', @i
        EXEC sp_OAMethod @json, 'StringOf', @email OUT, 'carbonCopies[i].email'
        EXEC sp_OAMethod @json, 'StringOf', @recipientId OUT, 'carbonCopies[i].recipientId'
        EXEC sp_OAMethod @json, 'StringOf', @requireIdLookup OUT, 'carbonCopies[i].requireIdLookup'
        EXEC sp_OAMethod @json, 'StringOf', @routingOrder OUT, 'carbonCopies[i].routingOrder'
        EXEC sp_OAMethod @json, 'StringOf', @status OUT, 'carbonCopies[i].status'
        EXEC sp_OAMethod @json, 'StringOf', @completedCount OUT, 'carbonCopies[i].completedCount'
        EXEC sp_OAMethod @json, 'StringOf', @deliveryMethod OUT, 'carbonCopies[i].deliveryMethod'
        EXEC sp_OAMethod @json, 'StringOf', @recipientType OUT, 'carbonCopies[i].recipientType'
        SELECT @i = @i + 1
      END
    SELECT @i = 0
    EXEC sp_OAMethod @json, 'SizeOfArray', @count_i OUT, 'certifiedDeliveries'
    WHILE @i < @count_i
      BEGIN
        EXEC sp_OASetProperty @json, 'I', @i
        --    ...
        SELECT @i = @i + 1
      END
    SELECT @i = 0
    EXEC sp_OAMethod @json, 'SizeOfArray', @count_i OUT, 'inPersonSigners'
    WHILE @i < @count_i
      BEGIN
        EXEC sp_OASetProperty @json, 'I', @i
        --    ...
        SELECT @i = @i + 1
      END
    SELECT @i = 0
    EXEC sp_OAMethod @json, 'SizeOfArray', @count_i OUT, 'seals'
    WHILE @i < @count_i
      BEGIN
        EXEC sp_OASetProperty @json, 'I', @i
        --    ...
        SELECT @i = @i + 1
      END
    SELECT @i = 0
    EXEC sp_OAMethod @json, 'SizeOfArray', @count_i OUT, 'witnesses'
    WHILE @i < @count_i
      BEGIN
        EXEC sp_OASetProperty @json, 'I', @i
        --    ...
        SELECT @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"
    -- }
    -- 

    EXEC @hr = sp_OADestroy @http
    EXEC @hr = sp_OADestroy @jsonToken
    EXEC @hr = sp_OADestroy @json
    EXEC @hr = sp_OADestroy @sbJson
    EXEC @hr = sp_OADestroy @jResp


END
GO