Guest Signature

Returns the information a guest signer needs to review and sign a lease, from a public token-based link (no login required).

Authentication

This endpoint is public: the only credential is the guest token carried in the URL path. The token is a UUID v4 that is sha256-hashed server-side and is single-use once the signature is applied.

Privacy

The returned projection is a strict allow-list. It never exposes the signer's phone number or email, nor any internal IDs. Only the OTP delivery channel (sms / email) is surfaced.

Anti-oracle behaviour

All responses (success and errors) are padded to a constant minimum latency, and an unknown token returns the same generic 404 as a token that did not match — so timing and messages cannot be used to probe for valid tokens.

Example

Code
curl https://api.faireplace.com/api/public/guest-signature/3f8b1c2d-...-9a0e

Response:

Code
{
  "lease_label": "Bail - 12 rue des Lilas, 75011 Paris",
  "document_url": "https://api.faireplace.com/api/public/guest-signature/3f8b.../pdf",
  "me": {
    "first_name": "Jean",
    "last_name": "Dupont",
    "role": "locataire",
    "acting_as": { "kind": "self_capacity" }
  },
  "other_signers": [
    { "display_name": "M. M.", "role": "bailleur" }
  ],
  "mandataire_disclosure": null,
  "expires_at": "2026-06-27T10:00:00Z",
  "otp_channel": "sms"
}

Streams the (unsigned/preview) PDF for the guest signer to review before signing. Public, token-based (no login).

Why a backend proxy

The PDF is stored encrypted with SSE-C; a browser cannot send the SSE-C headers from an iframe. The backend therefore fetches and decrypts the document, then streams the clear bytes. When previous signatures already exist, the already-signed PDF is served (so each signer consents to the real document).

Embedding

The response sets Content-Disposition: inline and relaxes framing headers (frame-ancestors allow-list) so the PDF can be embedded in the FairePlace frontend.

Example

Code
curl -L https://api.faireplace.com/api/public/guest-signature/3f8b1c2d-...-9a0e/pdf \
  --output bail.pdf

Triggers delivery of a one-time password to the guest signer. The backend resolves the tenant and the delivery channel server-side and relays the request to the signature orchestrator.

Public, token-based (no login). The request takes no body.

Privacy

The response only returns the delivery channel (sms / email) — never the phone number or email used.

Example

Code
curl -X POST https://api.faireplace.com/api/public/guest-signature/3f8b1c2d-...-9a0e/request-otp

Response (202 Accepted):

Code
{ "channel": "sms" }

Validates the OTP code and applies the handwritten signature to the document. Public, token-based (no login).

On success the session token is consumed (single-use): any later call with the same token returns 410 Gone.

Privacy

The returned receipt is non-PII: it carries only signed_at plus an optional evidence_id / completion_url.

Example

Code
curl -X POST https://api.faireplace.com/api/public/guest-signature/3f8b1c2d-...-9a0e/sign \
  -H "Content-Type: application/json" \
  -d '{
    "otp_code": "123456",
    "signature_image_base64": "iVBORw0KGgoAAAANSUhEUg..."
  }'

Response:

Code
{
  "signed_at": "2026-06-20T14:30:00Z",
  "evidence_id": "ev_550e8400e29b41d4",
  "completion_url": "https://app.faireplace.com/signature/done"
}