---
title: "Finalize a signature document (Worker)"
method: POST
path: "/leases/signatures/{document_signature_id}/finalize"
tags: ["Signatures", "Workers"]
---

# Finalize a signature document (Worker)

`POST /leases/signatures/{document_signature_id}/finalize`

## Request

- Base URL: `https://api.faireplace.com/api`
- URL: `https://api.faireplace.com/api/leases/signatures/{document_signature_id}/finalize`
- Auth: API key in header `X-API-Key`

Finalizes a signature document and activates the lease if all signatures are complete.

## Usage
This endpoint is called by the **signature-orchestrator** (Cloudflare worker) when **all signers**
have completed their signatures. It verifies that all signature_requests are complete and activates
the lease if so.

## Finalization flow
1. All signers have completed their signatures (via `POST /leases/signatures/{document_signature_id}/complete/{signer_type}`)
2. The signature-orchestrator calls this endpoint to finalize the document
3. The system verifies that all signature_requests are in `COMPLETED` status
4. If all are complete:
   - The document is marked as `COMPLETED`
   - The lease changes to `ACTIVE` status
   - A finalization event is published
5. If some signatures are not complete, the document is marked as `COMPLETED`
   but the lease remains in `PENDING_SIGNATURE`

## Authentication
This endpoint uses an **API key** (`X-API-Key`) instead of a Bearer API key.
Only authorized workers can call this endpoint.

## Important note
The signature_requests must be updated individually via `POST /leases/signatures/{document_signature_id}/complete/{signer_type}`
before calling this endpoint. This endpoint does not update the signature_requests, it only
verifies them.

## Prerequisites
- The signature document must exist
- All signature_requests must be in `COMPLETED` status (updated individually)
- The tenant_id must be provided in the `X-Tenant-ID` header
- The final signed PDF URL must be provided

## Path parameters

- `document_signature_id` string, uuid, required

## Request body

- FinalizeDocumentSignatureRequest: Request to finalize a signature document. This endpoint is called by the signature-orchestrator when all signers have finished their signatures. It verifies that all signatures are complete and activates the lease if so.
  - `signed_pdf_url` string, uri, required: URL of the final signed PDF (containing all signatures)
  - `archive_url` string, uri, nullable: URL of the archived PDF with timestamping (optional)

## Response `200`

Signature document finalized successfully

- FinalizeDocumentSignatureResponse: Response after finalizing a signature document. This response confirms that the document has been finalized and that the lease has been activated if all signatures were complete.
  - `success` boolean, required: Indicates whether the finalization succeeded
  - `message` string, required: Confirmation message
  - `document_signature_id` string, uuid, required: Finalized signature document ID

## Other responses

- `400`: Invalid data
- `401`: Missing or invalid API key
- `404`: Signature document not found
- `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)