QuickStart

This QuickStart shows you how to:

The examples here and later on use curl to show how 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.

Create Your Developer Sandbox

Developer sandboxes are completely free, they never expire, and you get access to enterprise level features. Create your developer sandbox.

After creating your sandbox account, you will get an email to confirm your account. Confirm your account, and set up a password for the sandbox. Once you do that you’ll be logged in to your developer sandbox.

Developer sandbox accounts operate in the DocuSign demo environment. Documents sent through this environment are not legally binding and have watermarks indicating they are tests.

Generate an Integrator Key

Your integrator key (also known as a client id) is a unique identifier that authenticates your account with the DocuSign API. To create yours, log in to your developer sandbox then follow these steps:

  1. Go to DocuSign Admin

    Select the Go to Admin link in the account settings drop-down menu in the upper left corner. Alternatively, you can go to this address https://admindemo.docusign.com.

  2. In DocuSign Admin, click API and Keys in the left navigation panel.

  3. Click ADD INTEGRATOR KEY.

  4. Add a description for your application. You can add a link to your privacy policy and your terms of use, or you can do it later. For the time being ignore the This is a mobile app checkbox.

  5. Click ADD. A new modal dialog opens to let you add additional information if you’re using one of the OAuth authentication flows. You’ll be using a simpler form of authentication for this QuickStart, so click CANCEL.

Your integrator key is a string that appears in the My Integrator Keys section of DocuSign Admin. It looks something like this: 230546a7-9c55-40ad-8fbf-af205d5494ad. You’ll use this key to authenticate your API requests.

Authenticate and Get Your Base URL

This and later examples use 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.

Your first call to the DocuSign REST API is to the /login_information endpoint to get account information and the baseUrl. You’ll use the baseURL to make all the subsequent API requests. and to obtain the URL that you’ll use to make more requests.

$ curl -i -H 'X-DocuSign-Authentication:
              { "Username":"developer@example.com",
                "Password":"S3cre+p455w0Rd",
                "IntegratorKey":"230546a7-9c55-40ad-8fbf-af205d5494ad" }'\
          https://demo.docusign.net/restapi/v2/login_information

The response will look similar to this:

{
  "loginAccounts": [
    {
      "name": "Dev Eloper",
      "accountId": "1703061",
      "baseUrl": "https://demo.docusign.net/restapi/v2/accounts/1703061",
      "isDefault": "true",
      "userName": "Dev Eloper",
      "userId": "1470ff66-f92e-4e8e-ab81-8c46f140da37",
      "email": "developer@example.com",
      "siteDescription": ""
    }
  ]
}

Since we’re using legacy header authentication, every request must include an X-DocuSign-Authentication header to authenticate the request. The value of this header should be a JSON string that looks like this:

{
  "Username":"developer@example.com",
  "Password":"S3cre+p455w0Rd",
  "IntegratorKey":"your integrator key"
}

The result contains information about all of the login accounts associated with your account. The most useful value to you right now is the baseUrl. This is the URL that you’ll use for all your requests. In the production environment your baseUrl will contain the address of a production server.

Make a Request to the REST API

Armed with your baseUrl and authentication header, you’re ready to start creating envelopes and sending signature requests. To send a signature request for a document you need to call the Envelopes: create method with a POST request to the /envelopes endpoint.

POST https://demo.docusign.net/restapi/v2/accounts/1703061/envelopes

Accept: application/json
Content-Type: application/json
X-DocuSign-Authentication:
              { "Username":"developer@example.com",
                "Password":"S3cre+p455w0Rd",
                "IntegratorKey":"230546a7-9c55-40ad-8fbf-af205d5494ad" }

{
	"emailSubject": "DocuSign REST API Quickstart Sample",
	"emailBlurb": "Shows how to create and send an envelope from a document.",
	"recipients": {
		"signers": [{
			"email": "sally.smith@example.com",
			"name": "Sally Smith",
			"recipientId": "1",
			"routingOrder": "1"
		}]
	},
	"documents": [{
		"documentId": "1",
		"name": "test.pdf",
		"documentBase64": "<base64 encoded document bytes>"
	}],
	"status": "sent"
}

A successful response looks like:

{
  "envelopeId": "a9d3db9a-1a88-2d0c-bba5-bee60f393aef",
  "uri": "/envelopes/a9d3db9a-1a88-2d0c-bba5-bee60f393aef",
  "statusDateTime": "2016-07-09T04:11:40.9079767Z",
  "status": "sent"
}

You can use the REST API Explorer to test the Envelopes: create API in real time.

Since we are not defining any tabs in the above request the request uses the free-form signing workflow in which the recipient decides where to sign the document.

Since the status property is set to sent in this example, the envelope will be sent immediately. If the status was created, the envelope would be saved as a draft to be sent later.

XML Formatted Requests and Responses

DocuSign’s REST API also accepts XML-formatted requests. To render requests and responses in XML add the following headers to your requests:

  • Accept: application/xml
  • Content-Type: application/xml

Alternatively you can also append .xml to each endpoint you access to force XML format.

You can also supply the X-DocuSign-Authentication header in XML. The XML in this example is formatted to be easier to read. The response is actually rendered as an unformatted string.

To create and send an envelope (i.e. signature request) through the REST API using XML format make the following http POST request:

POST https://demo.docusign.net/restapi/v2/accounts/1703061/envelopes

Accept: application/xml
Content-Type: application/xml
X-DocuSign-Authentication:
           <DocuSignCredentials>
             <Username>developer@example.com</Username>
             <Password>S3cre+p455w0Rd</Password>
             <IntegratorKey>230546a7-9c55-40ad-8fbf-af205d5494ad</IntegratorKey>
           </DocuSignCredentials>

<envelopeDefinition xmlns="http://www.docusign.com/restapi">
  <emailSubject>DocuSign REST API Quickstart sample</emailSubject>
  <emailSubject>This example uses xml</emailSubject>
  <documents>
    <document>
      <documentId>1</documentId>
      <name>sample.pdf</name>
      <documentBase64>base64 encoded document bytes</documentBase64>
    </document>
  </documents>
  <recipients>
    <signers>
      <signer>
        <name>Sally Smith</name>
        <email>sally.smith@email.com</email>
        <recipientId>1</recipientId>
        <routingOrder>1</routingOrder>
      </signer>
    </signers>
  </recipients>
  <status>sent</status>
</envelopeDefinition>

A successful response in XML looks like:

<envelopeSummary xmlns="http://www.docusign.com/restapi">
  <envelopeId>a9d3db9a-1a88-2d0c-bba5-bee60f393aef</envelopeId>
  <status>sent</status>
  <statusDateTime>2016-07-09T02:58:56.4915156Z</statusDateTime>
  <uri>/envelopes/a9d3db9a-1a88-2d0c-bba5-bee60f393aef</uri>
</envelopeSummary>