QuickSign API

Get API Key

API Reference

Complete reference for all QuickSign external API endpoints. All endpoints require authentication with an API key passed in the X-API-KEY header.

Base URL

All API requests should be made to: https://api.quicksign.com.au/external/api/v1
GET/documents

List Documents

Get a list of all documents owned by your account. Supports pagination, filtering by status, search, and sorting. Perfect for building document dashboards and automation workflows.

API Key Required

Query Parameters

Parameters

NameTypeRequiredDescription
pagenumberOptionalPage number for pagination (default: 1)
limitnumberOptionalNumber of documents per page (default: 10, max: 100)
statusstringOptionalFilter by status: "DRAFT", "SENT", "COMPLETED", or "TRASH" (declined/expired/cancelled)
searchstringOptionalSearch term to filter documents by title
sortBystringOptionalSort by field: "dateCreated", "documentName", or "dateModified" (default: "dateCreated")
sortOrderstringOptionalSort order: "ASC" or "DESC" (default: "DESC")

Code Examples

List Documents

# Get all DRAFT documents
curl -X GET "https://api.quicksign.com.au/external/api/v1/documents?status=DRAFT&page=1&limit=10" \
  -H "X-API-KEY: your-api-key-here"

# Search for contracts
curl -X GET "https://api.quicksign.com.au/external/api/v1/documents?search=contract" \
  -H "X-API-KEY: your-api-key-here"

Success Response

Documents Retrieved Successfully

200 OK
{
  "code": "DEFAULT",
  "message": "Documents retrieved successfully",
  "data": {
    "items": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "title": "Employment Contract",
        "status": "DRAFT",
        "filePath": "https://s3.amazonaws.com/bucket/document.pdf",
        "pages": 3,
        "createdAt": "2024-01-15T10:30:00.000Z",
        "updatedAt": "2024-01-15T10:35:00.000Z",
        "expiryDate": null,
        "code": "DOC-12345"
      }
    ],
    "total": 45,
    "page": 1,
    "limit": 10,
    "totalPages": 5
  }
}

Use Cases

  • Dashboard: Display all documents with status filters
  • Search: Find documents by title quickly
  • Automation: Process documents by status (e.g., send all DRAFT documents)
  • Reporting: Generate document statistics and reports
GET/documents/:id

Get Document Details

Retrieve complete information about a specific document, including all recipients and their assigned fields. Essential for knowing the page count before positioning fields and verifying document state.

API Key Required

Path Parameters

Parameters

NameTypeRequiredDescription
idstringRequiredThe unique identifier (UUID) of the document

Code Examples

Get Document Details

curl -X GET https://api.quicksign.com.au/external/api/v1/documents/abc123 \
  -H "X-API-KEY: your-api-key-here"

Success Response

Document Retrieved Successfully

200 OK
{
  "code": "DEFAULT",
  "message": "Document retrieved successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Employment Contract",
    "status": "DRAFT",
    "filePath": "https://s3.amazonaws.com/bucket/document.pdf",
    "pages": 3,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:35:00.000Z",
    "expiryDate": null,
    "recipients": [
      {
        "id": "recipient-uuid",
        "name": "John Doe",
        "email": "john@example.com",
        "status": "PENDING",
        "colorCode": "#FF6B6B",
        "fields": [
          {
            "id": "field-uuid",
            "type": "SIGNATURE",
            "page": 1,
            "x": 100,
            "y": 200,
            "width": 200,
            "height": 50
          }
        ]
      }
    ]
  }
}

Why This Endpoint is Critical

  • Page Count: Know how many pages the document has before positioning fields (prevents errors!)
  • Verify Recipients: Check which recipients have been added
  • Check Fields: See which fields are already positioned and where
  • Validation: Ensure document is ready before sending
  • Status Check: Know if document is DRAFT, SENT, or COMPLETED
POST/documents/:id/recipients

Add Recipients to Document

Add recipients (signers and viewers) to an existing document. Recipients must be added before fields can be assigned to them.

API Key Required

Path Parameters

Parameters

NameTypeRequiredDescription
idstringRequiredThe unique identifier (UUID) of the document

Request Body

Parameters

NameTypeRequiredDescription
namestringRequiredRecipient's full name
emailstringRequiredRecipient's email address
rolestringRequiredEither "SIGNER" (must sign) or "VIEWER" (can view only)
countryCodestringOptionalCountry code for SMS notifications (e.g., "+1", "+61")
phoneNumberstringOptionalPhone number for SMS notifications

Code Examples

Add Recipients

curl -X POST https://api.quicksign.com.au/external/api/v1/documents/abc123/recipients \
  -H "X-API-KEY: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "name": "John Doe",
      "email": "john@example.com",
      "role": "SIGNER",
      "countryCode": "+1",
      "phoneNumber": "5551234567"
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "role": "VIEWER"
    }
  ]'

Success Response

Recipients Added Successfully

200 OK
{
  "code": "DEFAULT",
  "message": "Recipients added successfully",
  "data": {}
}

Error Responses

Bad Request

400 Bad Request
{
  "code": "ERROR",
  "message": "Invalid request body or validation error",
  "data": {}
}

Document Not Found

404 Not Found
{
  "code": "ERROR",
  "message": "Document not found",
  "data": {}
}

Best Practice

Add all recipients in a single request to minimize API calls. You can send an array of recipients.
POST/documents/:id/fields

Add Fields to Document

Add signature fields, text fields, date fields, or initials fields to a document. Fields are positioned by page and coordinates, and assigned to specific recipients by their email address.

API Key Required

Path Parameters

Parameters

NameTypeRequiredDescription
idstringRequiredThe unique identifier (UUID) of the document

Request Body

Parameters

NameTypeRequiredDescription
recipientEmailstringRequiredEmail address of the recipient (must match a previously added recipient)
typestringRequiredField type: "SIGNATURE", "TEXT", "DATE", or "INITIALS"
pagenumberRequiredPage number where the field should be placed (1-indexed)
xnumberRequiredX coordinate (horizontal position) in pixels from the left edge
ynumberRequiredY coordinate (vertical position) in pixels from the top edge
widthnumberOptionalField width in pixels (default: 200)
heightnumberOptionalField height in pixels (default: 50)

Code Examples

Add Fields

curl -X POST https://api.quicksign.com.au/external/api/v1/documents/abc123/fields \
  -H "X-API-KEY: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "recipientEmail": "john@example.com",
      "type": "SIGNATURE",
      "page": 1,
      "x": 100,
      "y": 200,
      "width": 200,
      "height": 50
    },
    {
      "recipientEmail": "jane@example.com",
      "type": "TEXT",
      "page": 1,
      "x": 100,
      "y": 300,
      "width": 150,
      "height": 30
    }
  ]'

Success Response

Fields Added Successfully

200 OK
{
  "code": "DEFAULT",
  "message": "Fields added successfully",
  "data": {}
}

Important

Recipients must be added to the document before fields can be assigned to them. The recipientEmailmust match an email from a previously added recipient.

Coordinate System

The coordinate system starts at the top-left corner of each page (0,0). X increases to the right, Y increases downward. All measurements are in pixels.
POST/documents/:id/send

Send Document for Signing

Send the document to all recipients for signing. This triggers email notifications and updates the document status to 'SENT'. The document must have at least one recipient with assigned fields.

API Key Required

Path Parameters

Parameters

NameTypeRequiredDescription
idstringRequiredThe unique identifier (UUID) of the document

Request Body

Parameters

NameTypeRequiredDescription
messagestringRequiredMessage to include in the signing email notification
descriptionstringRequiredAdditional description or instructions for recipients
expiryDatestringRequiredExpiry date in ISO 8601 format (UTC). Must be in the future. Example: "2024-12-31T23:59:59Z"

Code Examples

Send Document

curl -X POST https://api.quicksign.com.au/external/api/v1/documents/abc123/send \
  -H "X-API-KEY: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Please review and sign this document",
    "description": "This is an important contract that requires your signature.",
    "expiryDate": "2024-12-31T23:59:59Z"
  }'

Success Response

Document Sent Successfully

200 OK
{
  "code": "DEFAULT",
  "message": "Document sent successfully",
  "data": {}
}

Prerequisites

Document Requirements

Before sending a document, ensure:
  • The document has at least one recipient
  • All recipients have at least one field assigned to them
  • The document is in "DRAFT" status (not already sent)
  • The expiry date is in the future
GET/documents/:id/audit

Get Document Audit Trail

Retrieve the complete audit trail (history) for a document, including all events like creation, sending, viewing, signing, and completion. Useful for compliance and tracking document status.

API Key Required

Path Parameters

Parameters

NameTypeRequiredDescription
idstringRequiredThe unique identifier (UUID) of the document

Code Examples

Get Audit Trail

curl -X GET https://api.quicksign.com.au/external/api/v1/documents/abc123/audit \
  -H "X-API-KEY: your-api-key-here"

Success Response

Audit Trail Retrieved Successfully

200 OK
{
  "code": "DEFAULT",
  "message": "Audit trail retrieved successfully",
  "data": [
    {
      "id": "uuid-here",
      "event": "CREATED",
      "message": "Document created successfully",
      "ipAddress": "192.168.1.1",
      "userAgent": "Mozilla/5.0...",
      "createdAt": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "uuid-here",
      "event": "SENT",
      "message": "Document was sent for signature",
      "ipAddress": "192.168.1.1",
      "userAgent": "Mozilla/5.0...",
      "createdAt": "2024-01-15T10:35:00.000Z"
    },
    {
      "id": "uuid-here",
      "event": "VIEWED",
      "message": "Viewed by recipient@example.com",
      "ipAddress": "192.168.1.2",
      "userAgent": "Mozilla/5.0...",
      "createdAt": "2024-01-15T11:00:00.000Z"
    },
    {
      "id": "uuid-here",
      "event": "SIGNED",
      "message": "Signed by recipient@example.com",
      "ipAddress": "192.168.1.2",
      "userAgent": "Mozilla/5.0...",
      "createdAt": "2024-01-15T11:05:00.000Z"
    },
    {
      "id": "uuid-here",
      "event": "COMPLETED",
      "message": "This document has been completed.",
      "ipAddress": "192.168.1.1",
      "userAgent": "Mozilla/5.0...",
      "createdAt": "2024-01-15T11:10:00.000Z"
    }
  ]
}

Event Types

Possible Events

NameTypeRequiredDescription
CREATEDeventOptionalDocument was created
SENTeventOptionalDocument was sent to recipients
VIEWEDeventOptionalA recipient viewed the document
SIGNEDeventOptionalA recipient signed the document
DECLINEDeventOptionalA recipient declined to sign
COMPLETEDeventOptionalAll recipients have signed and document is complete
EXPIREDeventOptionalDocument expired before completion
UPDATEDeventOptionalDocument was updated

Use Cases

The audit trail is essential for:
  • Compliance: Maintain complete records of document lifecycle
  • Debugging: Track down issues with document delivery or signing
  • Analytics: Measure time-to-sign and recipient engagement
  • Legal Evidence: Provide timestamp and IP address proof

Next Steps

Now that you understand all the API endpoints, check out the Webhooks documentation to receive real-time notifications when documents are completed.