---
title: "List Signing Requests"
method: GET
path: "/signing-requests"
tags: ["Signing Requests"]
---

# List Signing Requests

`GET /signing-requests`

Retrieve a paginated list of signing requests

## Query parameters

- `page` integer
- `page_size` integer
- `name` string
- `status` 'not_sent' | 'in_progress' | 'finished' | 'cancelled' | 'declined' | 'deleted' | 'expired'
- `created_after` string, date-time
- `created_before` string, date-time
- `signer_email` string
- `signer_name` string
- `sort_by` 'name' | 'created_on' | 'expiration_hours' | 'sent_on' | 'finished_on'
- `sort_order` 'asc' | 'desc'

## Response `200`

Signing requests retrieved successfully

- SigningRequestListResponse — Paginated list of signing requests
  - `results` SigningRequestListItem[], required
    - `id` string, uuid, required — Unique identifier for the signing request
    - `name` string, required — Signing request name
    - `description` string, nullable — Signing request description
    - `status` 'not_sent' | 'in_progress' | 'finished' | 'cancelled' | 'declined' | 'deleted' | 'expired', required — Current status of the signing request
    - `document_url` string, uri — Pre-signed URL to the PDF document. This is a time-limited signed URL for secure access - see document_url_expires_at for expiration time. Initial URLs are valid for 7 days; refreshed URLs are valid for 1 hour. Request a new signing request retrieval to get a fresh URL if expired.
    - `document_url_expires_at` string, date-time, nullable — ISO 8601 timestamp when the document_url will expire. After this time, the URL will return an access denied error. Fetch the signing request again to receive a fresh signed URL.
    - `page_count` integer — Number of pages in the document
    - `expiration_hours` integer — Hours until signing request expires (default: 168 = 7 days)
    - `expires_at` string, date-time, nullable — ISO 8601 timestamp when the signing request expires. Computed from sent_date + expiration_hours. Null if the signing request has not been sent yet or has no expiration_hours set.
    - `credit_cost` integer — Number of credits consumed when this signing request was sent. Minimum value is 1.
    - `template_id` string, uuid, nullable — Template ID if created from a template
    - `settings` SigningRequestSettings — Settings returned by the signing request list and detail endpoints. Templates use the TemplateSettings schema (no identity fields).
      - `allow_download` boolean — Whether recipients can download the document
      - `attach_pdf_on_finish` boolean — Whether to attach PDF when signing is complete
      - `allow_editing_before_sending` boolean — Whether the signing request can be edited before sending
      - `use_signing_order` boolean — Whether signing order is enforced among recipients. When true, signers receive the document in sequence based on their order. When false, all signers receive the document simultaneously.
      - `hand_drawn_only` boolean — When enabled, signers can only hand-draw their signatures and cannot use typed/font-based signatures
      - `send_signing_email` boolean — Whether to send signing request notification emails to signers
      - `send_finish_email` boolean — Whether to send completion email when all signers finish
      - `send_expiration_email` boolean — Whether to send expiration notification email when request expires
      - `send_cancellation_email` boolean — Whether to send cancellation notification email when request is cancelled
      - `require_otp_verification` boolean, nullable — Whether signers must verify their email with a one-time code before accessing the document. null = inherit from workspace/company setting.
      - `disable_guided_navigation` boolean, nullable — Disable automatic scrolling to the next required field during signing. Inherits from workspace or company if not set.
      - `allow_presigning_download` boolean, nullable — Allow signers to download the original document before signing. Inherits from workspace or company setting when null.
      - `show_qr_code` boolean, nullable — Show a QR code on the signing page that lets signers continue on their phone. Inherits from workspace or company setting when null.
      - `identity_editable_fields` string[], nullable — Identity fields signers may edit before signing (e.g. ["name", "company"]). null = disabled. When set, a confirmation dialog lets signers edit the specified fields.
      - `notify_identity_change_email` boolean — Send an email notification when a signer changes their identity.
    - `created_date` string, date-time, required — Creation timestamp
    - `updated_date` string, date-time — Last update timestamp
    - `sent_date` string, date-time, nullable — When the signing request was sent
    - `finished_date` string, date-time, nullable — When all signatures were completed
    - `cancelled_date` string, date-time, nullable — When the signing request was cancelled
    - `declined_date` string, date-time, nullable — When the signing request was declined
    - `recipients` SigningRequestListRecipient[] — Signing request recipients (simplified shape)
      - `id` string, uuid — Unique identifier for the recipient
      - `name` string — Combined full name
      - `email` string, email — Recipient email address
      - `designation` 'Signer' | 'Approver' | 'CC' — Role of the recipient. Signer signs the document, Approver approves with approval fields, CC receives a copy when complete.
      - `order` integer — Signing order
      - `finished_date` string, date-time, nullable — When this recipient completed signing
      - `signature_details` object, nullable — Details about the recipient's signature
    - `fields` object[] — Signing request fields with nested position object
      - `id` string, uuid
      - `type` 'text' | 'signature' | 'date' | 'checkbox' | 'dropdown' | 'radio_buttons' | 'number' | 'text_area' | 'file' | 'initial' | 'stamp' | 'approval_signature' | 'approval_checkmark' | 'approval_date'
      - `required` boolean
      - `recipient_id` string, uuid, nullable
      - `variable_name` string, nullable
      - `variable_defined_name` string, nullable — Human-readable field name from the custom field definition (e.g. 'artist_name'). Only present for fields linked to a custom field definition, null otherwise.
      - `position` object
        - `x` number
        - `y` number
        - `width` number
        - `height` number
      - `value` string, nullable — Final value of the field after signing
      - `dropdown_options` union
        - string[]
        - object
      - `format_rules` DateFormatRules — Formatting rules for date fields. Specifies how date values should be displayed and formatted.
        - `dateFormat` 'MM/dd/yyyy' | 'dd/MM/yyyy' | 'yyyy-MM-dd' | 'MMMM dd, yyyy' | 'MMM dd, yyyy' | 'dd MMMM yyyy' — Date format pattern. Use predefined formats or custom patterns with: yyyy (4-digit year), MM (2-digit month), dd (2-digit day), MMMM (full month name), MMM (abbreviated month name), HH (24-hour), mm (minute), ss (second). Examples: 'MM/dd/yyyy' displays as 01/31/2024, 'MMMM dd, yyyy' displays as January 31, 2024.
        - `fontSize` integer — Optional starting/maximum font size in pixels for the rendered field value. Text still auto-shrinks to fit the field box. Omit for automatic sizing. Values outside 8-48 are clamped.
      - `validation_rules` FieldValidationRules, nullable — Validation rules for field values. Reserved for future use - currently not enforced for any field types.
  - `pagination` Pagination, required — Pagination metadata for list responses
    - `current_page` integer, required
    - `page_size` integer, required
    - `total_count` integer, required
    - `total_pages` integer, required

## Other responses

- `401` — Unauthorized - Invalid or missing API key
- `429` — Too Many Requests - Rate limit exceeded

---

[API](https://skmtc.dev/firma/apis/firma-partner-api.md) · [All operations](https://skmtc.dev/firma/apis/firma-partner-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/firma/firma-partner-api/revisions/5c03d6a9d080/schema)