# LeadPilot API — Lead Ingestion & Idempotency

**Document Version:** 1.0.0 (Phase 11)  
**Authentication:** Bearer Token (API Key)  
**Base URL:** `/api/v1`

---

## 1. Create Lead

```http
POST /api/v1/leads
```

### Headers
```
Authorization: Bearer lp_live_YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: req_unique_id_12345 (Optional, recommended)
```

### Request Body
```json
{
  "first_name": "Sarah",
  "last_name": "Connor",
  "email": "sarah@resistance.io",
  "phone": "+155501992",
  "company": "Cyberdyne Systems",
  "inquiry_text": "Requesting immediate quote for defense automation.",
  "deal_value": 15000.00,
  "tags": ["uuid-tag-1", "uuid-tag-2"]
}
```

### Response (201 Created)
```json
{
  "success": true,
  "data": {
    "id": "9cb5a045-8fe1-4c48-8df0-202d6fae3b3a",
    "first_name": "Sarah",
    "last_name": "Connor",
    "email": "sarah@resistance.io",
    "phone": "+155501992",
    "company": "Cyberdyne Systems",
    "inquiry_text": "Requesting immediate quote for defense automation.",
    "deal_value": "15000.00",
    "status": "active",
    "ai_score": 50,
    "temperature": "WARM",
    "created_at": "2026-08-30T12:00:00Z"
  },
  "meta": {
    "is_duplicate": false,
    "duplicate_of_id": null,
    "followup_enrolled": true
  }
}
```

---

## 2. API Idempotency

When the `Idempotency-Key` header is provided:
- If a subsequent request arrives with the same key within 24 hours, LeadPilot returns the cached 201 response with header `Idempotency-Replay: true`.
- No duplicate lead is created.