---
title: "View a guest signature session"
method: GET
path: "/public/guest-signature/{token}"
tags: ["Guest Signature"]
---

# View a guest signature session

`GET /public/guest-signature/{token}`

## Request

- Base URL: `https://api.faireplace.com/api`
- URL: `https://api.faireplace.com/api/public/guest-signature/{token}`
- Auth: none required

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
```bash
curl https://api.faireplace.com/api/public/guest-signature/3f8b1c2d-...-9a0e
```

**Response**:
```json
{
  "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"
}
```

## Path parameters

- `token` string, required

## Response `200`

Guest signature session retrieved.

- GuestSignatureView: Projection exposed to the guest signer when they open the signature link. This is a strict allow-list of fields (tested by snapshot in the backend). It never serializes a raw Signature domain entity.
  - `lease_label` string, required: Human-readable label of the lease being signed.
  - `document_url` string, required: URL to stream the (unsigned/preview) PDF. Points to the `/public/guest-signature/{token}/pdf` proxy endpoint and carries the clear token in its path.
  - `me` GuestSignerSelf, required: Identity of the guest signer: only what is needed for display and the legal mention.
    - `first_name` string, required
    - `last_name` string, required
    - `role` 'bailleur' | 'locataire' | 'garant', required: Legal role of the guest signer (serialized in snake_case).
    - `acting_as` SigningCapacityView, required: Signing capacity disclosed to the guest signer. Discriminated by `kind`: - `self_capacity`: the signer signs in their own name (no extra field). - `on_behalf_of`: the signer acts as a mandatary; only the `mandataire_display_name` is exposed to inform the signer.
      - `kind` 'self_capacity' | 'on_behalf_of', required
      - `mandataire_display_name` string: Display name of the mandatary (present only when kind = on_behalf_of).
  - `other_signers` GuestPeerInfo[], required: Other signers of the same lease (minimal info).
    - `display_name` string, required: Non-extended-PII display name (e.g. initial of the last name).
    - `role` 'bailleur' | 'locataire' | 'garant', required: Legal role of the guest signer (serialized in snake_case).
  - `mandataire_disclosure` MandataireDisclosure: Legal mandatary disclosure printed on a lease signed on behalf of another party (art. 3, loi n°89-462 du 6 juillet 1989). Strictly non-extended-PII: no SIRET, address or email.
    - `display_name` string, required: Display name of the mandatary.
    - `mandate_reference` string, required: Mandate reference.
  - `expires_at` string, date-time, required: Expiration date of the guest signature session.
  - `otp_channel` 'sms' | 'email', required: Channel used to deliver the OTP code. Only the *nature* of the channel is exposed: never the phone number or email itself.

## Other responses

- `404`: Token invalid, not found, or malformed (generic, anti-oracle).
- `410`: The session has expired or has already been used.
- `423`: Too many failed attempts: the session is temporarily locked. A `Retry-After` header (in seconds) indicates when to retry.
- `500`: Internal error (no infra details leaked).
- `503`: The guest signature feature is temporarily disabled.

---

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