AgentFlow Enterprise Docs

API Reference — Lead Qualification

The real inspected qualification endpoint is `POST /api/ai/qualify-lead`; no `POST /api/qualify` route was found.

Endpoint

Method	Path	Runtime	Status
`POST`	`/api/ai/qualify-lead`	`nodejs`, dynamic	Implemented. This is the documented live route after code inspection.
`POST`	`/api/qualify`	Not found	Do not document as live unless a route is added later.

The route accepts either a signed-in Supabase dashboard session or an AgentFlow API key. API keys can be sent as Authorization: Bearer af_live_placeholder or x-agentflow-api-key: af_live_placeholder.

A valid request is resolved to an organization before rate-limit, billing, OpenAI, Supabase persistence, HubSpot sync, Slack/webhook dispatch, usage counter, and audit event operations run.

Request JSON Schema

Field	Required	Type	Validation
`lead_id`	No	UUID string	Existing lead to update; omitted for insert.
`name`	Yes	String	Trimmed, 2-120 characters.
`email`	Yes	Email string	Trimmed, valid email, max 180 characters, lowercased before save.
`company`	No	String	Max 140 characters; blank is treated as missing.
`phone`	No	String	Max 60 characters; blank is treated as missing.
`message`	Yes	String	Trimmed, 10-2000 characters.
`website`	No	String	Honeypot field. Leave empty; a populated value is blocked as spam.

Example requestjson

{
  "name": "Mira Example",
  "email": "[email protected]",
  "company": "Example B2B Studio",
  "phone": "+40 700 000 000",
  "message": "We need a server-side lead qualification workflow for inbound demo requests and CRM follow-up.",
  "website": ""
}

Success Response

The current route returns score, status, intent, confidence, summary, and recommended_action. Separate BANT keys such as fit_score, urgency, authority, budget, need, and timeline are not implemented as distinct response fields in the inspected code.

Example success responsejson

{
  "success": true,
  "lead": {
    "id": "lead_uuid_placeholder",
    "name": "Mira Example",
    "email": "[email protected]",
    "company": "Example B2B Studio",
    "phone": "+40 700 000 000",
    "message": "We need a server-side lead qualification workflow...",
    "score": 87,
    "status": "sales-ready",
    "intent": "high",
    "confidence": "high",
    "summary": "The lead describes a clear B2B qualification use case with operational urgency.",
    "ai_summary": "The lead describes a clear B2B qualification use case with operational urgency.",
    "recommended_action": "book-call",
    "priority": "high",
    "hubspot_sync_status": "not_configured",
    "hubspot_contact_id": null,
    "created_at": "2026-05-18T12:00:00.000Z"
  },
  "qualification": {
    "id": "qualification_uuid_placeholder",
    "score": 87,
    "status": "sales-ready",
    "intent": "high",
    "confidence": "high",
    "summary": "The lead describes a clear B2B qualification use case with operational urgency.",
    "recommended_action": "book-call",
    "model": "gpt-4o-mini",
    "created_at": "2026-05-18T12:00:00.000Z",
    "lead_id": "lead_uuid_placeholder",
    "organization_id": "organization_uuid_placeholder"
  },
  "hubspot": {
    "status": "not_configured"
  },
  "usage": {
    "metric": "ai_qualifications",
    "used": 12,
    "limit": 100,
    "remaining": 88,
    "periodStart": "2026-05-01T00:00:00.000Z",
    "periodEnd": "2026-06-01T00:00:00.000Z",
    "plan": "solo",
    "status": "active"
  },
  "organization": {
    "id": "organization_uuid_placeholder",
    "name": "Example Workspace"
  }
}

Validation and Rate Limits

Behavior	Current implementation
JSON parsing	Invalid JSON returns a validation error with HTTP 400.
Strict payload	Unknown fields fail validation because the Zod schema is strict.
Abuse checks	Honeypot, excessive links/emails, repeated characters, and spam-like terms are blocked.
Session limit	Signed-in users are limited to 100 qualification requests per minute.
API key limit	API-key requests are limited to 60 qualification requests per minute.
Production rate storage	Upstash Redis is used when configured; otherwise a per-instance in-memory fallback is used.

Errors and Security Notes

Example error responsejson

{
  "success": false,
  "stage": "validation",
  "message": "Lead payload failed validation.",
  "error": "Lead payload failed validation.",
  "details": [
    {
      "path": "email",
      "message": "Invalid email address"
    }
  ]
}

Never send OpenAI, Supabase service-role, Stripe, HubSpot, Slack, or Google secrets to the browser.
Validate and sanitize payloads before AI calls; the route strips unsafe control characters and treats lead fields as untrusted prompt data.
Avoid raw PII in logs. Log stage, organization id, event id, provider status, and safe error code where possible.
AI qualification requires an active subscription unless a platform-admin bypass applies in the server route.

These docs describe implementation readiness and configuration. They are not a SOC 2, ISO 27001, penetration test, or contractual SLA claim.

Endpoint

Authentication

Request JSON Schema

Success Response

Validation and Rate Limits

Errors and Security Notes