Leases
Signatures

Validate OTP and apply electronic signature

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

Path parameters

lease_idstring uuid required

UUID identifier of the lease

Request body

document_signature_idstring uuid required

Unique identifier of the signature process. Must match the one used during the signature request.

otpstring 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

Example request

{
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "otp": "123456"
}

Response

Signature applied successfully

successboolean required

Indicates whether the validation and signature succeeded

messagestring required

Descriptive result message

document_signature_idstring 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_signersinteger

Number of remaining signers (0 if all have signed)

signed_pdf_urlstring uri nullable

URL of the final signed PDF.

Available only when all signers have validated their signature (document_status = COMPLETED).

Example response

{
  "success": true,
  "message": "Signature completed successfully",
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "signer_status": "COMPLETED",
  "document_status": "SIGNING",
  "remaining_signers": 1,
  "signed_pdf_url": "https://api.faireplace.com/api/media/serve/550e8400-e29b-41d4-a716-446655440003"
}

Changes

No recorded changes to this operation across all 1 revision of this API.