API Docs

Developer trust for the AI lead qualification endpoint.

A practical reference for the live AI qualification API, including request shape, response shape, rate limits, HubSpot sync behavior, and structured errors.

POST /api/ai/qualify-lead

Endpoint URL

https://agentflow-enterprise.com/api/ai/qualify-lead

Request body

{
  "name": "Marius Pop",
  "email": "[email protected]",
  "company": "B2B Agency",
  "message": "We need an AI system to qualify inbound leads and automate follow-up.",
  "website": ""
}

Response body

{
  "success": true,
  "qualification": {
    "id": "uuid",
    "score": 91,
    "status": "sales-ready",
    "intent": "high",
    "confidence": "high",
    "summary": "High-intent agency lead with a clear qualification use case.",
    "recommended_action": "book-call",
    "created_at": "2026-05-08T10:00:00.000Z",
    "lead_id": "uuid",
    "organization_id": "uuid"
  },
  "lead": {
    "id": "uuid",
    "created_at": "2026-05-06T10:00:00.000Z",
    "name": "Marius Pop",
    "email": "[email protected]",
    "company": "B2B Agency",
    "score": 91,
    "status": "sales-ready",
    "intent": "high",
    "confidence": "high",
    "ai_summary": "High-intent agency lead with a clear qualification use case.",
    "recommended_action": "book-call",
    "priority": "high",
    "hubspot_sync_status": "synced",
    "hubspot_contact_id": "123456",
    "source": "ai_qualification"
  },
  "hubspot": {
    "status": "synced",
    "contactId": "123456"
  }
}

Example curl

curl -X POST https://agentflow-enterprise.com/api/ai/qualify-lead \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer af_live_your_api_key" \
  -d '{
    "name": "Marius Pop",
    "email": "[email protected]",
    "company": "B2B Agency",
    "message": "We need an AI system to qualify inbound leads and automate follow-up.",
    "website": ""
  }'

OpenAPI-style summary

paths:
  /api/ai/qualify-lead:
    post:
      summary: Qualify a lead with AI and persist the result
      security:
        - cookieSession: []
        - agentflowApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, email, message]
              properties:
                name:
                  type: string
                  maxLength: 120
                email:
                  type: string
                  format: email
                  maxLength: 180
                company:
                  type: string
                  maxLength: 140
                message:
                  type: string
                  maxLength: 2000
                website:
                  type: string
                  description: Honeypot field. Leave empty.
      responses:
        "200":
          description: Lead qualified, saved, and optionally synced to HubSpot.
        "400":
          description: validation_error
        "429":
          description: rate_limited
        "402":
          description: subscription_required or limit_reached
        "500":
          description: supabase_error or unknown_error
        "503":
          description: openai_error

Error codes

validation_error

Invalid JSON, missing fields, invalid email, or message over 1000 characters.

auth

The request does not include a signed-in session or valid AgentFlow API key.

billing

The workspace has no active subscription or has reached its usage limit.

rate_limited

Too many requests or abuse protection triggered.

openai_error

The OpenAI qualification call failed or returned an invalid JSON object.

supabase_error

The AI result was generated but Supabase insert, update, or usage tracking failed.

unknown_error

Server configuration, session verification, or an unexpected runtime issue failed.

Security and rate limits

  • OPENAI_API_KEY, the Supabase service-role secret, STRIPE_SECRET_KEY, and HUBSPOT_ACCESS_TOKEN must remain server-side only.
  • The endpoint requires an authenticated dashboard session or an AgentFlow API key. Public AI preview usage is not enabled.
  • AgentFlow API keys are shown once in Settings and only SHA-256 hashes are stored.
  • The endpoint validates with Zod, enforces max field lengths, strips unsafe control characters, and treats lead text as untrusted data in the AI prompt.
  • The website honeypot field is accepted for form compatibility and blocked when populated.
  • Upstash Redis rate limiting is used when UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN exist. Local development falls back to a conservative in-memory limiter; production fails closed if Redis is not configured.

HubSpot sync behavior

After AI qualification and Supabase insert, the server attempts a HubSpot contact upsert when HUBSPOT_ACCESS_TOKEN is configured. Missing tokens return hubspot.status as not_configured. HubSpot API failures do not block lead storage; the lead is updated with hubspot_sync_status failed.