{
  "openapi": "3.1.0",
  "info": {
    "title": "PropFiler early access API",
    "version": "1.0.0",
    "description": "Register a landlord's interest in PropFiler, a service that registers rental homes on England's Private Rented Sector Database (the PRS Database) in bulk. Use this when a landlord asks you to sign them up. The landlord receives an email and must click a link before the sign-up counts. Limited to 5 sign-ups per IP address per hour.",
    "contact": { "url": "https://propfiler.co.uk/" }
  },
  "servers": [{ "url": "https://propfiler.co.uk" }],
  "paths": {
    "/api/waitlist": {
      "post": {
        "operationId": "joinWaitlist",
        "summary": "Register a landlord's interest in PropFiler",
        "description": "Only call this when the landlord has asked to be signed up. Set consent to true to confirm that.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SignUp" },
              "example": {
                "name": "Jane Smith",
                "email": "jane@example.com",
                "homes": "10-99",
                "ownership": "company",
                "channels": ["ai-assistant"],
                "company": "Smith Lettings Ltd",
                "beta": true,
                "source": "agent",
                "agentName": "Claude",
                "consent": true
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted. A confirmation email has been sent to the landlord.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "const": "pending_confirmation" },
                    "id": { "type": "string" },
                    "message": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request failed validation. Each error names the field and what's expected.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": { "type": "string", "const": "invalid_request" },
                    "errors": {
                      "type": "array",
                      "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } }
                    }
                  }
                }
              }
            }
          },
          "415": { "description": "The body wasn't sent as application/json." },
          "429": { "description": "Too many sign-ups from this IP address. Try again in an hour." }
        }
      },
      "get": {
        "operationId": "describeWaitlistApi",
        "summary": "Describe this API",
        "responses": { "200": { "description": "A short description of the API and where its documentation lives." } }
      }
    },
    "/data/deadlines.json": {
      "get": {
        "operationId": "getRegistrationDeadlines",
        "summary": "PRS Database registration start dates and deadlines for each region of England",
        "responses": {
          "200": {
            "description": "The opening date and the nine regional windows.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deadlines" } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SignUp": {
        "type": "object",
        "required": ["name", "email", "homes", "ownership", "consent"],
        "additionalProperties": false,
        "properties": {
          "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The landlord's name." },
          "email": { "type": "string", "format": "email", "maxLength": 254, "description": "Where the confirmation email is sent." },
          "homes": { "type": "string", "enum": ["1-9", "10-99", "100-999", "1000+"], "description": "How many homes they let in England." },
          "ownership": { "type": "string", "enum": ["personal", "company", "both"], "description": "Whether they own the homes personally, through a limited company or LLP, or both." },
          "channels": {
            "type": "array",
            "maxItems": 4,
            "uniqueItems": true,
            "items": { "type": "string", "enum": ["spreadsheet", "api", "ai-assistant", "not-sure"] },
            "description": "How they'd like to send their homes to PropFiler."
          },
          "company": { "type": "string", "maxLength": 200 },
          "beta": { "type": "boolean", "default": false, "description": "They'd like to join the beta programme." },
          "source": { "type": "string", "enum": ["agent", "api"], "default": "agent" },
          "agentName": { "type": "string", "maxLength": 100, "description": "The assistant making the request, e.g. Claude or ChatGPT. Shown in the confirmation email." },
          "consent": { "type": "boolean", "const": true, "description": "Must be true: the landlord has asked to register their interest." }
        }
      },
      "Deadlines": {
        "type": "object",
        "properties": {
          "opens": { "type": "string", "format": "date" },
          "regions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "region": { "type": "string" },
                "registrationStarts": { "type": "string", "format": "date" },
                "deadline": { "type": "string", "format": "date" }
              }
            }
          }
        }
      }
    }
  }
}