---
title: "Submit OTP and apply the guest signature"
method: POST
path: "/public/guest-signature/{token}/sign"
tags: ["Guest Signature"]
---

# Submit OTP and apply the guest signature

`POST /public/guest-signature/{token}/sign`

## Request

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

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
```bash
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**:
```json
{
  "signed_at": "2026-06-20T14:30:00Z",
  "evidence_id": "ev_550e8400e29b41d4",
  "completion_url": "https://app.faireplace.com/signature/done"
}
```

## Path parameters

- `token` string, required

## Request body

- GuestSignBody: Request body to submit the OTP and apply the guest signature.
  - `otp_code` string, required: OTP code received via the channel returned by request-otp.
  - `signature_image_base64` string, byte, required: Base64-encoded handwritten signature image (PNG/JPEG recommended). Validated server-side for size and format before being relayed to the signature orchestrator.

## Response `200`

Signature applied successfully.

- GuestSignReceipt: Signature receipt returned after a successful guest signature. Non-PII by design: no signer email, phone or other-signer information.
  - `signed_at` string, date-time, required: Server timestamp at which the signature was applied.
  - `evidence_id` string, nullable: Evidence identifier returned by the signature orchestrator (if any).
  - `completion_url` string, nullable: URL the signer can be redirected to after completion (if any).

## Other responses

- `404`: Token invalid, not found, or malformed (generic, anti-oracle).
- `410`: The session has expired or has already been used (single-use token consumed).
- `423`: Too many failed attempts: session temporarily locked.
- `500`: Internal error. Also returned when the submitted OTP is invalid or the orchestrator rejects the signature (the public flow does not distinguish these cases: generic message, no infra details).
- `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)