Signers

Signers are the people who need to sign, approve, or view a document. Each signer receives a unique signing link via email.

Signer roles

Role	Description
signer	Must sign the document (default)
viewer	Receives a copy but doesn’t sign
approver	Must approve the document before signers can sign

List signers

GET /api/v1/documents/{id}/signers

Returns all signers on a document, ordered by their signing order.

Required scope: documents.read

curl

curl -X GET https://app.insigner.co/api/v1/documents/cm5x9abc123/signers \
  -H "Authorization: Bearer isk_YOUR_API_KEY"

JavaScript

const res = await fetch(
  'https://app.insigner.co/api/v1/documents/cm5x9abc123/signers',
  { headers: { 'Authorization': 'Bearer isk_YOUR_API_KEY' } }
);
const { data } = await res.json();

Python

res = requests.get(
    "https://app.insigner.co/api/v1/documents/cm5x9abc123/signers",
    headers={"Authorization": "Bearer isk_YOUR_API_KEY"}
)

Response

{
  "data": [
    {
      "id": "sr_abc123",
      "email": "[email protected]",
      "name": "Jane Smith",
      "role": "signer",
      "status": "completed",
      "order": 0,
      "signedAt": "2026-05-29T14:30:00.000Z",
      "createdAt": "2026-05-28T12:00:00.000Z",
      "updatedAt": "2026-05-29T14:30:00.000Z"
    },
    {
      "id": "sr_def456",
      "email": "[email protected]",
      "name": "John Doe",
      "role": "signer",
      "status": "pending",
      "order": 1,
      "signedAt": null,
      "createdAt": "2026-05-28T12:00:00.000Z",
      "updatedAt": "2026-05-28T12:00:00.000Z"
    }
  ]
}

---

Add a signer

POST /api/v1/documents/{id}/signers

Adds a signer to a draft document. Maximum 50 signers per document.

Required scope: documents.write

Request body

Field	Type	Required	Description
email	string	✅	Signer’s email (max 254 chars)
name	string	✅	Signer’s full name (1–200 chars)
role	string	—	"signer" (default), "viewer", or "approver"
order	integer	—	Signing order for sequential documents (default: 0)
phone	string	—	Phone number for SMS verification (max 20 chars)

curl

curl -X POST https://app.insigner.co/api/v1/documents/cm5x9abc123/signers \
  -H "Authorization: Bearer isk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "Jane Smith",
    "role": "signer",
    "order": 0
  }'

JavaScript

const res = await fetch(
  'https://app.insigner.co/api/v1/documents/cm5x9abc123/signers',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer isk_YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      email: '[email protected]',
      name: 'Jane Smith',
      role: 'signer',
      order: 0
    })
  }
);
const { data } = await res.json();

Python

res = requests.post(
    "https://app.insigner.co/api/v1/documents/cm5x9abc123/signers",
    headers={"Authorization": "Bearer isk_YOUR_API_KEY"},
    json={
        "email": "[email protected]",
        "name": "Jane Smith",
        "role": "signer",
        "order": 0
    }
)

Response 201 Created

{
  "data": {
    "id": "sr_abc123",
    "email": "[email protected]",
    "name": "Jane Smith",
    "role": "signer",
    "status": "pending",
    "order": 0,
    "createdAt": "2026-05-28T12:00:00.000Z"
  }
}

Tip

For sequential signing, set the order field to control the signing order. Signer with order: 0 signs first, order: 1 signs second, etc. For parallel signing, order is ignored.

---

Remove a signer

DELETE /api/v1/documents/{id}/signers/{signerId}

Removes a signer from a draft document.

Required scope: documents.write

curl

curl -X DELETE https://app.insigner.co/api/v1/documents/cm5x9abc123/signers/sr_abc123 \
  -H "Authorization: Bearer isk_YOUR_API_KEY"

JavaScript

await fetch(
  'https://app.insigner.co/api/v1/documents/cm5x9abc123/signers/sr_abc123',
  {
    method: 'DELETE',
    headers: { 'Authorization': 'Bearer isk_YOUR_API_KEY' }
  }
);

Python

requests.delete(
    "https://app.insigner.co/api/v1/documents/cm5x9abc123/signers/sr_abc123",
    headers={"Authorization": "Bearer isk_YOUR_API_KEY"}
)

Response: 204 No Content

---

Send a reminder

POST /api/v1/documents/{id}/signers/{signerId}/remind

Sends a reminder email to a pending signer. The document must be in pending or action_required status.

Required scope: documents.send

curl

curl -X POST https://app.insigner.co/api/v1/documents/cm5x9abc123/signers/sr_def456/remind \
  -H "Authorization: Bearer isk_YOUR_API_KEY"

JavaScript

const res = await fetch(
  'https://app.insigner.co/api/v1/documents/cm5x9abc123/signers/sr_def456/remind',
  {
    method: 'POST',
    headers: { 'Authorization': 'Bearer isk_YOUR_API_KEY' }
  }
);
const { data } = await res.json();

Python

res = requests.post(
    "https://app.insigner.co/api/v1/documents/cm5x9abc123/signers/sr_def456/remind",
    headers={"Authorization": "Bearer isk_YOUR_API_KEY"}
)

Response

{
  "data": {
    "signerId": "sr_def456",
    "email": "[email protected]",
    "reminderSentAt": "2026-05-30T10:00:00.000Z"
  }
}