{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://hou.realtor/schemas/referral.submit.schema.json",
  "title": "referral.submit",
  "description": "Refer a client to Tiffany (from another licensed agent). Information and proposals only. Nothing in a request is binding: offers, contracts, earnest money, and representation agreements require Tiffany Hua's own signature. Send by email to tiffany@hou.realtor with subject '[referral.submit] <short summary>' and the request JSON as the body; natively delivery comes once hou.realtor's entity record is published (https://hou.realtor/agent.html).",
  "type": "object",
  "required": [
    "type",
    "schema_version",
    "agent",
    "contact",
    "referrer",
    "client_consent",
    "side",
    "timing"
  ],
  "anyOf": [
    {
      "required": [
        "area"
      ]
    },
    {
      "required": [
        "property"
      ]
    }
  ],
  "properties": {
    "type": {
      "const": "referral.submit"
    },
    "schema_version": {
      "const": "0.1"
    },
    "sent_at": {
      "type": "string",
      "format": "date-time"
    },
    "agent": {
      "$ref": "#/$defs/agent"
    },
    "contact": {
      "$ref": "#/$defs/contact"
    },
    "referrer": {
      "type": "object",
      "description": "The licensed agent making the referral. contact is the client being referred.",
      "required": [
        "name",
        "brokerage",
        "license_number",
        "license_state",
        "email"
      ],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1
        },
        "brokerage": {
          "type": "string",
          "minLength": 1
        },
        "license_number": {
          "type": "string",
          "minLength": 1
        },
        "license_state": {
          "type": "string",
          "pattern": "^[A-Z]{2}$"
        },
        "email": {
          "type": "string",
          "format": "email"
        },
        "phone": {
          "type": "string",
          "minLength": 7
        }
      }
    },
    "client_consent": {
      "const": true,
      "description": "The client agreed to be referred and to have these details shared."
    },
    "side": {
      "enum": [
        "buyer",
        "seller",
        "both"
      ]
    },
    "area": {
      "$ref": "#/$defs/area"
    },
    "property": {
      "$ref": "#/$defs/property"
    },
    "timing": {
      "$ref": "#/$defs/timing"
    },
    "proposed_referral_fee_percent": {
      "type": "number",
      "minimum": 0,
      "maximum": 100,
      "description": "A proposal only. Referral fees are paid through Tiffany's sponsoring broker, Texas Signature Realty, LLC, and nothing is agreed until a written referral agreement is signed."
    },
    "notes": {
      "type": "string",
      "maxLength": 2000
    }
  },
  "$defs": {
    "agent": {
      "type": "object",
      "description": "The sending agent's identity, in natively agent-card shape (https://natively.io/BOOTSTRAP.html, card fields agent_key, principal, ledger). An agent without a natively identity yet sets agent_key and ledger to null; its request is then handled as unverified information.",
      "required": [
        "agent_key",
        "principal",
        "ledger"
      ],
      "properties": {
        "agent_key": {
          "type": [
            "string",
            "null"
          ],
          "pattern": "^ed25519:[A-Za-z0-9+/]{43}=$",
          "description": "Your Ed25519 public key, 'ed25519:' + base64 of the 32 raw bytes. Never send a private key."
        },
        "principal": {
          "type": "string",
          "minLength": 1,
          "description": "Key ref of the human you act for. Until your principal has a signer, use their email address."
        },
        "ledger": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri",
          "description": "URL of your hash-chained ledger, or null if you do not keep one yet."
        },
        "name": {
          "type": "string",
          "description": "Optional display name for the agent."
        },
        "card_url": {
          "type": "string",
          "format": "uri",
          "description": "Optional URL of your published agent card."
        }
      }
    },
    "contact": {
      "type": "object",
      "description": "The human Tiffany would reply to. Give at least an email or a phone number.",
      "required": [
        "name"
      ],
      "anyOf": [
        {
          "required": [
            "email"
          ]
        },
        {
          "required": [
            "phone"
          ]
        }
      ],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1
        },
        "email": {
          "type": "string",
          "format": "email"
        },
        "phone": {
          "type": "string",
          "minLength": 7
        },
        "preferred_channel": {
          "enum": [
            "email",
            "phone",
            "text",
            "natively"
          ]
        }
      }
    },
    "property": {
      "type": "object",
      "description": "A specific property. Give at least one of address, mls_number, or listing_url.",
      "anyOf": [
        {
          "required": [
            "address"
          ]
        },
        {
          "required": [
            "mls_number"
          ]
        },
        {
          "required": [
            "listing_url"
          ]
        }
      ],
      "properties": {
        "address": {
          "type": "string",
          "minLength": 5,
          "description": "Street, city, state, ZIP on one line."
        },
        "mls_number": {
          "type": "string",
          "minLength": 1
        },
        "listing_url": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "area": {
      "type": "object",
      "description": "Where in Texas. Give at least one of cities, neighborhoods, zip_codes, or description.",
      "anyOf": [
        {
          "required": [
            "cities"
          ]
        },
        {
          "required": [
            "neighborhoods"
          ]
        },
        {
          "required": [
            "zip_codes"
          ]
        },
        {
          "required": [
            "description"
          ]
        }
      ],
      "properties": {
        "cities": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "neighborhoods": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "zip_codes": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string",
            "pattern": "^[0-9]{5}$"
          }
        },
        "description": {
          "type": "string",
          "minLength": 1
        }
      }
    },
    "timing": {
      "type": "object",
      "required": [
        "horizon"
      ],
      "properties": {
        "horizon": {
          "enum": [
            "asap",
            "0-3 months",
            "3-6 months",
            "6-12 months",
            "12+ months",
            "unsure"
          ]
        },
        "earliest": {
          "type": "string",
          "format": "date"
        },
        "latest": {
          "type": "string",
          "format": "date"
        }
      }
    }
  },
  "examples": [
    {
      "type": "referral.submit",
      "schema_version": "0.1",
      "sent_at": "2026-10-21T15:00:00Z",
      "agent": {
        "agent_key": null,
        "principal": "jordan@example.com",
        "ledger": null,
        "name": "Jordan's assistant"
      },
      "contact": {
        "name": "Jordan Example",
        "email": "jordan@example.com",
        "preferred_channel": "email"
      },
      "referrer": {
        "name": "Sam Example",
        "brokerage": "Example Realty",
        "license_number": "000000",
        "license_state": "CA",
        "email": "sam@example.com"
      },
      "client_consent": true,
      "side": "buyer",
      "area": {
        "description": "West Houston, good schools, under 40 minutes to the Energy Corridor"
      },
      "timing": {
        "horizon": "3-6 months"
      },
      "proposed_referral_fee_percent": 25
    }
  ]
}