Signature Requests

List signature requests

GET /v1/signature_requests

Returns a paginated list of signature requests for your organization.

Query parameters:

Parameter	Type	Description
page	integer	Page number (default: 1)
per_page	integer	Results per page (default: 20, max: 100)

Response:

{
  "signature_requests": [
    {
      "id": "sr_123",
      "title": "Service Agreement",
      "status": "sent",
      "is_complete": false,
      "is_declined": false,
      "signing_order": "everyone",
      "test_mode": false,
      "metadata": {},
      "files_url": "/v1/signature_requests/sr_123/files",
      "created_at": "2026-03-04T10:00:00Z",
      "expires_at": null,
      "signers": [
        {
          "id": "sig_456",
          "name": "Jane Smith",
          "email": "jane@example.com",
          "status": "pending",
          "order": 0,
          "signed_at": null,
          "viewed_at": null
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total_pages": 1,
    "total_count": 1
  }
}

---

Get a signature request

GET /v1/signature_requests/:id

Returns a single signature request with signer details.

---

Create a signature request

POST /v1/signature_requests

Upload a PDF file and send it for signature. Use multipart/form-data encoding.

Parameters:

Parameter	Type	Description
file	file	PDF file to sign (required)
data	JSON	Request data (required, see below)

Data fields:

Field	Type	Default	Description
title	string	"Untitled"	Document title
message	string	—	Message included in signing emails
signers	array	required	Signer objects (see below)
fields	array	—	Field placement objects
signing_order	string	"everyone"	"everyone" or "one_at_a_time"
expires_at	string	—	ISO 8601 expiration date
test_mode	boolean	false	Non-binding test mode
metadata	object	—	Arbitrary key-value data

Signer object:

Field	Type	Description
name	string	Signer’s full name (required)
email	string	Signer’s email address (required)
order	integer	Signing order (required for one_at_a_time)

Field object:

Field	Type	Description
type	string	signature, date, text, or checkbox (required)
signer_index	integer	Index into the signers array (required)
page	integer	Page number, 1-based (required)
x	number	X position in points (required)
y	number	Y position in points (required)
width	number	Width in points (required)
height	number	Height in points (required)
label	string	Label shown to signer
required	boolean	Whether field must be filled (default: true)

Example:

curl -X POST https://api.visisign.app/v1/signature_requests \
  -H "Authorization: Bearer vsk_your_key_here" \
  -F "file=@contract.pdf" \
  -F 'data={
    "title": "Service Agreement",
    "message": "Please review and sign this agreement.",
    "signers": [
      {"name": "Jane Smith", "email": "jane@example.com"}
    ],
    "fields": [
      {
        "type": "signature",
        "signer_index": 0,
        "page": 1,
        "x": 100,
        "y": 650,
        "width": 200,
        "height": 50
      }
    ]
  }'

Response (201):

{
  "signature_request": {
    "id": "sr_789",
    "title": "Service Agreement",
    "status": "sent",
    "is_complete": false,
    "is_declined": false,
    "message": "Please review and sign this agreement.",
    "signing_order": "everyone",
    "test_mode": false,
    "metadata": {},
    "files_url": "/v1/signature_requests/sr_789/files",
    "created_at": "2026-03-04T12:00:00Z",
    "expires_at": null,
    "signers": [
      {
        "id": "sig_101",
        "name": "Jane Smith",
        "email": "jane@example.com",
        "status": "pending",
        "order": 0,
        "signed_at": null,
        "viewed_at": null
      }
    ]
  }
}

---

Send with template

POST /v1/signature_requests/send_with_template

Create a signature request from a pre-configured template.

Body parameters:

Field	Type	Default	Description
template_id	string	required	Template ID (prefixed tmpl_)
title	string	template name	Document title
message	string	—	Message for signers
signers	array	required	Signers mapped to template roles
expires_at	string	—	ISO 8601 expiration
test_mode	boolean	false	Non-binding test mode
metadata	object	—	Arbitrary metadata

Signer object (template):

Field	Type	Description
name	string	Signer’s full name (required)
email	string	Signer’s email address (required)
role	string	Template role name
role_id	integer	Template role ID

Provide either role or role_id for each signer.

---

Cancel a signature request

POST /v1/signature_requests/:id/cancel

Cancels a signature request. Only requests that haven’t been completed can be cancelled.

Response (200):

Returns the updated signature request with status: "cancelled".

---

Send a reminder

POST /v1/signature_requests/:id/remind

Send a reminder email to a signer who hasn’t signed yet.

Body parameters:

Field	Type	Description
email_address	string	Email of the signer to remind (required)

Response (200):

{
  "message": "Reminder sent."
}

---

Download signed files

GET /v1/signature_requests/:id/files

Redirects to the signed PDF file. Only available after all signers have completed. Returns 404 if the signed file is not yet available.

Use the -L flag with curl to follow the redirect:

curl -L https://api.visisign.app/v1/signature_requests/sr_123/files \
  -H "Authorization: Bearer vsk_your_key_here" \
  -o signed.pdf