API REFERENCE · V1

Messages, safely delivered.

KindHello accepts contact inquiries and structured service leads from an exact approved web origin. Public form keys are not admin credentials.

All public requests require JSON, a blank honeypot field, and a valid Turnstile token. The owning organization controls the form’s allowed origins and recipient.

POST/v1/forms/:formKey/inquiries

fetch("https://kindhello.dev/v1/forms/your-form-key/inquiries", {
  method: "POST", headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Maya Chen", email: "maya@example.com",
    subject: "Hello", message: "Could you help?",
    sourceUrl: location.href, turnstileToken, website: ""
  })
})

Required: name, email, message, turnstileToken.
Optional: subject and sourceUrl.

POST/v1/forms/:formKey/leads

Lead forms must have a server-configured schema. Send a name, at least one valid contact method, and only the approved detail fields.

{
  "name":"Jordan Lee",
  "contact":{"phone":"+1 207 555 0142","preferred":"phone"},
  "details":{"jobType":"Tree removal","location":"Brunswick, ME"},
  "turnstileToken":"…", "website":""
}

<div data-kind-contact
  data-form="your-public-form-key"
  data-turnstile-key="your-turnstile-site-key"></div>
<script src="https://kindhello.dev/v1/widgets/contact.js" defer></script>

The widget renders an accessible contact form and submits to the same protected inquiry endpoint.

Operator API

Internal management endpoints live beneath /v1/operator/ and require the server-only OPERATOR_API_KEY. They are never called from browser code.

GET /v1/operator/forms: List organizations and forms.
POST /v1/operator/forms: Provision a form with a recipient, exact HTTPS origins, and optional lead schema.
PATCH /v1/operator/forms/:id: Change recipient, origins, active state, or lead schema.
PATCH /v1/operator/organizations/:id: Change retention (30–365 days) or close/reopen an organization.
PATCH /v1/operator/forms/:formKey/inquiries/:id: Set new, reviewed, resolved, or archived.
PATCH /v1/operator/forms/:formKey/leads/:id: Set the documented lead status.

Data lifecycle

Unread inquiries and leads are deleted after 30 days. Once reviewed or handled, they are retained for 90 days from their latest handling event. When an organization closes, its configured 30–365 day closure window deletes any remaining intake data. Purge receipts retain aggregate counts only.

Responses