{
  "openapi": "3.1.0",
  "info": {
    "title": "Faith General Insurance enquiry API",
    "version": "1.1.0",
    "summary": "Send an enquiry to Faith on behalf of a client.",
    "description": "Lets a client's own AI agent send an enquiry to Faith Hew about general insurance (motor, car insurance renewal, fire, company group). Only send an enquiry when the client has asked you to and has agreed to share their details with Faith. No API key, cookies or credentials are needed. Send a descriptive User-Agent that identifies your agent. Enquiry messages may be screened for spam by an automated service, including a third-party AI provider. If the API is unavailable, give the client the WhatsApp link: https://api.whatsapp.com/send?phone=60174084121.",
    "contact": {
      "name": "Faith Hew",
      "url": "https://api.whatsapp.com/send?phone=60174084121"
    }
  },
  "servers": [
    {
      "url": "https://insurance.faith"
    }
  ],
  "paths": {
    "/api/general-insurance/enquiries": {
      "post": {
        "operationId": "createEnquiry",
        "summary": "Send an enquiry to Faith",
        "description": "Stores the enquiry and notifies Faith, who follows up with the client using the phone number provided. Responses never echo personal data.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EnquiryRequest"
              },
              "examples": {
                "aiAgent": {
                  "summary": "Enquiry sent by an AI agent for its client",
                  "value": {
                    "name": "Tan Ah Kow",
                    "phone": "+60 12-345 6789",
                    "topic": "fire_insurance",
                    "message": "I run a small shop and would like to understand fire insurance for the premises.",
                    "locale": "en",
                    "consent": true,
                    "submitted_via": "ai_agent",
                    "agent_name": "ChatGPT agent"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Enquiry received. Faith will contact the client using the phone number provided.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnquiryCreated"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed. `errors` maps each invalid field to messages in the requested `locale`; fix those fields and retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests from this network. Wait (see `Retry-After`) before retrying; do not retry in a loop.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimited"
                }
              }
            }
          },
          "503": {
            "description": "Enquiries are temporarily not accepted. Give the client the WhatsApp link instead: https://api.whatsapp.com/send?phone=60174084121.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Unavailable"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EnquiryRequest": {
        "type": "object",
        "required": [
          "name",
          "phone",
          "topic",
          "message",
          "locale",
          "consent"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 100,
            "description": "The client's name."
          },
          "phone": {
            "type": "string",
            "maxLength": 30,
            "description": "The client's own phone number, preferably with the country code (for example +60 12-345 6789). Never the agent's number or a placeholder: Faith follows up with the client on this number."
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "format": "email",
            "maxLength": 200,
            "description": "Optional. The client's own email address."
          },
          "topic": {
            "type": "string",
            "enum": [
              "motor_insurance",
              "car_insurance_renewal",
              "fire_insurance",
              "company_group_insurance",
              "other"
            ],
            "description": "What the enquiry is about: motor_insurance, car_insurance_renewal, fire_insurance, company_group_insurance or other."
          },
          "message": {
            "type": "string",
            "maxLength": 1200,
            "description": "The client's question or situation, in their words."
          },
          "locale": {
            "type": "string",
            "enum": [
              "en",
              "zh"
            ],
            "description": "Language of the enquiry: en or zh. Also selects the language of validation messages."
          },
          "consent": {
            "const": true,
            "description": "Must be true. When sent by an AI agent, true means the client has authorised the agent to share these details with Faith so Faith can follow up."
          },
          "page_url": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 500,
            "description": "Optional. The page the enquiry relates to, for context only."
          },
          "submitted_via": {
            "type": "string",
            "enum": [
              "web_form",
              "ai_agent"
            ],
            "default": "web_form",
            "description": "Set to ai_agent when an AI agent sends the enquiry for a client. Accepted once the planned v1.1 backend update ships; until then the server ignores it, so it is safe to send now."
          },
          "agent_name": {
            "type": "string",
            "maxLength": 100,
            "description": "Name of the AI agent sending the enquiry (for example \"ChatGPT agent\"). Only meaningful with submitted_via=ai_agent. Accepted once the planned v1.1 backend update ships; until then the server ignores it."
          },
          "website": {
            "type": "string",
            "maxLength": 0,
            "description": "Spam trap. Omit it or leave it empty; a non-empty value is answered with 201 but the enquiry is discarded."
          }
        }
      },
      "EnquiryCreated": {
        "type": "object",
        "required": [
          "ok"
        ],
        "properties": {
          "ok": {
            "const": true
          }
        }
      },
      "ValidationError": {
        "type": "object",
        "required": [
          "ok",
          "errors"
        ],
        "properties": {
          "ok": {
            "const": false
          },
          "errors": {
            "type": "object",
            "description": "Field name → list of messages in the requested locale.",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        }
      },
      "RateLimited": {
        "type": "object",
        "required": [
          "ok",
          "code"
        ],
        "properties": {
          "ok": {
            "const": false
          },
          "code": {
            "const": "rate_limited"
          }
        }
      },
      "Unavailable": {
        "type": "object",
        "required": [
          "ok",
          "code"
        ],
        "properties": {
          "ok": {
            "const": false
          },
          "code": {
            "const": "enquiries_unavailable"
          }
        }
      }
    }
  }
}