Sending for Signature

The signature requests endpoint lets you upload a PDF and send it to one or more signers. VisiSign handles the email delivery, signing experience, and document finalization.

Basic request

Upload a file and provide signer information:

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",
    "signers": [
      {"name": "Alice", "email": "alice@example.com"},
      {"name": "Bob", "email": "bob@example.com"}
    ]
  }'

Request options

The data parameter accepts the following fields:

Field	Type	Default	Description
title	string	"Untitled"	Document title shown to signers
message	string	—	Message included in the signing email
signers	array	required	List of signer objects
fields	array	—	Placed fields (signature, date, text, checkbox)
signing_order	string	"everyone"	"everyone" (parallel) or "one_at_a_time" (sequential)
expires_at	string	—	ISO 8601 expiration date
test_mode	boolean	false	Test mode requests are not legally binding
metadata	object	—	Arbitrary key-value data attached to the request

Signers

Each signer needs a name and email. For sequential signing, include order:

{
  "signers": [
    {"name": "Alice", "email": "alice@example.com", "order": 0},
    {"name": "Bob", "email": "bob@example.com", "order": 1}
  ]
}

When signing_order is "one_at_a_time", signers are emailed in order — Bob receives his signing link only after Alice completes.

Placing fields

Position fields on the document pages. Each field is linked to a signer by signer_index (0-based, matching the signers array):

{
  "fields": [
    {
      "type": "signature",
      "signer_index": 0,
      "page": 1,
      "x": 100,
      "y": 650,
      "width": 200,
      "height": 50,
      "required": true
    },
    {
      "type": "date",
      "signer_index": 0,
      "page": 1,
      "x": 100,
      "y": 710,
      "width": 150,
      "height": 30
    }
  ]
}

Field types

Type	Description
signature	Signature field (draw, type, or upload)
date	Auto-filled with the signing date
text	Free-text input
checkbox	Checkbox toggle

Field properties

Property	Type	Default	Description
type	string	required	Field type
signer_index	integer	required	Which signer this field belongs to
page	integer	required	Page number (1-based)
x	number	required	X position in points from left edge
y	number	required	Y position in points from top edge
width	number	required	Width in points
height	number	required	Height in points
label	string	—	Label shown to the signer
required	boolean	true	Whether the field must be filled

Sending reminders

Send a reminder to a signer who hasn’t signed yet:

curl -X POST https://api.visisign.app/v1/signature_requests/sr_123/remind \
  -H "Authorization: Bearer vsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email_address": "alice@example.com"}'

Cancelling a request

Cancel a signature request that hasn’t been completed:

curl -X POST https://api.visisign.app/v1/signature_requests/sr_123/cancel \
  -H "Authorization: Bearer vsk_your_key_here"

Cancelled requests cannot be reopened. Signers who haven’t signed will see the request as cancelled.

Downloading signed files

Once all signers have completed, download the signed PDF:

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

The response redirects to the file URL. Use -L (follow redirects) with curl.