---
title: "List all contracts pending signature"
method: GET
path: "/leases/signatures/pending"
tags: ["Leases", "Signatures"]
---

# List all contracts pending signature

`GET /leases/signatures/pending`

## Request

- Base URL: `https://api.faireplace.com/api`
- URL: `https://api.faireplace.com/api/leases/signatures/pending`
- Auth: HTTP bearer

Retrieves the paginated list of all contracts pending signature for the tenant.

## Access
This endpoint is for users with the **"owner"** role in the tenant.
It returns all contracts where at least one signer has a `PENDING` or `SIGNING` status.

## Automatic filtering
- Only contracts from the authenticated user's tenant are returned (multi-tenant isolation)
- Contracts with `COMPLETED`, `EXPIRED`, or `CANCELLED` status are excluded
- Only contracts with at least one pending signer are returned

## Returned information
For each contract, you receive:
- Document information (ID, lease, status, dates, URLs)
- Complete list of all signers with their individual statuses
- The URL of the PDF document to sign
- The URL of the signed PDF (if available)

## Pagination
Use `limit` and `offset` to paginate results.
The `total_count` field indicates the total number of matching contracts.

## Query parameters

- `limit` integer
- `offset` integer

## Response `200`

Pending contracts list retrieved successfully

- PendingSignaturesResponse: Paginated response containing the list of contracts pending signature for the tenant. Used by the `GET /leases/signatures/pending` endpoint. ## Pagination Use the `limit` and `offset` fields in the request to navigate through results. The `total_count` field indicates the total number of contracts matching the criteria, allowing you to calculate the number of pages. ## Page calculation example ``` total_pages = ceil(total_count / limit) current_page = floor(offset / limit) + 1 ```
  - `contracts` PendingSignatureContract[], required: List of contracts pending signature (for the current page)
    - `document_signature_id` string, uuid, required: Unique identifier of the signature process
    - `lease_id` string, uuid: Associated lease identifier.
    - `document_type` 'LEASE' | 'CAUTIONNEMENT', required: What is being signed. A lease with guarantors produces **both**: the lease itself and one surety deed per guarantor. They used to be listed together with no way to tell them apart, so a deed appeared under the heading "lease". Read this field before labelling a row. Documents created before the field existed report `LEASE`.
    - `status` 'READY' | 'SIGNING' | 'COMPLETED' | 'FAILED' | 'ARCHIVED', required: Status of the document signature process
    - `initiator_type` 'proprietaire' | 'locataire' | 'agent_immobilier' | 'caution', required: Who is signing. **Always lowercase** on the wire. `caution` is deliberately distinct from `locataire`: a surety does not sign the lease, they sign their own surety deed, on which they must themselves write the mention required by article 2297 of the Civil Code: without it their undertaking is void.
    - `created_at` string, date-time, required: Date and time the signature process was created
    - `expires_at` string, date-time, nullable: Overall process expiration date (usually 7 days after creation)
    - `signers` PendingSignerDto[], required: List of all contract signers with their individual statuses
      - `signer_type` 'proprietaire' | 'locataire' | 'agent_immobilier' | 'caution', required: Who is signing. **Always lowercase** on the wire. `caution` is deliberately distinct from `locataire`: a surety does not sign the lease, they sign their own surety deed, on which they must themselves write the mention required by article 2297 of the Civil Code: without it their undertaking is void.
      - `signer_email` string, email, required: Signer email address
      - `signer_phone` string, required: Phone number for OTP delivery
      - `status` 'PENDING' | 'OTP_SENT' | 'SIGNING' | 'COMPLETED' | 'FAILED' | 'EXPIRED', required: Status of an individual signature request
      - `expires_at` string, date-time, required: Signature request expiration date
      - `person_id` string, uuid, nullable: Database person ID (owner_id or lessee_id)
      - `first_name` string, nullable: Signer first name
      - `last_name` string, nullable: Signer last name
      - `legal_name` string, nullable: Legal name (for legal entities)
      - `title` string, nullable: Title (Mr., Mrs., etc.)
      - `resend_count` integer: Number of times the request has been resent for this signer
    - `media_id` string, uuid, nullable: Media identifier of the unsigned PDF. Prefer it over `document_url`.
    - `signed_media_id` string, uuid, nullable: Media identifier of the signed PDF, `null` until every party has signed. Prefer it over `signed_pdf_url`.
    - `document_url` string, uri, nullable: Full URL of the unsigned PDF. Kept for backward compatibility: new integrations should use `media_id` and build the URL themselves.
    - `signed_pdf_url` string, uri, nullable: Full URL of the signed PDF, available once every signature is collected. Kept for backward compatibility: prefer `signed_media_id`.
  - `total_count` integer, required: Total number of pending contracts (all combined, before pagination)
  - `limit` integer, required: Maximum number of results per page (value used for the request)
  - `offset` integer, required: Number of skipped results (pagination offset used)

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `500`: Internal Server Error

---

[API](https://skmtc.dev/faireplace/apis/faireplace-property-management-api.md) · [All operations](https://skmtc.dev/faireplace/apis/faireplace-property-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/faireplace/apis/faireplace-property-management-api/revisions/69de39762919?raw)