RAIA Enquiry

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://estateaigents.org/schemas/enquiry.json",
  "title": "RAIA Enquiry",
  "description": "Body of an enquiry POSTed to the agent card's endpoints.enquire URL. Initiates the RAIA Protocol session state machine described in SPEC.md section 6. v0.2 standardises the enquirer block, adds source provenance, and requires submitted_at.",
  "type": "object",

  "$defs": {
    "enquirer_block": {
      "type": "object",
      "description": "The party making the enquiry. For consumer-agent traffic, this is the end client whose AI assistant is acting on their behalf. Per ADR-211 / SPEC.md section 2.4, end-client identity is shared at this point — the enquiry is the moment PII first crosses the agent boundary.",
      "required": ["name", "email"],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "description": "Full name of the enquirer."
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "Contact email address. Required."
        },
        "phone": {
          "type": "string",
          "description": "Contact phone number. E.164 format strongly preferred (e.g. '+447947552000')."
        },
        "preferred_contact": {
          "type": "string",
          "enum": ["email", "phone", "whatsapp"],
          "description": "Channel the enquirer prefers for follow-up. Receiving agents SHOULD respect this where operationally possible."
        }
      },
      "additionalProperties": false
    },

    "viewing_request_block": {
      "type": "object",
      "description": "Optional viewing-request payload. If present, the receiving agent should treat the enquiry as a viewing request (SPEC.md section 6 — Viewing request).",
      "properties": {
        "preferred_dates": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "date-time"
          },
          "minItems": 1,
          "maxItems": 3,
          "description": "Up to three proposed slots. SPEC.md section 6 limits to three."
        },
        "party_size": {
          "type": "integer",
          "minimum": 1,
          "description": "Number of attendees expected at the viewing."
        }
      },
      "additionalProperties": false
    },

    "source_block": {
      "type": "object",
      "description": "Provenance of the enquiry. Helps the receiving agent attribute conversion and apply per-source rate limits.",
      "properties": {
        "origin": {
          "type": "string",
          "description": "Logical origin of the enquiry. Common values: 'movehome.org', 'agent_site', 'raia_aggregator', 'consumer_agent'. Free-text — registry curates the canonical list.",
          "examples": ["movehome.org", "agent_site", "raia_aggregator", "consumer_agent"]
        },
        "user_id_hash": {
          "type": "string",
          "description": "Optional SHA-256 hash of the originating user's identifier on the source platform. Allows deduplication without exposing PII."
        },
        "ip_country": {
          "type": "string",
          "pattern": "^[A-Z]{2}$",
          "description": "ISO 3166-1 alpha-2 country code derived from the originating IP. Useful for jurisdictional filtering. Two letters only — never the full IP."
        }
      },
      "additionalProperties": false
    }
  },

  "required": ["enquiry_id", "raia_id", "enquirer", "message", "submitted_at"],

  "properties": {
    "enquiry_id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID generated by the sender. Used for idempotency — replays of the same enquiry_id MUST NOT create duplicate records."
    },
    "raia_id": {
      "type": "string",
      "pattern": "^prop-[a-z]{2}-[a-z0-9-]{2,32}-[0-9]{4,}$",
      "description": "Property identifier the enquiry is about. Must reference a listing visible to the sender."
    },
    "enquirer": {
      "$ref": "#/$defs/enquirer_block"
    },
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000,
      "description": "Free-text message from the enquirer. Receiving agents should treat this as untrusted input and sanitise before display or LLM processing."
    },
    "viewing_request": {
      "$ref": "#/$defs/viewing_request_block"
    },
    "source": {
      "$ref": "#/$defs/source_block"
    },
    "submitted_at": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp at which the sender constructed the enquiry. Receiving agents may reject enquiries with submitted_at more than 24 hours in the past or any time in the future."
    }
  },

  "additionalProperties": false,

  "examples": [
    {
      "enquiry_id": "0d8b57ee-58a4-4bbf-9c2c-19c67d3f7c12",
      "raia_id": "prop-gb-rlf-000142",
      "enquirer": {
        "name": "Aria Patel",
        "email": "aria.patel@example.com",
        "phone": "+447700900123",
        "preferred_contact": "whatsapp"
      },
      "message": "Hi — I'm relocating from Manchester for a role in Shoreditch in late June. Couple, no pets, both employed (combined income ~£95k). Could we view this on a weekday evening?",
      "viewing_request": {
        "preferred_dates": [
          "2026-06-03T18:30:00+01:00",
          "2026-06-04T18:30:00+01:00",
          "2026-06-05T18:00:00+01:00"
        ],
        "party_size": 2
      },
      "source": {
        "origin": "movehome.org",
        "user_id_hash": "f3d4a8c2b1e0974f5d6a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e",
        "ip_country": "GB"
      },
      "submitted_at": "2026-05-07T11:42:18Z"
    }
  ],

  "x-raia-notes": {
    "session_state": "A successful enquiry POST creates a session in state IDENTIFIED (per SPEC.md section 6). The receiving agent advances state and reports back via the response body or a callback URL — channel TBD in v1.0.",
    "rate_limiting": "Receiving agents SHOULD rate-limit enquiries by enquirer.email and source.user_id_hash. Reasonable defaults: 5 enquiries per hour per email; 20 per hour per origin.",
    "pii_boundary": "The enquirer block is the first message in the protocol that contains end-client PII. Until this point, listings and search responses are anonymous. Aggregators that proxy enquiries MUST forward this block intact and MUST NOT log it beyond standard request-trace retention."
  }
}