# AI Lead Qualification

Turn a website enquiry into a scored lead, a spreadsheet row and a Slack notification. Keep the final decision with your team.

By AutomateHQ, an AI and workflow automation business serving companies in Singapore and Thailand.

Guide: https://automatehq.org/resources/n8n-ai-lead-qualification/

## Status and permission to use

Free to use and adapt in personal or commercial workflows. Provided as a starter without warranty. No signup. No secrets or pinned customer data. Local fixture tests cover Code node validation and export structure. Not yet imported into a live n8n instance or verified with provider credentials. Do not treat these checks as end-to-end certification.

## Requirements

- An n8n instance with Code, HTTP Request and Webhook nodes. The downloads use built-in nodes only; import compatibility still needs checking on your installed version.
- Your own OpenAI API account with billing enabled. Store the key in an n8n Header Auth credential named OpenAI: header Authorization, value Bearer followed by your key.
- A Google Sheets OAuth2 credential in n8n and a dedicated test spreadsheet. Enable the Sheets API and grant the connected account access to that spreadsheet.
- A Slack app with chat:write permission, invited to your test channel. Store its bot token in a separate Header Auth credential: Authorization: Bearer <token>.
- An n8n Webhook Header Auth credential with header X-AutomateHQ-Key and a long random value. Call this from your server, never from public browser code.

## Setup

1. Import the JSON using n8n’s Import from File command. Leave it inactive while configuring it.
2. Create a sheet tab named Leads and add the column headers below in exactly this order.
3. Fill in Configure workflow and attach the credentials listed below. Invite the Slack app to the channel.
4. Select Listen for test event in Receive lead. From a trusted server or terminal, POST the example JSON to the node’s Test URL with Content-Type: application/json and your X-AutomateHQ-Key header.
5. Confirm one row appears and one Slack message arrives. Verify that the webhook response includes the same lead_id. Try an invalid email and confirm no row is written.
6. Tune the prompt on representative enquiries. Activate only after testing, then replace the Test URL with the Production URL in your server-side form handler.

## Sheet columns, in order

```text
lead_id,name,email,company,score,priority,reason,needs_review
```

Sheets append uses RAW input, so text is not executed as spreadsheet formulas. No write node retries automatically.

## Configuration

### Configure workflow

Set spreadsheetId, sheetName and slackChannel. Set model to a structured-output-capable model available in your account (default: gpt-4o-mini).

### Receive lead

Select your Webhook Header Auth credential. Do not disable authentication.

### Classify with OpenAI

Select the OpenAI Header Auth credential. Edit the system prompt to describe your qualification rules.

### Append review row

Select your Google Sheets OAuth2 credential.

### Notify Slack

Select the separate Slack Header Auth credential.

## Example input

```json
{
  "lead_id": "demo-001",
  "name": "Alex Tan",
  "email": "alex@example.com",
  "company": "Example Logistics",
  "message": "We manually route 200 enquiries each week. Can you connect our form to a CRM and Slack?"
}
```

## Illustrative output (model output varies)

```json
{
  "lead_id": "demo-001",
  "score": 85,
  "priority": "high",
  "reason": "A specific recurring workflow and clear integration needs.",
  "needs_review": true
}
```

## Troubleshooting

### 401/403 at the webhook

Check the X-AutomateHQ-Key header and selected credential. Keep the secret on the sending server.

### OpenAI failure or invalid classification

The run stops before writing. Read the failed node; check quota, credentials, model access or output validation. API calls make up to three attempts.

### Sheet row exists but Slack failed

Do not rerun the entire workflow blindly. Check the row by lead_id and retry the notification only. Slack can return ok:false with HTTP 200; the workflow checks this.

Failed runs remain visible in n8n Executions; configure a separate error workflow for alerts. Webhook failures return an error rather than a success result. Check your caller's timeout; a timeout does not prove that no external write happened.

## Limitations

- The score is a model suggestion, not a probability of conversion. Every lead remains marked for human review.
- This starter appends records. It does not merge CRM contacts, prevent repeated webhook submissions or send lead follow-ups.
- Google Forms is not connected automatically. Connect a trusted form handler that sends the documented JSON payload.

## From demo to production

- Store lead_id in a durable database with a unique constraint before writing to external systems. A retry after a timeout may otherwise create another row.
- Separate intake from delivery with a queue. Track sheet and Slack delivery independently so a Slack outage cannot duplicate a lead.
- Define qualification rules, consent, record ownership and review responsibility. Test multilingual Singapore and Thailand enquiries against a labelled sample.
- Add per-sender rate limits, monitoring and cost budgets. Alert an owner on failures without including full enquiry text.

## Security and retention

The submitted name, email, company and message go to OpenAI; lead details go to your spreadsheet. Slack receives only the lead ID, priority and score. Use synthetic leads first, restrict sheet access and set an execution-data retention policy in n8n. Successful production execution payloads are not saved by this export; manual and failed executions are saved for debugging. Set pruning and binary-data retention explicitly, and delete synthetic test runs when finished. Header credentials may appear in webhook execution inputs; restrict access and rotate test keys.

## Costs

One model request, one Sheets append and one Slack message per valid lead; a transient model failure can make up to three model attempts. Add n8n hosting or execution charges and any workspace plan costs. Estimate per 1,000 runs as (input tokens × input price per million + output tokens × output price per million) / 1,000, then add hosting and retries. Use current pricing at https://openai.com/api/pricing/ and https://n8n.io/pricing/.

## Customization

- Replace the sheet with your CRM after adding contact matching.
- Route high-priority leads to an owner using explicit territory rules.
- Add a review queue before creating follow-up drafts.

## Live acceptance checklist

- Record n8n version and import the JSON; confirm every node and credential type resolves.
- Configure only sandbox accounts and synthetic data.
- Run a valid case; compare each external write to the validated result.
- Run invalid input and simulated model refusal; confirm no downstream writes.
- Simulate provider failure and inspect partial completion.
- Check duplicate/retry behavior and delete test data.
- Record results before submitting to n8n or claiming live compatibility.

Need this connected to your actual systems? https://automatehq.org/#request-demo