---
title: "Validate OTP and apply electronic signature"
method: POST
path: "/leases/{lease_id}/signature/validate-otp"
tags: ["Leases", "Signatures"]
---

# Validate OTP and apply electronic signature

`POST /leases/{lease_id}/signature/validate-otp`

## Request

- Base URL: `https://api.faireplace.com/api`
- URL: `https://api.faireplace.com/api/leases/{lease_id}/signature/validate-otp`
- Auth: HTTP bearer

Validates the OTP code received via SMS and applies the electronic signature to the PDF document.

## Validation flow
1. The user enters the 6-digit OTP code received via SMS
2. The system verifies that the code is valid and not expired
3. If valid, the signature (previously captured image) is applied to the PDF
4. The signer's status changes to `COMPLETED`
5. If all signers have signed, the final document is generated

## User identification
The system automatically identifies the user as a signer via:
- The `auth_user_id` extracted from the JWT (claim `sub`)
- Matching with an `owner_id` or `lessee_id` in the database
- Verification that this user is indeed a signer of the lease

## OTP code expiration
The OTP code expires after **5 minutes**. If the code has expired, the user must
request a new code via `POST /leases/{lease_id}/signature/request`.

## Final document
When all signers have validated their signature:
- The signed PDF is generated with all signatures
- The signed PDF URL is returned in `signed_pdf_url`
- The document status changes to `COMPLETED`
- A notification is sent to all signers

## Path parameters

- `lease_id` string, uuid, required

## Request body

- ValidateOtpDto: Request to validate the OTP code and finalize the signature. This object is sent to the `/leases/{lease_id}/signature/validate-otp` endpoint after the user has received their code via SMS. The OTP code expires after **5 minutes**. If expired, the user must request a new code via `POST /leases/{lease_id}/signature/request`.
  - `document_signature_id` string, uuid, required: Unique identifier of the signature process. Must match the one used during the signature request.
  - `otp` string, required: 6-digit OTP code received via SMS. **Format:** Exactly 6 digits (0-9) **Validity:** 5 minutes after sending **Attempts:** Maximum 3 attempts before temporary lockout

## Response `200`

Signature applied successfully

- OtpValidationResponse: Response returned after successful OTP validation. Indicates whether the signature was applied and provides information about the overall signature process state.
  - `success` boolean, required: Indicates whether the validation and signature succeeded
  - `message` string, required: Descriptive result message
  - `document_signature_id` string, uuid, required: Signature process ID
  - `signer_status` 'COMPLETED' | 'FAILED': New signer status after validation
  - `document_status` 'SIGNING' | 'COMPLETED': Overall document status after this signature: - `SIGNING`: Waiting for other signatures - `COMPLETED`: All signers have signed
  - `remaining_signers` integer: Number of remaining signers (0 if all have signed)
  - `signed_pdf_url` string, uri, nullable: URL of the final signed PDF. **Available only** when all signers have validated their signature (`document_status` = `COMPLETED`).

## Other responses

- `400`: Invalid, expired, or malformed OTP code
- `401`: Unauthorized
- `403`: The user is not authorized to sign this document
- `404`: Lease or signature process not found
- `409`: The user has already signed this document
- `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)