Undersign
⌘K
v1.1
Create Free Account
API Reference API reference · Signature Requests
POST /signature-requests

Create Signature Request

Dispatch a document signing package across one or more reusable templates and their associated signers.

Authentication

This endpoint requires a bearer token. See Authentication and API Keys.

Headers

HeaderRequiredDescription
Authorization required Bearer <BEARER_TOKEN>
Content-Type required application/json
Idempotency-Key optional A unique key for the create operation. Supply it to prevent duplicate creation on network timeouts, and reuse it when retrying the same operation. See Idempotency.

Parameters

This endpoint takes no query or path parameters.

Request body

The request body is a JSON object. Only templates is required; every other field is optional.

FieldRequiredTypeDescription
templates required array Array of template objects containing signers and prefill values.
templates[].template_id required string (UUID) Valid UUID of a fillable template.
templates[].signers required array List of recipient objects. Must match the signer count in the template.
templates[].signers[].name required string Full legal recipient name.
templates[].signers[].email required string Valid email address of the recipient.
templates[].prefill optional array Pre-populate form values. Array of objects with id (field ID), name (field label) and value.
mode optional string Delivery mode: email (default, auto-sends links) or local (retrieve links via API).
message optional string Custom invitation email body message. Defaults to an empty string.
sequential_signing optional string Enforce order routing: Yes or No (default). If Yes, email is sent to Signer 1 first; Signer 2 receives email only after Signer 1 completes.
field_visibility optional string Control signer visibility of other parties' entries: Yes or No (default).
external_id optional string Client reference ID (e.g. CRM record ID, contract number). See External IDs & Metadata.
metadata optional object Key-value JSON payload stored with the package and returned in webhooks.
webhook optional object Webhook config object: {"url": "...", "events": ["*"]}. See Configure a Webhook.
webhook_url optional string Legacy string callback URL. Used if the webhook object is omitted.

Request example

curl -X POST "https://toolkit.undersign.app/api/v1.1/signature-requests" \
  -H "Authorization: Bearer <BEARER_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <UNIQUE_KEY>" \
  -d '{
    "mode": "email",
    "message": "Please review and sign the attached agreement.",
    "sequential_signing": "Yes",
    "field_visibility": "No",
    "external_id": "CRM-DOC-10023",
    "metadata": { "deal_id": "D-99821", "region": "NA" },
    "webhook": {
      "url": "https://api.yourdomain.com/webhooks/undersign",
      "events": ["*"]
    },
    "templates": [
      {
        "template_id": "<template-uuid>",
        "signers": [
          { "name": "Alice Smith", "email": "alice@company.com" },
          { "name": "Bob Jones", "email": "bob@partner.com" }
        ],
        "prefill": [
          { "id": "prefill_amt", "name": "Fee", "value": "$10,000" }
        ]
      }
    ]
  }'

Response

A successful creation returns 201 Created with the package identifiers and the echoed request options. Creating a package decrements 1 API credit.

201 Created
{
  "success": true,
  "request_id": "75c3db09-66e0-4ad3-9e47-e6a88b56ea88",
  "timestamp": "2026-09-17T15:01:20+00:00",
  "data": {
    "package_id": 5012,
    "message": "Signature request sent successfully.",
    "package_guid": "7A8F1-92D3E-810A2-9E47A",
    "external_id": "CRM-DOC-10023",
    "metadata": {
      "deal_id": "D-99821",
      "region": "NA"
    },
    "webhook_registered": true,
    "sequential_signing": "Yes",
    "field_visibility": "No"
  }
}

Response fields

FieldDescription
success Whether the request succeeded. true in the supplied example.
request_id API request / correlation identifier. Log it for support.
timestamp API response timestamp.
data.package_id Numeric package identifier. Store with your internal record.
data.message Human-readable result message.
data.package_guid Public / package GUID. Store with your internal record.
data.external_id Client reference ID, if supplied.
data.metadata Metadata associated with the request, if supplied.
data.webhook_registered Whether a webhook was registered for the request.
data.sequential_signing Echo of the requested sequential signing option.
data.field_visibility Echo of the requested field visibility option.

Response status & error codes

CodeError codeDescription
201 - Package created successfully. Decrements 1 API credit.
400 TEMPLATES_REQUIRED The templates parameter is empty or not provided.
400 SIGNER_COUNT_MISMATCH Number of signers supplied does not match the template requirement.
400 SIGNER_ORDER_MISMATCH Signers at the same position do not share the same email across all templates in sequential mode.
400 PROCESSING_ERROR Database transaction or storage copy failure.
403 MONTHLY_API_QUOTA_EXCEEDED API credits exhausted. See Quotas & Credits.
403 STORAGE_LIMIT_EXCEEDED Account storage quota exceeded for the active plan.
404 TEMPLATE_NOT_FOUND Template UUID not found, deleted, or in draft status.
429 RATE_LIMIT_EXCEEDED Too many requests (limit: 100/min). See Rate Limits.

Implementation guidance

Get Signature Request Status

Retrieve the status of the request you created.

Create Bulk Request

Dispatch up to 100 signing requests in one batch.