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

A guarantor (caution) types, in their own words, the mention required by article 2297 of the French Civil Code. This must happen before POST /public/guest-signature/{token}/sign: without a mention written by the surety themselves, the undertaking is void. The deed is regenerated with their characters and only then can be signed.

The text is compared to the expected mention by the domain, which owns the tolerance on accents and punctuation. Nothing is normalised client-side: the proof has to stay literal, so send the keystrokes as typed.

Typing evidence

The optional mode_saisie, evenements_saisie and duree_saisie_ms fields record how the text arrived in the field. Case law accepts a keyboard-entered mention on the basis that the surety actually typed it, and these fields are what lets you say so. They are reported by the client, so they are never probative on their own, but omitting mode_saisie records the undertaking with an unknown input mode, and it will never be assumed to have been typed.

Why a rejection is 422 and not 400

A non-conforming mention is a well-formed request; what is not constituted is the undertaking. On MENTION_NON_CONFORME the response carries mention_attendue so the surety can copy it without guessing what they missed.