Requesting a Signature via Email

This topic shows you how to request a signature on a document. The recipient receives an email notifying them that there is a document waiting to be signed. The recipient then clicks a link in the email which initiates the signing process.

Before You Begin

Make sure that you set up your DocuSign developer sandbox. If you don’t have a developer sandbox, an integrator key, and an authentication header, go to the QuickStart

This example uses legacy header authentication which is easier to use while learning the API but is not recommended for production applications. See Authentication Overview to learn more about your authentication options.

Step by Step Example

In this example you’ll send a PDF document to be signed to a recipient via email. The document will contain three tabs (fields):

  • a tab where the recipient can sign
  • a tab that records the signer’s printed name
  • a tab that records the date the document was signed

To accomplish this you will:

  • Prepare a PDF document to be sent through the DocuSign platform.
  • Create the signing request payload.
  • Send the request to sign the PDF document.
  • Sign the document you sent.

This example uses curl to make HTTP requests. If you prefer, you may find it more convenient to use a tool such as Postman. In your application you might use one of the client SDKs rather than making HTTP requests directly.

Get the Document to be Signed

In order to make it easier to follow this example, we’ll use a sample PDF file called Mutual_NDA.pdf. Remember that documents sent through the developer sandbox are not legally binding and have watermarks on them indicating they are tests.

You can find the sample PDF file at https://docs.docusign.com/assets/example_docs/Mutual_NDA.pdf. Download the file to the directory that you’ll use to issue the curl command.

Alternatively, you can download the file like this:

$ curl -s https://docs.docusign.com/assets/example_docs/Mutual_NDA.pdf > Mutual_NDA.pdf

Open Mutual_NDA.pdf in a PDF viewer. Search for the strings “signer1name”, “signer1sig”, and “signer1date”. You’ll notice that the search matches but that the text is not visible. These strings are regular text in the document. Their text color has been set to white, so they can’t be see in the document. But DocuSign can find them, and use them as anchor text to place the tabs (the signature, name, and date fields).

There are other ways to specify where tabs go in a document. For example, you could specify the (x, y) coordinates of a tab on a given page. But using anchor text is a more robust solution.

The signing tab will be located where the “signer1sig” text is in the document. The date signed tab will be located where the “signer1date” text is. And the “signer1name” text is where the full name tab appears.

In a moment you’ll learn how to associate the document with an envelope and how to user the anchor text to specify the tabs. First, you need to convert the PDF document into a format that DocuSign can work with.

Prepare the Document to Send Through DocuSign

Documents that you send through DocuSign must be base64-encoded. Use the base64 tool as shown. You will have a new file called Mutual_NDA.pdf.base64.

$ base64 Mutual_NDA.pdf -o Mutual_NDA.pdf.base64

Create the Envelope Definition

To create and send an envelope you’ll use the /envelopes endpoint. The body of this request is a fairly complex object called the envelope definition that you can specify as JSON or XML.

In this example you’ll use a ready-made request body. You can find it at https://docs.docusign.com/assets/quickstart/send_signing_request_by_email.json. Download the file to the directory that you’ll use to issue the curl command.

Alternatively, you can download the file:

curl https://docs.docusign.com/assets/quickstart/send_signing_request_by_email.json > send_signing_request_by_email.json

You can open the file send_signing_request_by_email.json in a text editor to see how it’s organized.

"documents": [
  {
    "documentBase64": "FILE1_BASE64",
    "documentId": "1",
    "fileExtension": "pdf",
    "name": "NDA.pdf"
  }
]

The documents section the documentBase64 contains the contents of the base64-converted version of the PDF file.

"recipients": {
  "signers": [
    {
      "email": "the_nda_signer@mailinator.com",
      "name": "Darlene Petersen",
      "recipientId": "1",
      "routingOrder": "1",
      "tabs": {
        "dateSignedTabs": [
          {
            "anchorString": "signer1date",
            "anchorYOffset": "-6",
            "fontSize": "Size12",
            "name": "Date Signed",
            "recipientId": "1",
            "tabLabel": "date_signed"
          }
        ]
      }
    }
  ]
}

The recipients field contains a signers field, which is an array of objects that list the name and email address of the person who will be receiving the document to sign. The tabs field in this object specifies where the tabs will appear.

Before you can use the this envelope definition, you should change the value of the documentBase64 field to the contents of the converted file. Use this command to do that easily.

sed -e "s/FILE1_BASE64/$(sed 's:/:\\/:g' Mutual_NDA.pdf.base64)/" send_signing_request_by_email.json > payload.json

Send the Signing Request

You now have a complete envelope definition in payload.json that contains:

  • The document to be signed.
  • The name and email address of the recipient.
    In payload.json the recipient is “Darlene Petersen” whose email address is the_nda_signer@mailinator.com.
  • The locations of the three tabs: signature, name, and date.
  • The status field is set to sent to indicate that DocuSign should send the signing request via email as when the HTTP request succeeds.

To create and send the envelope send a POST request to the envelopes endpoint.

$ curl -i -k -X POST -d @payload.json \
                      -H "Accept: application/json" \
                      -H "Content-Type: application/json" \
                      -H 'X-DocuSign-Authentication: { "Username":"developer@example.com",
                                                       "Password":"S3cre+p455w0Rd",
                                                       "IntegratorKey":"230546a7-9c55-40ad-8fbf-af205d5494ad"}' \
              https://demo.docusign.net/restapi/v2/accounts/1703061/envelopes

The response is initially 100 Continue, to indicate that DocuSign received the request, followed immediately by 201 Created.

HTTP/1.1 100 Continue

HTTP/1.1 201 Created
Cache-Control: no-cache
Content-Length: 195
Content-Type: application/json; charset=utf-8
X-RateLimit-Reset: 1464908400
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 994
Date: Thu, 02 Jun 2016 22:57:27 GMT
Strict-Transport-Security: max-age=31536000; includeSubDomains

{
  "envelopeId": "d1cf4bea-1b78-47ea-b372-746678e3679f",
  "uri": "/envelopes/d1cf4bea-1b78-47ea-b372-746678e3679f",
  "statusDateTime": "2016-06-02T22:57:27.8300000Z",
  "status": "sent"
}

The successful response includes an envelope ID and a URI that you can use to work with the envelope later.

Sign the Document You Sent.

Remember that the recipient’s address of the document you sent to be signed was the_nda_signer@mailinator.com.

Mailinator is a disposable email service. You can use it to send email to any address without registering it first. Keep in mind that anything you sent through it is available to anyone. Never send private information through Mailinator.

You can see what the recipient of a signing request gets by going the the_nda_signer’s mailbox on Mailinator: https://www.mailinator.com/inbox2.jsp?public_to=the_nda_signer.

View and sign the document you sent. You will see how the signature contains the recipient’s name (Darlene Petersen), and the name and date fields are filled automatically from the information in the envelope definition.

You will also receive an email at the address you used to create your developer sandbox, telling you that the document has been signed.

With the information in the response to the HTTP request, your application can monitor the state of the signature request and take action when the state changes.