---
title: "Request a signature - Send an OTP via SMS"
method: POST
path: "/leases/{lease_id}/signature/request"
tags: ["Leases", "Signatures"]
---

# Request a signature - Send an OTP via SMS

`POST /leases/{lease_id}/signature/request`

## Request

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

Initiates the signature process for the authenticated user by sending an OTP code via SMS.

## Signature flow
1. The user captures their signature image (handwritten drawing)
2. The image is encoded in base64 and sent with this endpoint
3. The system identifies the user via their JWT and verifies they are a signer of the lease
4. A 6-digit OTP code is sent via SMS to the registered phone number
5. The code expires after 5 minutes

## 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

## Prerequisites
- The user must be authenticated and be a signer of the lease
- The signature process must have been initiated (`POST /leases/{lease_id}/signature/initiate`)
- The signer must have a valid registered phone number

## Signature image
The image must be:
- Encoded in base64
- PNG or JPEG format recommended
- Reasonable size (< 500KB after encoding)

## Path parameters

- `lease_id` string, uuid, required

## Request body

- RequestSignatureDto: Request to initiate a user's signature. This object is sent to the `/leases/{lease_id}/signature/request` endpoint to: 1. Submit the signature image captured by the user 2. Trigger sending an OTP code via SMS The user is automatically identified via their API key - no need to specify their identity in the request.
  - `document_signature_id` string, uuid, required: Unique identifier of the signature process. Obtained during initiation via `POST /leases/{lease_id}/signature/initiate`.
  - `person_id` string, uuid, nullable: Optional. The signer's `owner_id` or `lessee_id`, when they have no `auth_user_id` linked to their account. Not a way around identity checks: the JWT's email must match the signer's email for the request to be accepted.
  - `document_declare_lu` boolean: The signer **declares** having read the document, as a guest signer already does. It is a declaration, not proof of reading: the platform cannot certify that anyone read anything, only that they stated they had, and when. Defaults to `false`: a client that omits it declares nothing rather than declaring on the user's behalf.
  - `signature_data` object, required: Handwritten signature data
    - `signature_image` string, byte, required: Base64-encoded handwritten signature image. **Recommended format:** - PNG or JPEG - Transparent background (PNG) or white - Size: 300x100 pixels minimum - Weight: < 500KB after encoding **Example data URL prefix (optional):** `data:image/png;base64,iVBORw0KGgo...`

## Response `200`

OTP code sent successfully via SMS

- object
  - `success` boolean, required: Indicates whether the sending was successful
  - `message` string, required: Confirmation message
  - `expires_at` string, date-time: OTP code expiration date (typically 5 minutes)
  - `phone_hint` string: Phone number hint (partially masked)

## Other responses

- `400`: Invalid data or missing signature image
- `401`: Unauthorized
- `403`: The user is not an authorized signer for this lease
- `404`: Lease or signature process not found
- `422`: Unable to send OTP (invalid number, quota exceeded, etc.)
- `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)