# 🚀 Velo Universal Lead Capture API Documentation

This document provides technical instructions for integrating external websites (Landing Pages, E-commerce stores, etc.) with the Velo Dashboard.

## 🛠 Integration Overview

To capture leads from any website and route them to the correct Velo tenant workspace, you need to make an HTTP POST request to our centralized Edge Function.

### **Endpoint URL**
`https://fryqsyakqtnvprcyryvr.supabase.co/functions/v1/capture-lead`

### **Method**
`POST`

---

## 📬 Request Headers

| Header | Required | Value |
| :--- | :--- | :--- |
| `Content-Type` | Yes | `application/json` |
| `x-org-key` | Yes | The **Workspace Slug** (e.g., `acme-corp`). This identifies which dashboard the lead is routed to. |

---

## 📦 Request Body (JSON)

| Field | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `name` | String | No | Full name of the prospect. |
| `phone` | String | **Yes*** | Contact number. (*Required if email is not provided) |
| `email` | String | **Yes*** | Email address. (*Required if phone is not provided) |
| `message` | String | No | The inquiry or context text. |
| `source` | String | No | Origin of the lead (Default: `website`). |

---

## 💸 Implementation Examples

### **1. JavaScript (Fetch API)**
Recommended for most modern frameworks (Next.js, React, Vue, Vanilla JS).

```javascript
const submitLead = async (formData) => {
  try {
    const response = await fetch('https://fryqsyakqtnvprcyryvr.supabase.co/functions/v1/capture-lead', {  
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-org-key': 'YOUR_WORKSPACE_SLUG' // Replace with client's Velo slug
      },
      body: JSON.stringify({
        name: formData.name,
        phone: formData.phone,
        email: formData.email, // At least one of phone or email is required
        message: formData.message,
        source: 'website_landing_page'
      })
    });

    const result = await response.json();
    return result.success;
  } catch (error) {
    console.error('Lead capture failed:', error);
    return false;
  }
};
```

### **2. AI IDE Agent Prompt (Cursor/Windsurf/Copilot)**
If you are an AI agent building a landing page for a client, follow these steps:
1. Identify the client's workspace slug in Velo.
2. In the landing page's contact form handler, implement a `fetch` request to the endpoint above.
3. Ensure the `x-org-key` header perfectly matches the client's slug.
4. Add basic validation to ensure either the `phone` or `email` field is not empty.

---

## ★ Success Response
```json
{
  "success": true,
  "leadId": "uuid-of-the-saved-lead"
}
```

## ♜ Error Response
```json
{
  "error": "Error message details (e.g., Missing x-org-key header)"
}
```

---

## 📅 Security Note
This endpoint is CORS-enabled and designed to be called directly from client-side code (browsers). It uses workspace slugs for routing. **No sensitive private keys (like Service Role keys) should be exposed in the frontend code.**