Documents

Documents are the core resource in inSigner. A document represents a PDF that requires signatures from one or more signers.

List documents

GET /api/v1/documents

Returns a paginated list of documents in your organization.

Query parameters

Parameter	Type	Default	Description
cursor	string	—	Pagination cursor
limit	integer	25	Items per page (1–100)
status	string	—	Filter by status: draft, pending, completed, cancelled, expired, declined
search	string	—	Search by document name (case-insensitive)

Required scope: documents.read

curl

curl -X GET "https://app.insigner.co/api/v1/documents?limit=10&status=completed" \
  -H "Authorization: Bearer isk_YOUR_API_KEY"

JavaScript

const res = await fetch(
  'https://app.insigner.co/api/v1/documents?limit=10&status=completed',
  { headers: { 'Authorization': 'Bearer isk_YOUR_API_KEY' } }
);
const { data, meta } = await res.json();

Python

import requests

res = requests.get(
    "https://app.insigner.co/api/v1/documents",
    headers={"Authorization": "Bearer isk_YOUR_API_KEY"},
    params={"limit": 10, "status": "completed"}
)
data = res.json()

Response

{
  "data": [
    {
      "id": "cm5x9abc123",
      "name": "Sales Agreement Q3",
      "status": "completed",
      "signingType": "sequential",
      "fileSize": 245000,
      "expiresAt": "2026-11-28T12:00:00.000Z",
      "completedAt": "2026-05-29T14:30:00.000Z",
      "createdAt": "2026-05-28T12:00:00.000Z",
      "updatedAt": "2026-05-29T14:30:00.000Z",
      "templateId": null,
      "campaignId": null,
      "bulkSendId": null,
      "folderId": null,
      "_count": { "signers": 2, "fields": 5, "attachments": 1 }
    }
  ],
  "meta": {
    "count": 1,
    "hasMore": false,
    "nextCursor": null
  }
}

---

Create a document

POST /api/v1/documents

Creates a new document in draft status. Upload the PDF file separately via the upload endpoint.

Required scope: documents.create

Request body

Field	Type	Required	Description
name	string	✅	Document name (1–200 chars)
signingType	string	—	"sequential" (default) or "parallel"
message	string	—	Message for signers (max 5000 chars)
expiresAt	string	—	ISO 8601 expiration date (must be in the future)
folderId	string	—	Folder ID to organize the document

curl

curl -X POST https://app.insigner.co/api/v1/documents \
  -H "Authorization: Bearer isk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "NDA - Acme Corp",
    "signingType": "parallel",
    "message": "Please review and sign this NDA.",
    "expiresAt": "2026-12-31T23:59:59.000Z"
  }'

JavaScript

const res = await fetch('https://app.insigner.co/api/v1/documents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer isk_YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'NDA - Acme Corp',
    signingType: 'parallel',
    message: 'Please review and sign this NDA.',
    expiresAt: '2026-12-31T23:59:59.000Z'
  })
});
const { data } = await res.json();

Python

import requests

res = requests.post(
    "https://app.insigner.co/api/v1/documents",
    headers={
        "Authorization": "Bearer isk_YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "name": "NDA - Acme Corp",
        "signingType": "parallel",
        "message": "Please review and sign this NDA.",
        "expiresAt": "2026-12-31T23:59:59.000Z"
    }
)
data = res.json()

Response 201 Created

{
  "data": {
    "id": "cm5x9def456",
    "name": "NDA - Acme Corp",
    "status": "draft",
    "signingType": "parallel",
    "message": "Please review and sign this NDA.",
    "expiresAt": "2026-12-31T23:59:59.000Z",
    "folderId": null,
    "createdAt": "2026-05-28T12:00:00.000Z",
    "updatedAt": "2026-05-28T12:00:00.000Z"
  }
}

---

Get a document

GET /api/v1/documents/{id}

Returns full document details including signers, fields, and attachments.

Required scope: documents.read

curl

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

JavaScript

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

Python

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

Response

{
  "data": {
    "id": "cm5x9abc123",
    "name": "Sales Agreement Q3",
    "status": "completed",
    "signingType": "sequential",
    "fileSize": 245000,
    "documentHash": "a1b2c3d4...",
    "signedFileHash": "e5f6g7h8...",
    "message": "Please review and sign.",
    "emailSubject": null,
    "emailMessage": null,
    "expiresAt": "2026-11-28T12:00:00.000Z",
    "completedAt": "2026-05-29T14:30:00.000Z",
    "reminderFrequency": null,
    "otpMethod": null,
    "requireKyc": false,
    "createdAt": "2026-05-28T12:00:00.000Z",
    "updatedAt": "2026-05-29T14:30:00.000Z",
    "templateId": null,
    "campaignId": null,
    "bulkSendId": null,
    "folderId": null,
    "signers": [
      {
        "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"
      }
    ],
    "fields": [
      {
        "id": "fld_abc123",
        "type": "signature",
        "label": "Client Signature",
        "page": 1,
        "x": 100,
        "y": 650,
        "width": 200,
        "height": 60,
        "required": true,
        "readOnly": false,
        "assignedTo": 0,
        "placeholder": null,
        "defaultValue": null,
        "options": null
      }
    ],
    "attachments": [],
    "_count": { "signers": 1, "fields": 1, "attachments": 0 }
  }
}

---

Delete a document

DELETE /api/v1/documents/{id}

Soft-deletes a document. Cannot delete documents in pending or action_required status — cancel them first.

Required scope: documents.delete

curl

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

JavaScript

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

Python

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

Response: 204 No Content

---

Upload document file

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

Generates a presigned upload URL for the document PDF. The document must be in draft status.

Required scope: documents.write

Request body

Field	Type	Required	Description
filename	string	—	Original filename (default: "document.pdf")
contentType	string	—	MIME type: application/pdf, image/png, image/jpeg, image/webp
fileSize	number	—	File size in bytes (max 50 MB)

curl

# Step 1: Get presigned URL
curl -X POST https://app.insigner.co/api/v1/documents/cm5x9abc123/upload \
  -H "Authorization: Bearer isk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "contract.pdf", "contentType": "application/pdf", "fileSize": 125000}'

# Step 2: Upload file to the presigned URL
curl -X PUT "PRESIGNED_URL_FROM_RESPONSE" \
  -H "Content-Type: application/pdf" \
  --data-binary @contract.pdf

JavaScript

// Step 1: Get presigned URL
const uploadRes = await fetch(
  'https://app.insigner.co/api/v1/documents/cm5x9abc123/upload',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer isk_YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      filename: 'contract.pdf',
      contentType: 'application/pdf',
      fileSize: 125000
    })
  }
);
const { data } = await uploadRes.json();

// Step 2: Upload file
await fetch(data.uploadUrl, {
  method: 'PUT',
  headers: { 'Content-Type': 'application/pdf' },
  body: fileBuffer
});

Python

import requests

# Step 1: Get presigned URL
res = requests.post(
    "https://app.insigner.co/api/v1/documents/cm5x9abc123/upload",
    headers={"Authorization": "Bearer isk_YOUR_API_KEY"},
    json={"filename": "contract.pdf", "contentType": "application/pdf", "fileSize": 125000}
)
upload_url = res.json()["data"]["uploadUrl"]

# Step 2: Upload file
with open("contract.pdf", "rb") as f:
    requests.put(upload_url, data=f, headers={"Content-Type": "application/pdf"})

Response

{
  "data": {
    "uploadUrl": "https://storage.example.com/presigned?...",
    "fileKey": "documents/usr_abc/cm5x9abc123/contract.pdf",
    "expiresIn": 600,
    "method": "PUT",
    "headers": {
      "Content-Type": "application/pdf"
    }
  }
}

Note

The presigned URL expires in 10 minutes (600 seconds). Upload the file using a PUT request before it expires.

---

Send a document

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

Sends the document for signing. Transitions status from draft → pending and emails all signers.

Required scope: documents.send

Prerequisites:

• Document must be in draft status
• At least one signer must be added
• At least one field must be added

curl

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

JavaScript

const res = await fetch(
  'https://app.insigner.co/api/v1/documents/cm5x9abc123/send',
  {
    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/send",
    headers={"Authorization": "Bearer isk_YOUR_API_KEY"}
)

Response

{
  "data": {
    "id": "cm5x9abc123",
    "status": "pending",
    "signerCount": 2,
    "sentAt": "2026-05-28T12:00:00.000Z"
  }
}

Note

If no expiration date was set, a default of 180 days is applied automatically.

---

Download a document

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

Downloads the document PDF. Returns the signed PDF if the document is completed, otherwise the original.

Required scope: documents.read

curl

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

JavaScript

const res = await fetch(
  'https://app.insigner.co/api/v1/documents/cm5x9abc123/download',
  { headers: { 'Authorization': 'Bearer isk_YOUR_API_KEY' } }
);
const blob = await res.blob();
// Save blob as PDF file

Python

res = requests.get(
    "https://app.insigner.co/api/v1/documents/cm5x9abc123/download",
    headers={"Authorization": "Bearer isk_YOUR_API_KEY"}
)
with open("document.pdf", "wb") as f:
    f.write(res.content)

Response: Binary PDF with headers:

• Content-Type: application/pdf
• Content-Disposition: attachment; filename="Document Name - Signed.pdf"

---

Cancel a document

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

Cancels a pending document and notifies all pending signers. Only documents in pending or action_required status can be cancelled.

Required scope: documents.write

curl

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

JavaScript

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

Python

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

Response

{
  "data": {
    "id": "cm5x9abc123",
    "status": "cancelled",
    "cancelledSigners": 2
  }
}

---

Get audit trail

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

Returns the audit log for a document — every action taken, with timestamps, IP addresses, and geo-location.

Required scope: documents.read

Query parameters

Parameter	Type	Default	Description
cursor	string	—	Pagination cursor
limit	integer	25	Items per page (1–100)

curl

curl -X GET "https://app.insigner.co/api/v1/documents/cm5x9abc123/audit?limit=50" \
  -H "Authorization: Bearer isk_YOUR_API_KEY"

JavaScript

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

Python

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

Response

{
  "data": [
    {
      "id": "log_abc123",
      "action": "document.created",
      "details": "API: Created document \"Sales Agreement Q3\"",
      "ipAddress": "203.0.113.42",
      "userAgent": "curl/8.4.0",
      "geoCity": "Bogotá",
      "geoCountry": "CO",
      "createdAt": "2026-05-28T12:00:00.000Z"
    },
    {
      "id": "log_def456",
      "action": "document.sent",
      "details": "API: Sent to Jane Smith, John Doe",
      "ipAddress": "203.0.113.42",
      "userAgent": "curl/8.4.0",
      "geoCity": "Bogotá",
      "geoCountry": "CO",
      "createdAt": "2026-05-28T12:05:00.000Z"
    }
  ],
  "meta": {
    "count": 2,
    "hasMore": false,
    "nextCursor": null
  }
}