Quickstart: send your first signature request

Go from API credentials to a signature request and back to its status in seven steps. Each step maps to one documented API call.

Before you start

You'll need API credentials from the Undersign account. See API Keys and Authentication for how to obtain and pass them securely.

1. Get API credentials

Create an API token in your Undersign account and store it securely in an environment variable. Never expose credentials in client-side code or repositories.

2. Set the base URL

Build every request URL as BASE URL + endpoint path. The production base URL is:

3. Authenticate

Include your token in the Authorization header on every request:

Authorization: Bearer <BEARER_TOKEN>

4. List templates

Retrieve the templates available to your account and note the template_id you want to send:

curl -X GET "https://toolkit.undersign.app/api/v1.1/templates" \
  -H "Authorization: Bearer <BEARER_TOKEN>"

5. Create a signature request

Send the request with your chosen template and signers. Basic creation requires mode, message and templates:

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 sign the official documents.",
    "templates": [
      {
        "template_id": "<template-uuid>",
        "signers": [
          { "name": "John Doe", "email": "<signer-email-1>" },
          { "name": "Jane Smith", "email": "<signer-email-2>" }
        ]
      }
    ]
  }'

Request fields

6. Save the returned identifiers

The documented create response includes package_id, package_guid, request_id, timestamp and message. Store package_id and package_guid with your internal record so you can retrieve status later.

7. Retrieve status

Check the request's progress with the status endpoint:

Returns overall status, per-signer status and assigned documents.

curl -X GET "https://toolkit.undersign.app/api/v1.1/signature-requests/<package-guid>" \
  -H "Authorization: Bearer <BEARER_TOKEN>"

Related