Dropbox Sign API Quickstart

This quickstart will walk you through sending your first Dropbox Sign API request. Further down, we will also walk you through sending your first eSignature request using our API.

This is mostly an interactive guide, meaning you will find embedded consoles along the way, which will allow you to send API requests without having to navigate away from the guide.

You will also find code examples, which can be copied as-is and used in your development environment.

The Dropbox Sign API at a Glance

The Dropbox Sign API powers eSignature functionality that can be built into your applications. You can enable electronic signatures for your users with non-embedded or embedded signature flows.

The endpoints are organized around specific classes. You can see the full range of classes and functionality by clicking the dropdown below:

Things to know

• The difference between Embedded and Non-Embedded
• How we charge
• Testing the Dropbox Sign API
• Rate Limits
• Embedded Testing Tool

Sending an API Request

Let's send your first API request!

Prerequisites - API Request

You'll need the following:

Calling the API

There are two ways the documentation will help you send API requests:

• Using the Try it console to send API requests directly from within the documentation.
• Copying the code examples to send API requests using your development environment.

That functionality is offered across all endpoints.

Using the Try it Console

This approach is great for exploration, discovery, and testing different combinations of parameters without the need to set up your own coding environment.

About Try it Console: You can use the Try it console, whenever present across the developer documentation, for most endpoints. You can also resend requests using the same instance, there's no need to refresh or navigate away from the documentation.

Using Code Examples

This approach is great for building out your integration. Especially if you're using the official SDKs.

Step 1. Grab your API Key from the API Settings page.

Step 2. Copy the code from the cURL tab below for the Get Account endpoint:

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

// Configure HTTP basic authorization: api_key
$config->setUsername("YOUR_API_KEY");

// or, configure Bearer (JWT) authorization: oauth2
// $config->setAccessToken("YOUR_ACCESS_TOKEN");

$accountApi = new Dropbox\Sign\Api\AccountApi($config);

try {
    $result = $accountApi->accountGet(null, 'jack@example.com');
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

Step 3. Combine your API key with the cURL example and send the command from your terminal.

About Code Examples: Every endpoint in our API Reference documentation contains code example for cURL along with all 6 officially supported SDKs.

Sending Signature Requests

The ability to create signature requests for your users to sign is a central concept of building with the Dropbox Sign API. All features, big and small, are connected by a shared need: allowing users to sign documents.

Users have two ways they can sign and complete signature requests:

• On dropboxsign.com — Non-embedded Signing flows.
• On your app (or website) in an iFrame — Embedded Signing flows.

You can fully test both signing flows by working through the sections below.

Prerequisites - Signature Requests

You'll need the following:

Non-embedded Signing

In non-embedded signing flows, you send the signature request via API and Dropbox Sign handles the rest. In this model, we notify the signer(s) via email, they follow a hyperlink, and we collect their eSignature on a Dropbox Sign-owned web page.

This section contains three main parts:

1. Sending a Signature Request
2. Signing the document to complete the Signature Request
3. Checking the status of the Signature Request

Step 1: Send Signature Request

Follow the steps below using the Try it console.

1. Paste your API Key into the Security tab.
2. Open the Body tab and inspect the request payload.
3. Replace the first signer's email_address and name values with your own test data — make sure you have access to the email address entered.
4. Add a metadata property to the payload with a custom key-value pair. Like this: "demo": "Hi from the demo"
5. Add, edit or remove parameters in the payload as you wish — ensuring required parameters are included though.
6. Press Send to send your signature request!

Want to try testing in your own environment? No problem, you can find code examples below to send cURL requests from your terminal or using one of our official SDKs:

1. Grab your API Key from the API Settings page.
2. Copy the code from the tab of your language of choice below for the Send Signature Request endpoint.
3. Use your API key and add or edit parameters to the copied code example and send the request.

Step 2: Complete the Signature Request

1. Check your email
2. Click on the "REVIEW AND SIGN" button
3. Sign and complete the signature request

Step 3: Check Signature Request Status

Let's check the status of the signature request by sending an API request to the Get Signature Request endpoint.

1. Paste your API Key into the Security tab once again.
2. Open the Parameters tab and paste the signature_request_id obtained in the previous step.
3. Press Send to send your request!

To continue testing in your own environment find the code example for the language of your choice below:

1. Grab your API Key from the API Settings page.
2. Copy the corresponding code example for the Get Signature Request endpoint.
3. Use your API key and add or edit parameters to the copied code example and send the request.

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

// Configure HTTP basic authorization: api_key
$config->setUsername("YOUR_API_KEY");

// or, configure Bearer (JWT) authorization: oauth2
// $config->setAccessToken("YOUR_ACCESS_TOKEN");

$signatureRequestApi = new Dropbox\Sign\Api\SignatureRequestApi($config);

$signatureRequestId = "fa5c8a0b0f492d768749333ad6fcc214c111e967";

try {
    $result = $signatureRequestApi->signatureRequestGet($signatureRequestId);
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

Embedded Signing

In embedded signing flows, Dropbox Sign is providing the eSign technology via API, but you're embedding the signing experience into your app or website. Your user signs and completes documents without ever leaving the surface you own.

In this model, all email notifications from Dropbox Sign are muted. You (the developer) are responsible for managing your user's notifications directly by consuming webhooks from Dropbox Sign Events.

This section contains three main parts:

1. Creating an Embedded Signature Request
2. Generating an Embedded Sign URL using a signer's unique signature_id
3. Loading the document in our Embedded Testing Tool, or your own app, using a sign_url
4. Signing the document to complete the Embedded Signature Request

Step 1: Create Embedded Signature Request

Follow the steps below using the Try it console.

1. Paste your API Key into the Security tab.
2. Open the Body tab and inspect the request payload.
3. Replace the client_id value with your own API App's Client ID.
4. Replace the first signer's email_address and name values with your own test data.
5. Add a metadata property to the payload with a custom key-value pair. Like this: "demo": "Hi from the demo"
6. Add, edit or remove parameters in the payload as you wish — ensuring required parameters are included though.
7. Press Send to send your signature request!

Want to try testing in your own environment? No problem, you can find code examples below to send cURL requests from your terminal or using one of our official SDKs:

1. Grab your API Key from the API Settings page.
2. Copy the code from the tab of your language of choice below for the Create Embedded Signature Request endpoint.
3. Use your API key and add or edit parameters to the copied code example and send the request.

Step 2: Generate a Sign URL

Let's generate a Sign URL by sending an API request to the Get Embedded Sign URL endpoint.

1. Paste your API Key into the Security tab once again.
2. Open the Parameters tab and paste the signature_id obtained in the previous step.
3. Press Send to send your request!

To continue testing in your own environment find the code example for the language of your choice below:

1. Grab your API Key from the API Settings page.
2. Copy the corresponding code example for the Get Embedded Sign URL endpoint.
3. Use your API key and add or edit parameters to the copied code example and send the request.

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

// Configure HTTP basic authorization: api_key
$config->setUsername("YOUR_API_KEY");

// or, configure Bearer (JWT) authorization: oauth2
// $config->setAccessToken("YOUR_ACCESS_TOKEN");

$embeddedApi = new Dropbox\Sign\Api\EmbeddedApi($config);

$signatureId = "50e3542f738adfa7ddd4cbd4c00d2a8ab6e4194b";

try {
    $result = $embeddedApi->embeddedSignUrl($signatureId);
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

Step 3: Load the Document in Our Embedded Testing Tool

1. Navigate to the Embedded Testing Tool.
2. Paste your API App's Client ID in the Client ID field.
3. Paste the sign_url in the Embedded URL field.
4. Click Launch Embedded button.

Step 4: Complete the Signature Request

With the document loaded in our Embedded Testing Tool, or your web app, go ahead and complete the signature request.

Client Side Library

We provide a client-side library that handles the authorization and display of the embedded request using an iFrame. You can take advantage of this library to make implementation easier.

For more details on how to use it, take a look at the Client Side section in one of our embedded workflows walkthroughs.

Next Steps

Fantastic job! By now, you should have a pretty good idea of how to interact with the Dropbox Sign API and implement it in a way that will fit your business needs.

We hope you've enjoyed the content and happy coding!

Resources and Tips

Most of the resources we would recommend you familiarize yourself with are:

• API Dashboard
• Events & Callbacks
• App Approval Overview
• Official Dropbox Sign SDKs
• Client Side Library How-to

Getting Help

We warmly welcome your feedback, feature requests, and bug reports!