{
  "openapi": "3.1.0",
  "info": {
    "title": "ArvokasArki contact / yhteydenotto API",
    "version": "1.0.0",
    "description": "Submit a contact request (lead) for ArvokasArki (Ristilä Group Oy), a Valvira-approved provider of VAT-free social support services (tukipalvelut) and home cleaning (kotisiivous) for the elderly and families in the Seinäjoki–Vaasa region of Finland. No API key required. Creating a lead does not create a quote and shows no prices — a human calls the customer back. Only submit with the customer's informed consent and their real details.",
    "contact": {
      "name": "ArvokasArki",
      "url": "https://arvokasarki.fi/",
      "email": "asiakaspalvelu@arvokasarki.fi"
    }
  },
  "servers": [{ "url": "https://arvokasarki.fi" }],
  "paths": {
    "/api/lead": {
      "get": {
        "operationId": "getLeadApiUsage",
        "summary": "Machine-readable usage document",
        "description": "Returns a JSON description of how to submit a contact request. Also the post-deploy health check.",
        "responses": {
          "200": {
            "description": "Usage document",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      },
      "post": {
        "operationId": "submitContactRequest",
        "summary": "Submit a contact request (lead)",
        "description": "Creates a lead in the ArvokasArki CRM. A human follows up by phone. Idempotent on external_id.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ContactRequest" },
              "examples": {
                "tukipalvelut": {
                  "summary": "Elderly support enquiry, AI-assisted",
                  "value": {
                    "name": "Maija Meikäläinen",
                    "phone": "0401234567",
                    "email": "maija@example.fi",
                    "services": ["tukipalvelut"],
                    "message": "Äitini (82) tarvitsisi apua kaupassa käyntiin ja seuraa viikoittain.",
                    "agent": "Claude (Anthropic)",
                    "external_id": "arvokasarki-yhteydenotto-2f6f6c1e-6b7a-4e0e-9d3d-1a2b3c4d5e6f"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Accepted. duplicate=true means the same external_id already succeeded. portal_url is the customer's self-service page (may be absent).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "duplicate": { "type": "boolean" },
                    "portal_url": {
                      "type": "string",
                      "format": "uri",
                      "description": "Customer self-service portal (view status, message the team). Share with the customer; do not open it yourself."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error. `fields` carries per-field Finnish messages.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          },
          "413": { "description": "Request body over 10 KB." },
          "502": { "description": "Temporary upstream failure — retry later with the SAME external_id." }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ContactRequest": {
        "type": "object",
        "required": ["name", "phone"],
        "additionalProperties": false,
        "properties": {
          "name": { "type": "string", "maxLength": 200, "description": "Customer's real name" },
          "phone": { "type": "string", "maxLength": 50, "description": "Primary contact channel" },
          "email": { "type": "string", "format": "email", "maxLength": 254, "description": "Recommended, not required" },
          "services": {
            "type": "array",
            "items": { "type": "string", "enum": ["tukipalvelut", "kotisiivous"] },
            "description": "Service interest — descriptive only, no pricing implication"
          },
          "palveluseteli": {
            "type": "boolean",
            "description": "Does the customer have a palveluseteli (service voucher)? Omit if unknown. Also accepts the strings 'kyllä'/'ei'. Wired to the DiiliPutki 'palveluseteli' custom field."
          },
          "message": { "type": "string", "maxLength": 2000, "description": "Kind of help needed, situation, schedule" },
          "agent": { "type": "string", "maxLength": 200, "description": "AI-assistant self-identification, e.g. 'Claude (Anthropic)'. Set when submitting on a customer's behalf." },
          "external_id": { "type": "string", "description": "arvokasarki-yhteydenotto-<uuid v4>; generate once per intent, reuse on retries" },
          "page_url": { "type": "string", "format": "uri" },
          "utm_source": { "type": "string", "maxLength": 200 },
          "utm_medium": { "type": "string", "maxLength": 200 },
          "utm_campaign": { "type": "string", "maxLength": 200 },
          "utm_content": { "type": "string", "maxLength": 200 },
          "utm_term": { "type": "string", "maxLength": 200 }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean", "enum": [false] },
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" }
            }
          },
          "fields": { "type": "object", "additionalProperties": { "type": "string" } }
        }
      }
    }
  }
}