Skip to content
  1. Blog
  2. API

How to Apply Expiration Date for eSignature Requests Through API

TL;DR: You set an expiration date on an eSignature request by adding ExpiryDateType and ExpiryValue to the send document call. The type can be Days, Hours or SpecificDateTime, and a request without a setting expires after 60 days. Our eSignature API page shows what else the API can do.

You send an offer letter that must be signed by Friday. Or you send a price quote that is only good for 48 hours. Without a deadline, a signer could open and sign the document weeks later, after the terms have changed.

An expiration date closes the signing window for you. This guide explains how expiry works in BoldSign and shows the code to set it in five languages.

What is an expiration date on an eSignature request?

An expiration date is the point after which signers can no longer sign the document. Until then, the request works as normal.

Think of a coupon with a “valid until” date printed on it. The shop accepts it up to that day and turns it away after. A signature request with an expiry works the same way, so old terms do not get signed by mistake.

How do you set an expiration date through the BoldSign API?

Add the expiry fields to the request that sends the document. You do not need a second call.

The send document endpoint accepts these fields:

  • ExpiryDateType sets the unit of the deadline: Days, Hours or SpecificDateTime.
  • ExpiryValue sets how many days or hours the request stays open.
  • ExpiryDays is a simpler field that takes a count of days only.
  • DisableExpiryAlert, set to true, stops the alert signers get one day before expiry.

A request with no expiry setting expires 60 days after you send it. For the format of a SpecificDateTime value, see the API reference.

What do the code samples look like?

Each sample below sends one document to one signer with a 10-day expiry. Replace the values in curly braces with your API key, file path and other details.

curl -X 'POST' \
  'https://api.boldsign.com/v1/document/send' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {your API key}' \
  -H 'Content-Type: multipart/form-data' \
  -F 'Message={document message}' \
  -F 'Signers={
  "name": "Alex",
  "emailAddress": "alex@example.com",
  "signerType": "Signer",
  "formFields": [
    {
      "id": "textbox1",
      "name": "textbox1",
      "filetype": "Textbox",
      "pageNumber": 1,
      "bounds": {
        "x": 140,
        "y": 140,
        "width": 82,
        "height": 32
      },
      "isRequired": true
    }
  ]
}' \
  -F 'ExpiryDays={The number of days after which the document expires}' \
  -F 'Files=@{your file}' \
  -F 'Title={title}' \
  -F 'ExpiryDateType={set the expirydatetype}' \
  -F 'ExpiryValue={expiryvalue}'
var apiClient = new ApiClient("https://api.boldsign.com", "{Your API key}");
var documentClient = new DocumentClient(apiClient);
var documentFilePath = new DocumentFilePath
{
    ContentType = "application/pdf",
    FilePath = "{your file path}"
};
var filesToUpload = new List<IDocumentFile>
{
    documentFilePath,
};
var signatureField = new FormField(
    id: "sign",
    isRequired: true,
    type: FieldType.Signature,
    pageNumber: 1,
    bounds: new Rectangle(x: 200, y: 200, width: 125, height: 25));
var formFieldCollections = new List<FormField>()
{
    signatureField
};
var signer = new DocumentSigner(
    signerName: "Alex",
    signerEmail: "alex@example.com",
    signerType: SignerType.Signer,
    formFields: formFieldCollections,
    locale: Locales.EN);
var documentSigners = new List<DocumentSigner>()
{
    signer
};
var sendForSign = new SendForSign()
{
    Signers = documentSigners,
    Title = "Expiration date",
    ExpiryValue = {expiry value},
    ExpiryDateType = ExpiryDateType.Days,
    Files = filesToUpload
};
var documentCreated = documentClient.SendDocument(sendForSign);
Console.WriteLine(documentCreated.DocumentId);
import requests  # type: ignore
import json

url = "https://api.boldsign.com/v1/document/send"
signer_data = {
    "name": "Alex",
    "emailAddress": "alex@example.com",
    "signerType": "Signer",
    "signerRole": "Signer",
    "formFields": [
        {
            "id": "signature",
            "name": "signature",
            "fieldType": "Signature",
            "pageNumber": 1,
            "bounds": {"x": 100, "y": 100, "width": 125, "height": 25},
            "isRequired": True,
        }
    ],
    "locale": "EN",
}
payload = {
    "Signers": json.dumps(signer_data),
    "Title": "Expiration date",
    "ExpiryValue": "10",
    "ExpiryDateType": "Days",
}

files = [("Files", ("{your file name}", open("{your file path}", "rb"), "application/pdf"))]
headers = {"accept": "application/json", "X-API-KEY": "{your Api key}"}
response = requests.post(url, headers=headers, data=payload, files=files)
print(response.text)
const axios = require("axios");
const FormData = require("form-data");
const fs = require("fs");
let data = new FormData();
data.append(
  "Signers",
  '{\r\n        "name": "Alex",\r\n        "emailAddress": "alex@example.com",\r\n        "signerType": "Signer", \r\n        "signerRole": "Signer",\r\n        "formFields": [\r\n           {\r\n                "id": "signature",\r\n                "name": "signature",\r\n                "fieldType": "Signature",\r\n                "pageNumber": 1,\r\n                "bounds": {\r\n                  "x": 100,\r\n                  "y": 100,\r\n                  "width": 125,\r\n                  "height": 25\r\n                   },\r\n      "isRequired": true\r\n    }\r\n  ],\r\n  "locale": "EN"\r\n}',
);
data.append("Files", fs.createReadStream("{your file path}"));
data.append("Title", "Expiration date");
data.append("ExpiryDateType", "Days");
data.append("ExpiryValue", "10");
let config = {
  method: "post",
  maxBodyLength: Infinity,
  url: "https://api.boldsign.com/v1/document/send",
  headers: {
    "accept": "application/json",
    "X-API-KEY": "{Your API key}",
    ...data.getHeaders(),
  },
  data: data,
};
axios
  .request(config)
  .then((response) => {
    console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
    console.log(error);
  });
<?php
require_once "vendor/autoload.php";
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;
use \GuzzleHttp\Psr7\Utils;

$client = new GuzzleHttp\Client();

$headers = [
    'accept' => 'application/json',
    'X-API-KEY' => '{your api key}'
];

$options = [
    'multipart' => [
        [
            'name' => 'DisableExpiryAlert',
            'contents' => 'false'
        ],
        [
            'name' => 'Message',
            'contents' => 'please sign the document'
        ],
        [
            'name' => 'Signers',
            'contents' => '{
                "name": "Alex",
                "emailAddress": "alex@example.com",
                "signerType": "Signer",
                "formFields": [
                    {
                        "id": "string",
                        "name": "string",
                        "fieldType": "Signature",
                        "pageNumber": 1,
                        "bounds": {
                            "x": 50,
                            "y": 50,
                            "width": 1,
                            "height": 1
                        },
                        "isRequired": true
                    }
                ],
                "locale": "EN"
            }'
        ],
        [
            'name' => 'ExpiryDays',
            'contents' => '10'
        ],
        [
            'name' => 'Files',
            'contents' => Utils::tryFopen('{your file path}', 'r'),
            'filename' => '{your file name}',
            'headers' => [
                'Content-Type' => 'application/pdf'
            ]
        ],
        [
            'name' => 'Title',
            'contents' => 'Expiration date'
        ],
        [
            'name' => 'ExpiryDateType',
            'contents' => 'Days'
        ],
        [
            'name' => 'ExpiryValue',
            'contents' => '10'
        ],
    ]
];

$request = new Request('POST', 'https://api.boldsign.com/v1/document/send', $headers);
$res = $client->sendAsync($request, $options)->wait();
echo $res->getBody();
The C# sample sets ExpiryValue as a placeholder, so put a number there before you run it. The first and last samples also send ExpiryDays next to the type and value.

What happens when a document expires?

Once the deadline passes, signers can no longer open the document to sign it. Any signatures already added stay on record in the audit trail.

To keep a deal alive, extend the deadline before it runs out. The extend document expiry endpoint moves the date later for documents that are not signed yet.

The new date can be up to 180 days after the document was created. Our guide on how to extend document expiry with the BoldSign API walks through that call.

How do you choose the right expiry period?

Match the deadline to how long the terms in the document stay true. A short window suits quotes and offers, and a long one suits contracts that need review.

  1. Use Hours for time-sensitive items such as a same-day approval or a 48-hour quote.
  2. Use Days for most agreements, such as a 7-day offer letter or a 30-day contract.
  3. Use SpecificDateTime when the deadline is a fixed moment, such as the end of a sale.
  4. Pair the expiry with automatic reminders so signers act before it passes.

Which plan do you need to use the BoldSign API?

You can build and test with a free API sandbox, and you need the Enterprise API plan to send live documents. Expiry settings work the same on both.

The Enterprise API plan starts at $30 a month with 40 envelopes included, and each extra envelope costs $0.75. Sandbox documents carry a test watermark and are deleted after 14 days.

Prices are in USD. See the pricing page for current details.

Ready to add expiry dates to your signing flow?

Pick the step that fits where you are:

Frequently asked questions

What is the default expiry for a BoldSign signature request?

A document sent through the API expires 60 days after you send it, unless you set your own expiry. You can set a shorter or longer period in the send request.

Can I set an expiry in hours instead of days?

Yes. Set ExpiryDateType to Hours and put the number of hours in ExpiryValue. The same send request also accepts Days or SpecificDateTime.

What happens when an eSignature request expires?

The signers can no longer open the document to sign it. You would send a new request, or extend the expiry before the date passes.

Can I extend the expiry date after I send the document?

Yes, for documents that are not signed yet. Call the extend expiry endpoint with a new value up to 180 days after the document was created.

Do signers get a warning before a document expires?

Yes, by default. Signers get an alert one day before expiry. Set DisableExpiryAlert to true in the send request to turn that alert off.

Can I shorten an expiry date with the extend endpoint?

No. The extend expiry endpoint only moves the date later. To give signers less time, set the shorter expiry when you first send the document.

Is a document still legally binding if it was signed just before expiry?

Yes, when the signer completed it before the expiry time and the usual eSignature rules are met. The expiry only stops new signing after the deadline passes.

Can I test document expiry for free?

Yes. Our free sandbox lets you send test documents with any expiry setting. Sandbox documents carry a test watermark and are deleted after 14 days.

Starvritsa Buhungi

Starvritsa is a Technical Assistant at BoldSign, channelling her passion into crafting top-tier content for users through meticulous documentation. She creates content across various formats, including API tutorials, help articles, and comprehensive guides.

More posts by Starvritsa Buhungi
Get started

Sign up for your free trial today!

Start free trial
  • 30-day free trial
  • No credit card required