# Non-Embedded Signing
> Find out how to send and retrieve signature requests, check their status, and download completed documents using the Dropbox Sign API.
# Signature Request Walkthrough
There are several ways to send a signature request using the Dropbox Sign API. The method you may want to use will depend on your use case. Take a look at the different options we offer to decide which scenario fits your needs.
## Scenarios
How do you plan on creating your signature requests?
You provide the files to create the request and we add a signature page for the signers to sign.
Setup a template on hellosign.com and reuse it with custom data when sending signature requests.
You provide the files and tell us exactly where form fields go on them. No signature page is added in this case.
### Using Files
This is the simplest way to create a signature request, attach the file(s) along with signer details and you're all set. A signature page will be appended at the end of your documents with a signature field for each signer involved.
This will send a signature request to Jack and Jill. Both will receive an email with a link to sign the request. The link will take them to a page where they can review the document before adding their signatures onto the signature page.
The `signature_request_id` field, found in the response object, allows you to keep track of the request status as shown in the [signature request status](#retrieving-signature-status) section. You can find more details about the [Signature Request](/api/signature-request) object on the [API reference page](/api/api-reference-welcome).
### Using Templates
If you need to send signature requests with the same documents often and need to have them filled in specific places, then using templates make perfect sense. This way, you save yourself the trouble of uploading the document files everytime and get to decide where the signers should fill in information.
Templates allow you to specify form fields (text, check boxes, signatures, etc...) that the signers should fill. But it also offers the possibilty to define "custom fields" that will be filled when the request gets sent via the API and will be shown to the signers.
Visit our [template walkthrough](/docs/walkthroughs/templates) if you're not familiar with templates and how to use them with the API.
This will send a signature request to George. George will receive an email with a link to sign the request. The link will take them to a page where they can review the document and fill out the required fields.
The `signature_request_id` field, found in the response object, allows you to keep track of the request status as shown in the [signature request status](#retrieving-signature-status) section. You can find more details about the [Signature Request](/api/signature-request) object on the [API reference page](/api/api-reference-welcome).
### Using Files and Form Fields
Warning: Due to a bug, the form\_fields\_per\_document parameter only supports two-dimensional arrays right now. We're testing a fix right now. You can read more here: Using Form Fields per Document.
If you need to send documents with changing content but the same form fields, we have a better alternative than using templates. Rather than creating a large number of templates to cover all the variations, you can create one single template and retrieve the coordinates of the associated form fields. With that information, you can provide the list of form fields and their coordinates when sending the signature request via the API.
Note:Text Tags are a much easier way to handle this scenario as they allow you to place tags in the document that will be converted to components when the request is sent.
This following request will create a signature request for two signers. On the first document (NDA), there will be a signature field and a date field for the signer. No form fields will be present on the second document.
For more information about form fields and their attributes, see `form_fields` in Templates on the [API reference page](/api/api-reference-welcome).
## Retrieving Signature Status
There are 2 ways get the status of a document. The preferred method is to provide a callback url which we'll post events to. The option to poll the API is also available but it's impractical in most situations since signers may take a while to view and sign your documents.
**Webhooks (preferred)**
Read our documentation about [Dropbox Sign Events](/docs/guides/events-and-callbacks/overview) to get a better understanding of how webhooks work with your account and apps.
**Polling**
If you poll, any frequency you choose has disadvantages, either having to make thousands of requests per signature request over a day or two or making fewer requests and having more time pass between the signature request completion and your system finding out about it. Webhooks solve both of these problems.
**Checking the status of a Signature Request**
```cURL cURL
curl -X GET 'https://api.hellosign.com/v3/signature_request/{signature_request_id}' \
-u 'YOUR_API_KEY:'
```
```php PHP maxLines=0
setUsername("YOUR_API_KEY");
// $config->setAccessToken("YOUR_ACCESS_TOKEN");
try {
$response = (new Dropbox\Sign\Api\SignatureRequestApi(config: $config))->signatureRequestGet(
signature_request_id: "fa5c8a0b0f492d768749333ad6fcc214c111e967",
);
print_r($response);
} catch (Dropbox\Sign\ApiException $e) {
echo "Exception when calling SignatureRequestApi#signatureRequestGet: {$e->getMessage()}";
}
```
```csharp C# maxLines=0
using System;
using System.Collections.Generic;
using System.IO;
using System.Text.Json;
using Dropbox.Sign.Api;
using Dropbox.Sign.Client;
using Dropbox.Sign.Model;
namespace Dropbox.SignSandbox;
public class SignatureRequestGetExample
{
public static void Run()
{
var config = new Configuration();
config.Username = "YOUR_API_KEY";
// config.AccessToken = "YOUR_ACCESS_TOKEN";
try
{
var response = new SignatureRequestApi(config).SignatureRequestGet(
signatureRequestId: "fa5c8a0b0f492d768749333ad6fcc214c111e967"
);
Console.WriteLine(response);
}
catch (ApiException e)
{
Console.WriteLine("Exception when calling SignatureRequestApi#SignatureRequestGet: " + e.Message);
Console.WriteLine("Status Code: " + e.ErrorCode);
Console.WriteLine(e.StackTrace);
}
}
}
```
```typescript TypeScript
import * as fs from 'fs';
import api from "@dropbox/sign"
import models from "@dropbox/sign"
const apiCaller = new api.SignatureRequestApi();
apiCaller.username = "YOUR_API_KEY";
// apiCaller.accessToken = "YOUR_ACCESS_TOKEN";
apiCaller.signatureRequestGet(
"fa5c8a0b0f492d768749333ad6fcc214c111e967", // signatureRequestId
).then(response => {
console.log(response.body);
}).catch(error => {
console.log("Exception when calling SignatureRequestApi#signatureRequestGet:");
console.log(error.body);
});
```
```java Java
package com.dropbox.sign_sandbox;
import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.JSON;
import com.dropbox.sign.model.*;
import java.io.File;
import java.math.BigDecimal;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
public class SignatureRequestGetExample
{
public static void main(String[] args)
{
var config = Configuration.getDefaultApiClient();
((HttpBasicAuth) config.getAuthentication("api_key")).setUsername("YOUR_API_KEY");
// ((HttpBearerAuth) config.getAuthentication("oauth2")).setBearerToken("YOUR_ACCESS_TOKEN");
try
{
var response = new SignatureRequestApi(config).signatureRequestGet(
"fa5c8a0b0f492d768749333ad6fcc214c111e967" // signatureRequestId
);
System.out.println(response);
} catch (ApiException e) {
System.err.println("Exception when calling SignatureRequestApi#signatureRequestGet");
System.err.println("Status code: " + e.getCode());
System.err.println("Reason: " + e.getResponseBody());
System.err.println("Response headers: " + e.getResponseHeaders());
e.printStackTrace();
}
}
}
```
```ruby Ruby
require "json"
require "dropbox-sign"
Dropbox::Sign.configure do |config|
config.username = "YOUR_API_KEY"
# config.access_token = "YOUR_ACCESS_TOKEN"
end
begin
response = Dropbox::Sign::SignatureRequestApi.new.signature_request_get(
"fa5c8a0b0f492d768749333ad6fcc214c111e967", # signature_request_id
)
p response
rescue Dropbox::Sign::ApiError => e
puts "Exception when calling SignatureRequestApi#signature_request_get: #{e}"
end
```
```python Python
import json
from datetime import date, datetime
from pprint import pprint
from dropbox_sign import ApiClient, ApiException, Configuration, api, models
configuration = Configuration(
username="YOUR_API_KEY",
# access_token="YOUR_ACCESS_TOKEN",
)
with ApiClient(configuration) as api_client:
try:
response = api.SignatureRequestApi(api_client).signature_request_get(
signature_request_id="fa5c8a0b0f492d768749333ad6fcc214c111e967",
)
pprint(response)
except ApiException as e:
print("Exception when calling SignatureRequestApi#signature_request_get: %s\n" % e)
```
## Retrieving Documents
The Dropbox Sign API can be used to download files (documents) in several different formats. Those formats include:
* A binary file
* A hyperlink to a downloadable file
* A data uri (base64 encoded string)
### Download Files
You can either download a single PDF document or separate pages in a zip file. Either option will contain all the signatures and information that signers have added so far.
```cURL cURL
curl -X GET 'https://api.hellosign.com/v3/signature_request/files/{signature_request_id}?file_type=pdf' \
-u 'YOUR_API_KEY:' \
--output downloaded_document.pdf
```
```php PHP
setUsername("YOUR_API_KEY");
// $config->setAccessToken("YOUR_ACCESS_TOKEN");
try {
$response = (new Dropbox\Sign\Api\SignatureRequestApi(config: $config))->signatureRequestFiles(
signature_request_id: "fa5c8a0b0f492d768749333ad6fcc214c111e967",
file_type: "pdf",
);
copy($response->getRealPath(), __DIR__ . '/file_response');
} catch (Dropbox\Sign\ApiException $e) {
echo "Exception when calling SignatureRequestApi#signatureRequestFiles: {$e->getMessage()}";
}
```
```csharp C#
using System;
using System.Collections.Generic;
using System.IO;
using System.Text.Json;
using Dropbox.Sign.Api;
using Dropbox.Sign.Client;
using Dropbox.Sign.Model;
namespace Dropbox.SignSandbox;
public class SignatureRequestFilesExample
{
public static void Run()
{
var config = new Configuration();
config.Username = "YOUR_API_KEY";
// config.AccessToken = "YOUR_ACCESS_TOKEN";
try
{
var response = new SignatureRequestApi(config).SignatureRequestFiles(
signatureRequestId: "fa5c8a0b0f492d768749333ad6fcc214c111e967",
fileType: "pdf"
);
var fileStream = File.Create("./file_response");
response.Seek(0, SeekOrigin.Begin);
response.CopyTo(fileStream);
fileStream.Close();
}
catch (ApiException e)
{
Console.WriteLine("Exception when calling SignatureRequestApi#SignatureRequestFiles: " + e.Message);
Console.WriteLine("Status Code: " + e.ErrorCode);
Console.WriteLine(e.StackTrace);
}
}
}
```
```typescript TypeScript
import * as fs from 'fs';
import api from "@dropbox/sign"
import models from "@dropbox/sign"
const apiCaller = new api.SignatureRequestApi();
apiCaller.username = "YOUR_API_KEY";
// apiCaller.accessToken = "YOUR_ACCESS_TOKEN";
apiCaller.signatureRequestFiles(
"fa5c8a0b0f492d768749333ad6fcc214c111e967", // signatureRequestId
"pdf", // fileType
).then(response => {
fs.createWriteStream('./file_response').write(response.body);
}).catch(error => {
console.log("Exception when calling SignatureRequestApi#signatureRequestFiles:");
console.log(error.body);
});
```
```java Java
package com.dropbox.sign_sandbox;
import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.JSON;
import com.dropbox.sign.model.*;
import java.io.File;
import java.math.BigDecimal;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
public class SignatureRequestFilesExample
{
public static void main(String[] args)
{
var config = Configuration.getDefaultApiClient();
((HttpBasicAuth) config.getAuthentication("api_key")).setUsername("YOUR_API_KEY");
// ((HttpBearerAuth) config.getAuthentication("oauth2")).setBearerToken("YOUR_ACCESS_TOKEN");
try
{
var response = new SignatureRequestApi(config).signatureRequestFiles(
"fa5c8a0b0f492d768749333ad6fcc214c111e967", // signatureRequestId
"pdf" // fileType
);
response.renameTo(new File("./file_response"));
} catch (ApiException e) {
System.err.println("Exception when calling SignatureRequestApi#signatureRequestFiles");
System.err.println("Status code: " + e.getCode());
System.err.println("Reason: " + e.getResponseBody());
System.err.println("Response headers: " + e.getResponseHeaders());
e.printStackTrace();
}
}
}
```
```ruby Ruby
require "json"
require "dropbox-sign"
Dropbox::Sign.configure do |config|
config.username = "YOUR_API_KEY"
# config.access_token = "YOUR_ACCESS_TOKEN"
end
begin
response = Dropbox::Sign::SignatureRequestApi.new.signature_request_files(
"fa5c8a0b0f492d768749333ad6fcc214c111e967", # signature_request_id
{
file_type: "pdf",
},
)
FileUtils.cp(response.path, "./file_response")
rescue Dropbox::Sign::ApiError => e
puts "Exception when calling SignatureRequestApi#signature_request_files: #{e}"
end
```
```python Python
import json
from datetime import date, datetime
from pprint import pprint
from dropbox_sign import ApiClient, ApiException, Configuration, api, models
configuration = Configuration(
username="YOUR_API_KEY",
# access_token="YOUR_ACCESS_TOKEN",
)
with ApiClient(configuration) as api_client:
try:
response = api.SignatureRequestApi(api_client).signature_request_files(
signature_request_id="fa5c8a0b0f492d768749333ad6fcc214c111e967",
file_type="pdf",
)
open("./file_response", "wb").write(response.read())
except ApiException as e:
print("Exception when calling SignatureRequestApi#signature_request_files: %s\n" % e)
```
### Download Files as Data Uri
```cURL cURL
curl -X GET 'https://api.hellosign.com/v3/signature_request/files_as_data_uri/{signature_request_id}' \
-u 'YOUR_API_KEY:'
```
```php PHP
setUsername("YOUR_API_KEY");
// $config->setAccessToken("YOUR_ACCESS_TOKEN");
try {
$response = (new Dropbox\Sign\Api\SignatureRequestApi(config: $config))->signatureRequestFilesAsDataUri(
signature_request_id: "fa5c8a0b0f492d768749333ad6fcc214c111e967",
);
print_r($response);
} catch (Dropbox\Sign\ApiException $e) {
echo "Exception when calling SignatureRequestApi#signatureRequestFilesAsDataUri: {$e->getMessage()}";
}
```
```csharp C#
using System;
using System.Collections.Generic;
using System.IO;
using System.Text.Json;
using Dropbox.Sign.Api;
using Dropbox.Sign.Client;
using Dropbox.Sign.Model;
namespace Dropbox.SignSandbox;
public class SignatureRequestFilesAsDataUriExample
{
public static void Run()
{
var config = new Configuration();
config.Username = "YOUR_API_KEY";
// config.AccessToken = "YOUR_ACCESS_TOKEN";
try
{
var response = new SignatureRequestApi(config).SignatureRequestFilesAsDataUri(
signatureRequestId: "fa5c8a0b0f492d768749333ad6fcc214c111e967"
);
Console.WriteLine(response);
}
catch (ApiException e)
{
Console.WriteLine("Exception when calling SignatureRequestApi#SignatureRequestFilesAsDataUri: " + e.Message);
Console.WriteLine("Status Code: " + e.ErrorCode);
Console.WriteLine(e.StackTrace);
}
}
}
```
```typescript TypeScript
import * as fs from 'fs';
import api from "@dropbox/sign"
import models from "@dropbox/sign"
const apiCaller = new api.SignatureRequestApi();
apiCaller.username = "YOUR_API_KEY";
// apiCaller.accessToken = "YOUR_ACCESS_TOKEN";
apiCaller.signatureRequestFilesAsDataUri(
"fa5c8a0b0f492d768749333ad6fcc214c111e967", // signatureRequestId
).then(response => {
console.log(response.body);
}).catch(error => {
console.log("Exception when calling SignatureRequestApi#signatureRequestFilesAsDataUri:");
console.log(error.body);
});
```
```java Java
package com.dropbox.sign_sandbox;
import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.JSON;
import com.dropbox.sign.model.*;
import java.io.File;
import java.math.BigDecimal;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
public class SignatureRequestFilesAsDataUriExample
{
public static void main(String[] args)
{
var config = Configuration.getDefaultApiClient();
((HttpBasicAuth) config.getAuthentication("api_key")).setUsername("YOUR_API_KEY");
// ((HttpBearerAuth) config.getAuthentication("oauth2")).setBearerToken("YOUR_ACCESS_TOKEN");
try
{
var response = new SignatureRequestApi(config).signatureRequestFilesAsDataUri(
"fa5c8a0b0f492d768749333ad6fcc214c111e967" // signatureRequestId
);
System.out.println(response);
} catch (ApiException e) {
System.err.println("Exception when calling SignatureRequestApi#signatureRequestFilesAsDataUri");
System.err.println("Status code: " + e.getCode());
System.err.println("Reason: " + e.getResponseBody());
System.err.println("Response headers: " + e.getResponseHeaders());
e.printStackTrace();
}
}
}
```
```ruby Ruby
require "json"
require "dropbox-sign"
Dropbox::Sign.configure do |config|
config.username = "YOUR_API_KEY"
# config.access_token = "YOUR_ACCESS_TOKEN"
end
begin
response = Dropbox::Sign::SignatureRequestApi.new.signature_request_files_as_data_uri(
"fa5c8a0b0f492d768749333ad6fcc214c111e967", # signature_request_id
)
p response
rescue Dropbox::Sign::ApiError => e
puts "Exception when calling SignatureRequestApi#signature_request_files_as_data_uri: #{e}"
end
```
```python Python
import json
from datetime import date, datetime
from pprint import pprint
from dropbox_sign import ApiClient, ApiException, Configuration, api, models
configuration = Configuration(
username="YOUR_API_KEY",
# access_token="YOUR_ACCESS_TOKEN",
)
with ApiClient(configuration) as api_client:
try:
response = api.SignatureRequestApi(api_client).signature_request_files_as_data_uri(
signature_request_id="fa5c8a0b0f492d768749333ad6fcc214c111e967",
)
pprint(response)
except ApiException as e:
print("Exception when calling SignatureRequestApi#signature_request_files_as_data_uri: %s\n" % e)
```
### Download Files as File Url
```cURL cURL
curl -X GET 'https://api.hellosign.com/v3/signature_request/files_as_file_url/{signature_request_id}' \
-u 'YOUR_API_KEY:'
```
```php PHP
setUsername("YOUR_API_KEY");
// $config->setAccessToken("YOUR_ACCESS_TOKEN");
try {
$response = (new Dropbox\Sign\Api\SignatureRequestApi(config: $config))->signatureRequestFilesAsFileUrl(
signature_request_id: "fa5c8a0b0f492d768749333ad6fcc214c111e967",
force_download: 1,
);
print_r($response);
} catch (Dropbox\Sign\ApiException $e) {
echo "Exception when calling SignatureRequestApi#signatureRequestFilesAsFileUrl: {$e->getMessage()}";
}
```
```csharp C#
using System;
using System.Collections.Generic;
using System.IO;
using System.Text.Json;
using Dropbox.Sign.Api;
using Dropbox.Sign.Client;
using Dropbox.Sign.Model;
namespace Dropbox.SignSandbox;
public class SignatureRequestFilesAsFileUrlExample
{
public static void Run()
{
var config = new Configuration();
config.Username = "YOUR_API_KEY";
// config.AccessToken = "YOUR_ACCESS_TOKEN";
try
{
var response = new SignatureRequestApi(config).SignatureRequestFilesAsFileUrl(
signatureRequestId: "fa5c8a0b0f492d768749333ad6fcc214c111e967",
forceDownload: 1
);
Console.WriteLine(response);
}
catch (ApiException e)
{
Console.WriteLine("Exception when calling SignatureRequestApi#SignatureRequestFilesAsFileUrl: " + e.Message);
Console.WriteLine("Status Code: " + e.ErrorCode);
Console.WriteLine(e.StackTrace);
}
}
}
```
```typescript TypeScript
import * as fs from 'fs';
import api from "@dropbox/sign"
import models from "@dropbox/sign"
const apiCaller = new api.SignatureRequestApi();
apiCaller.username = "YOUR_API_KEY";
// apiCaller.accessToken = "YOUR_ACCESS_TOKEN";
apiCaller.signatureRequestFilesAsFileUrl(
"fa5c8a0b0f492d768749333ad6fcc214c111e967", // signatureRequestId
1, // forceDownload
).then(response => {
console.log(response.body);
}).catch(error => {
console.log("Exception when calling SignatureRequestApi#signatureRequestFilesAsFileUrl:");
console.log(error.body);
});
```
```java Java
package com.dropbox.sign_sandbox;
import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.JSON;
import com.dropbox.sign.model.*;
import java.io.File;
import java.math.BigDecimal;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
public class SignatureRequestFilesAsFileUrlExample
{
public static void main(String[] args)
{
var config = Configuration.getDefaultApiClient();
((HttpBasicAuth) config.getAuthentication("api_key")).setUsername("YOUR_API_KEY");
// ((HttpBearerAuth) config.getAuthentication("oauth2")).setBearerToken("YOUR_ACCESS_TOKEN");
try
{
var response = new SignatureRequestApi(config).signatureRequestFilesAsFileUrl(
"fa5c8a0b0f492d768749333ad6fcc214c111e967", // signatureRequestId
1 // forceDownload
);
System.out.println(response);
} catch (ApiException e) {
System.err.println("Exception when calling SignatureRequestApi#signatureRequestFilesAsFileUrl");
System.err.println("Status code: " + e.getCode());
System.err.println("Reason: " + e.getResponseBody());
System.err.println("Response headers: " + e.getResponseHeaders());
e.printStackTrace();
}
}
}
```
```ruby Ruby
require "json"
require "dropbox-sign"
Dropbox::Sign.configure do |config|
config.username = "YOUR_API_KEY"
# config.access_token = "YOUR_ACCESS_TOKEN"
end
begin
response = Dropbox::Sign::SignatureRequestApi.new.signature_request_files_as_file_url(
"fa5c8a0b0f492d768749333ad6fcc214c111e967", # signature_request_id
{
force_download: 1,
},
)
p response
rescue Dropbox::Sign::ApiError => e
puts "Exception when calling SignatureRequestApi#signature_request_files_as_file_url: #{e}"
end
```
```python Python
import json
from datetime import date, datetime
from pprint import pprint
from dropbox_sign import ApiClient, ApiException, Configuration, api, models
configuration = Configuration(
username="YOUR_API_KEY",
# access_token="YOUR_ACCESS_TOKEN",
)
with ApiClient(configuration) as api_client:
try:
response = api.SignatureRequestApi(api_client).signature_request_files_as_file_url(
signature_request_id="fa5c8a0b0f492d768749333ad6fcc214c111e967",
force_download=1,
)
pprint(response)
except ApiException as e:
print("Exception when calling SignatureRequestApi#signature_request_files_as_file_url: %s\n" % e)
```