Leases
Signatures

Request a signature - Send an OTP via SMS

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

Path parameters

lease_idstring uuid required

UUID identifier of the lease

Request body

document_signature_idstring uuid required

Unique identifier of the signature process. Obtained during initiation via POST /leases/{lease_id}/signature/initiate.

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

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.

Example request

{
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "signature_data": {
    "signature_image": "iVBORw0KGgoAAAANSUhEUgAAASwAAACoCAMAAABt9SM9AAAAWlBMVEXm5ubv7+/x8fH19fX5+fn///8AAABERER3d3eqqqrMzMzu7u4gICAwMDBQUFBgYGCAgICQkJCgoKCwsLDAwMDQ0NDg4ODw8PBBQUFRUVFhYWFxcXGBgYGRkZGhoaE="
  }
}

Response

OTP code sent successfully via SMS

successboolean required

Indicates whether the sending was successful

messagestring required

Confirmation message

expires_atstring date-time

OTP code expiration date (typically 5 minutes)

phone_hintstring

Phone number hint (partially masked)

Example response

{
  "success": true,
  "message": "OTP code sent by SMS",
  "expires_at": "2024-01-15T10:15:00Z",
  "phone_hint": "+33 6 ** ** ** 78"
}

Changes

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