# Hifisys Enterprise REST API Platform Documentation

> **Version:** 1.0.0 | **Base URL:** `https://hifisys.com/api/v1` | **Provider:** Hifisys

## Overview
The Hifisys Enterprise API Platform provides robust, enterprise-grade REST interfaces for HRMS automation, conversational AI bots, automated SEO content creation, and high-fidelity AI-driven page building. All APIs adhere strictly to standard REST conventions, provide low-latency JSON payloads, and utilize granular scope-based security.

## Authentication
All requests require a valid API key passed in the request header:
```http
X-API-Key: YOUR_API_KEY
Accept: application/json
```
Alternatively, pass as a standard Bearer token:
```http
Authorization: Bearer YOUR_API_KEY
```

## Included Products
- **[HRMS API](hrms-api)**: Complete enterprise human resource management API for employee lifecycle, attendance, leaves, payroll, payslips, work logs, and analytics. (`https://hifisys.com/api/v1/hrms`)
- **[Chatbot API](chatbot-api)**: Context-aware conversational AI assistant API powered by Google Gemini with company services and navigation awareness. (`https://hifisys.com/api/v1/chatbot`)
- **[AI Blog Generator API](ai-blog-generator-api)**: Production-grade AI article engine that creates long-form, reader-first content, outlines, and SEO metadata. (`https://hifisys.com/api/v1/ai/blog`)
- **[AI Page Builder API](ai-page-builder-api)**: High-conversion website architecture API that generates semantic page sections, hero banners, and service copy. (`https://hifisys.com/api/v1/ai/page-builder`)
- **[Hifisys Enterprise HRMS Suite](enterprise-hrms-suite)**: Full-featured enterprise web software for workforce lifecycle management, biometric/web attendance, shift scheduling, leave approvals, payroll generation, recruitment ATS, and Employee Self-Service (ESS) portal. (`https://hifisys.com/api/v1`)
- **[Hifisys Enterprise SEO Control Center](enterprise-seo-control-center)**: Comprehensive 16-module SEO auditing, technical diagnostics, keyword rank tracking, Core Web Vitals monitoring, internal link graph analyzer, and schema markup software suite. (`https://hifisys.com/api/v1`)
- **[Hifisys CRM & Lead Automation Platform](crm-lead-automation-platform)**: Complete Zoho CRM-grade customer relationship platform and API suite. Unifies multi-channel lead capture, contact & account management, configurable visual sales pipelines, automated workflow triggers, multi-tenant REST APIs, and revenue analytics. (`https://hifisys.com/api/v1/leads`)

---
# Product: HRMS API
Base URL: `https://hifisys.com/api/v1/hrms`

### `GET` /api/v1/hrms/employees
**List Company Employees**
> **Scope:** `employees:read` | **Content-Type:** `application/json`

Returns a paginated list of company employees with department, designation, and employment status.

#### Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Search by name, employee code, or email. |
| `department_id` | `integer` | No | Filter by department ID. |
| `status` | `string` | No | active, inactive, probation, terminated. |

#### Example Requests
**cURL:**
```bash
curl -X GET "https://hifisys.com/api/v1/hrms/employees?status=active" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
```
**JavaScript:**
```javascript
const res = await fetch('https://hifisys.com/api/v1/hrms/employees?status=active', {
  headers: { 'X-API-Key': 'YOUR_API_KEY', 'Accept': 'application/json' }
});
const data = await res.json();
```
**PHP:**
```php
$ch = curl_init('https://hifisys.com/api/v1/hrms/employees?status=active');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: YOUR_API_KEY', 'Accept: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
```
**Python:**
```python
import requests
res = requests.get('https://hifisys.com/api/v1/hrms/employees?status=active', headers={'X-API-Key': 'YOUR_API_KEY'})
print(res.json())
```

#### Sample Response (200 OK)
```json
{
    "success": true,
    "data": [
        {
            "id": 1,
            "employee_code": "EMP-001",
            "full_name": "Sarah Connor",
            "email": "sarah@example.com",
            "department": "Engineering",
            "designation": "Staff Engineer",
            "employment_status": "active"
        }
    ]
}
```

---

### `POST` /api/v1/hrms/attendance/clock-in
**Attendance Clock-In**
> **Scope:** `attendance:write` | **Content-Type:** `application/json`

Records employee punch-in timestamp, location coordinates/mode, and IP address.

#### Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `employee_id` | `integer` | **Yes** | Unique employee identifier. |
| `work_mode` | `string` | No | office, remote, hybrid. Default: office. |

#### Example Requests
**cURL:**
```bash
curl -X POST "https://hifisys.com/api/v1/hrms/attendance/clock-in" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"employee_id":1,"work_mode":"office"}'
```
**JavaScript:**
```javascript
const res = await fetch('https://hifisys.com/api/v1/hrms/attendance/clock-in', {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ employee_id: 1, work_mode: 'office' })
});
```
**PHP:**
```php
$ch = curl_init('https://hifisys.com/api/v1/hrms/attendance/clock-in');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['employee_id' => 1, 'work_mode' => 'office']));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: YOUR_API_KEY', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
```
**Python:**
```python
import requests
res = requests.post('https://hifisys.com/api/v1/hrms/attendance/clock-in', json={'employee_id': 1, 'work_mode': 'office'}, headers={'X-API-Key': 'YOUR_API_KEY'})
print(res.json())
```

#### Sample Response (200 OK)
```json
{
    "success": true,
    "message": "Clock-in recorded successfully at 09:00:00.",
    "data": {
        "attendance_id": 124,
        "clock_in": "2026-10-07 09:00:00"
    }
}
```

---

---
# Product: Chatbot API
Base URL: `https://hifisys.com/api/v1/chatbot`

### `POST` /api/v1/chatbot/message
**Send Conversational Message**
> **Scope:** `chat:message` | **Content-Type:** `application/json`

Dispatches a visitor prompt to the Hifisys conversational knowledge-base assistant and returns AI-generated response with suggested quick replies.

#### Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `message` | `string` | **Yes** | User prompt/query text. |
| `session_id` | `string` | No | Session ID for multi-turn conversation memory. |

#### Example Requests
**cURL:**
```bash
curl -X POST "https://hifisys.com/api/v1/chatbot/message" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"What web development services do you offer?"}'
```
**JavaScript:**
```javascript
const res = await fetch('https://hifisys.com/api/v1/chatbot/message', {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ message: 'What web development services do you offer?' })
});
const data = await res.json();
```
**PHP:**
```php
$ch = curl_init('https://hifisys.com/api/v1/chatbot/message');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['message' => 'What web development services do you offer?']));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: YOUR_API_KEY', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
```
**Python:**
```python
import requests
res = requests.post('https://hifisys.com/api/v1/chatbot/message', json={'message': 'What web development services do you offer?'}, headers={'X-API-Key': 'YOUR_API_KEY'})
print(res.json())
```

#### Sample Response (200 OK)
```json
{
    "success": true,
    "reply": "Hifisys Tech provides enterprise web development, custom Laravel apps, React/Vue frontends, and API platforms.",
    "quick_replies": [
        "Get a Quote",
        "View Portfolio",
        "Contact Sales"
    ]
}
```

---

---
# Product: AI Blog Generator API
Base URL: `https://hifisys.com/api/v1/ai/blog`

### `POST` /api/v1/ai/blog/generate
**Generate Full Article**
> **Scope:** `blog:generate` | **Content-Type:** `application/json`

Generates a full-length SEO-optimized article with title, headings, HTML content, meta tags, and estimated read time.

#### Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `topic` | `string` | **Yes** | Article topic or main subject. |
| `target_keywords` | `array` | No | List of primary and secondary SEO keywords. |
| `tone` | `string` | No | professional, engaging, technical, casual. Default: professional. |

#### Example Requests
**cURL:**
```bash
curl -X POST "https://hifisys.com/api/v1/ai/blog/generate" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"topic":"Benefits of Enterprise HRMS","tone":"professional"}'
```
**JavaScript:**
```javascript
const res = await fetch('https://hifisys.com/api/v1/ai/blog/generate', {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ topic: 'Benefits of Enterprise HRMS', tone: 'professional' })
});
const data = await res.json();
```
**PHP:**
```php
$ch = curl_init('https://hifisys.com/api/v1/ai/blog/generate');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['topic' => 'Benefits of Enterprise HRMS', 'tone' => 'professional']));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: YOUR_API_KEY', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
```
**Python:**
```python
import requests
res = requests.post('https://hifisys.com/api/v1/ai/blog/generate', json={'topic': 'Benefits of Enterprise HRMS', 'tone': 'professional'}, headers={'X-API-Key': 'YOUR_API_KEY'})
print(res.json())
```

#### Sample Response (200 OK)
```json
{
    "success": true,
    "data": {
        "title": "Top 7 Strategic Benefits of Modern HRMS Platforms",
        "content": "<p>Enterprise HRMS solutions streamline payroll, attendance, and compliance...</p>",
        "meta_description": "Discover how modern HRMS software transforms workforce management.",
        "read_time_minutes": 5
    }
}
```

---

---
# Product: AI Page Builder API
Base URL: `https://hifisys.com/api/v1/ai/page-builder`

### `POST` /api/v1/ai/page-builder/generate-page
**Generate High-Fidelity Page (Prompt + References)**
> **Scope:** `page:generate` | **Content-Type:** `multipart/form-data or application/json`

Architects and generates complete, responsive landing pages adhering to prompt specifications, uploaded design references (screenshots, HTML/CSS files), and base theme contexts with up to 99% structural fidelity.

#### Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `prompt` | `string` | **Yes** | Detailed textual prompt describing target layout, sections, spacing, styling, copy, and specific constraints. |
| `base_theme` | `string` | No | Base theme context to inherit: hifisys-current, modern-dark, minimal-light, corporate. Default: hifisys-current. |
| `output_format` | `string` | No | Target code formats: html, css, js, blade, all. Default: all. |
| `responsive` | `boolean` | No | Optimize layout for mobile (390px), tablet (768px), and desktop (1366px). Default: true. |
| `references[]` | `file(s)` | No | Multiple design references: Screenshots (PNG/JPG/WebP/SVG), HTML files, CSS files, or ZIP frontend bundles. |
| `reference_url` | `string` | No | Optional public URL of reference webpage for structural and layout inspiration analysis. |

#### Example Requests
**cURL:**
```bash
curl -X POST "https://hifisys.com/api/v1/ai/page-builder/generate-page" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "prompt=Create a premium AI SaaS landing page with dark hero, gold accents, 3 feature cards, pricing, and FAQ. Keep Hifisys header." \
  -F "base_theme=hifisys-current" \
  -F "output_format=all" \
  -F "references[]=@/path/to/screenshot.png" \
  -F "references[]=@/path/to/reference.html"
```
**JavaScript:**
```javascript
const formData = new FormData();
formData.append('prompt', 'Create a premium AI SaaS landing page with dark hero and gold accents.');
formData.append('base_theme', 'hifisys-current');
// Attach reference file if available:
// formData.append('references[]', fileInput.files[0]);

const response = await fetch('https://hifisys.com/api/v1/ai/page-builder/generate-page', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Accept': 'application/json'
  },
  body: formData
});
const data = await response.json();
console.log(data);
```
**PHP:**
```php
$ch = curl_init('https://hifisys.com/api/v1/ai/page-builder/generate-page');
$postData = [
    'prompt' => 'Create a premium AI SaaS landing page with dark hero and gold accents.',
    'base_theme' => 'hifisys-current',
    'output_format' => 'all',
    // 'references[0]' => new CURLFile('/path/to/reference.png')
];
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: YOUR_API_KEY',
    'Accept: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($response);
```
**Python:**
```python
import requests

url = 'https://hifisys.com/api/v1/ai/page-builder/generate-page'
headers = {'X-API-Key': 'YOUR_API_KEY', 'Accept': 'application/json'}
data = {
    'prompt': 'Create a premium AI SaaS landing page with dark hero and gold accents.',
    'base_theme': 'hifisys-current',
    'output_format': 'all'
}
# files = {'references[]': open('reference.png', 'rb')}
response = requests.post(url, headers=headers, data=data)
print(response.json())
```

#### Sample Response (200 OK)
```json
{
    "success": true,
    "generation_id": "gen_9f82d19e0b1274a10c92",
    "message": "Page generated successfully with high fidelity.",
    "output": {
        "html": "<section class=\"pt-32 pb-20 bg-slate-950 text-white\">\n  <div class=\"max-w-7xl mx-auto px-6 text-center\">\n    <h1 class=\"text-5xl font-black text-amber-400\">Next-Gen AI Platform</h1>\n    <p class=\"mt-4 text-slate-300\">Architect scalable workflows effortlessly.</p>\n  </div>\n</section>",
        "css": "/* Custom High-Fidelity Design Tokens */\n.btn-gold { background: #E6A622; color: #111; font-weight: 700; border-radius: 12px; }",
        "js": "document.addEventListener('DOMContentLoaded', () => { console.log('Page interactive'); });",
        "blade": "@extends('layouts.app')\n@section('content')\n  <!-- Generated Content -->\n@endsection"
    },
    "reference_analysis": {
        "references_used": 2,
        "references_analyzed": [
            "screenshot.png",
            "reference.html"
        ],
        "layout_detected": "Dark Hero with 3-Column Feature Cards and Pricing Matrix",
        "fidelity_adherence": "Aggressive multi-reference matching applied."
    },
    "meta": {
        "base_theme": "hifisys-current",
        "generation_time_ms": 420,
        "quota_deducted": 1
    }
}
```

---

### `POST` /api/v1/ai/page-builder/generate-section
**Generate Modular Page Section**
> **Scope:** `page:section` | **Content-Type:** `application/json`

Generates an individual modular component block (Hero, Features, Pricing, Testimonials, FAQ) for seamless embedding into existing pages.

#### Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `section_name` | `string` | **Yes** | Type of section: hero, features, pricing, testimonials, faq, cta. |
| `title` | `string` | **Yes** | Section heading title. |
| `brief` | `string` | No | Specific content requirements and bullet points. |
| `layout_style` | `string` | No | cards, grid, split, hero, testimonial. Default: cards. |

#### Example Requests
**cURL:**
```bash
curl -X POST "https://hifisys.com/api/v1/ai/page-builder/generate-section" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"section_name":"pricing","title":"Flexible Pricing Plans","layout_style":"cards"}'
```
**JavaScript:**
```javascript
const res = await fetch('https://hifisys.com/api/v1/ai/page-builder/generate-section', {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ section_name: 'pricing', title: 'Flexible Pricing Plans' })
});
const data = await res.json();
```
**PHP:**
```php
$ch = curl_init('https://hifisys.com/api/v1/ai/page-builder/generate-section');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['section_name' => 'pricing', 'title' => 'Flexible Pricing Plans']));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: YOUR_API_KEY', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
```
**Python:**
```python
import requests
res = requests.post('https://hifisys.com/api/v1/ai/page-builder/generate-section', json={'section_name': 'pricing', 'title': 'Flexible Pricing Plans'}, headers={'X-API-Key': 'YOUR_API_KEY'})
print(res.json())
```

#### Sample Response (200 OK)
```json
{
    "success": true,
    "data": {
        "section_name": "pricing",
        "title": "Flexible Pricing Plans",
        "html_content": "<div class=\"py-16 bg-white\"><div class=\"grid md:grid-cols-3 gap-8\">...</div></div>",
        "meta": {
            "layout_style": "cards",
            "word_count": 140
        }
    }
}
```

---

### `POST` /api/v1/ai/page-builder/clean-html
**Sanitize & Clean HTML Markup**
> **Scope:** `page:section` | **Content-Type:** `application/json`

Sanitizes raw markup, strips malicious inline event listeners and script tags, and normalizes semantic element indentation.

#### Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `html` | `string` | **Yes** | Raw HTML markup string to sanitize. |

#### Example Requests
**cURL:**
```bash
curl -X POST "https://hifisys.com/api/v1/ai/page-builder/clean-html" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html":"<div onclick=\"alert(1)\">Safe Content</div>"}'
```
**JavaScript:**
```javascript
const res = await fetch('https://hifisys.com/api/v1/ai/page-builder/clean-html', {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ html: '<div>Clean Content</div>' })
});
```
**PHP:**
```php
$ch = curl_init('https://hifisys.com/api/v1/ai/page-builder/clean-html');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['html' => '<div>Clean Content</div>']));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: YOUR_API_KEY', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
```
**Python:**
```python
import requests
res = requests.post('https://hifisys.com/api/v1/ai/page-builder/clean-html', json={'html': '<div>Clean Content</div>'}, headers={'X-API-Key': 'YOUR_API_KEY'})
print(res.json())
```

#### Sample Response (200 OK)
```json
{
    "success": true,
    "data": {
        "cleaned_html": "<div>Safe Content</div>",
        "sanitized": true
    }
}
```

---

---
# Product: Hifisys Enterprise HRMS Suite
Base URL: `https://hifisys.com/api/v1`


---
# Product: Hifisys Enterprise SEO Control Center
Base URL: `https://hifisys.com/api/v1`


---
# Product: Hifisys CRM & Lead Automation Platform
Base URL: `https://hifisys.com/api/v1/leads`

### `POST` /api/v1/leads
**Create / Upsert Lead (Authenticated Server-to-Server)**
> **Scope:** `leads:write` | **Content-Type:** `application/json`

Creates a new CRM lead or safely merges with an existing open lead matching the normalized email address, runs configured lead automation rules, and returns the persisted lead reference code.

#### Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | **Yes** | Full name of the prospective customer (max 255 chars). |
| `email` | `string` | **Yes** | Valid email address used for contact and duplicate detection. |
| `phone` | `string` | No | Phone or WhatsApp number with country code. |
| `company` | `string` | No | Organization or company name. |
| `message` | `string` | No | Inquiry details, project scope, or notes. |
| `product_slug` | `string` | No | Interested Hifisys product slug (e.g., enterprise-hrms-suite, hrms-api). |
| `interested_option` | `string` | No | Purchase preference: software, api, both, or custom. |
| `campaign` | `string` | No | Marketing campaign identifier. |
| `utm_source` | `string` | No | UTM source attribution (e.g., google, linkedin, partner). |
| `utm_medium` | `string` | No | UTM medium (e.g., cpc, referral, email). |
| `utm_campaign` | `string` | No | UTM campaign name. |

#### Example Requests
**cURL:**
```bash
curl -X POST "https://hifisys.com/api/v1/leads" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Aarav Mehta",
    "email": "aarav.mehta@enterprise-example.com",
    "phone": "+91 9876543210",
    "company": "Mehta FinTech Solutions",
    "product_slug": "crm-lead-automation-platform",
    "interested_option": "both",
    "utm_source": "partner_portal",
    "utm_campaign": "q4_enterprise_launch",
    "message": "We want to deploy the CRM Software + REST API bundle for a 45-person sales team."
  }'
```
**JavaScript:**
```javascript
const res = await fetch('https://hifisys.com/api/v1/leads', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    name: 'Aarav Mehta',
    email: 'aarav.mehta@enterprise-example.com',
    company: 'Mehta FinTech Solutions',
    product_slug: 'crm-lead-automation-platform',
    interested_option: 'both',
    message: 'Interested in the CRM Software + API bundle.'
  })
});
const data = await res.json();
```
**PHP:**
```php
$ch = curl_init('https://hifisys.com/api/v1/leads');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'name' => 'Aarav Mehta',
    'email' => 'aarav.mehta@enterprise-example.com',
    'company' => 'Mehta FinTech Solutions',
    'product_slug' => 'crm-lead-automation-platform',
    'interested_option' => 'both',
    'message' => 'Interested in the CRM Software + API bundle.'
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: YOUR_API_KEY', 'Content-Type: application/json', 'Accept: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
```
**Python:**
```python
import requests
res = requests.post(
    'https://hifisys.com/api/v1/leads',
    json={
        'name': 'Aarav Mehta',
        'email': 'aarav.mehta@enterprise-example.com',
        'company': 'Mehta FinTech Solutions',
        'product_slug': 'crm-lead-automation-platform',
        'interested_option': 'both',
        'message': 'Interested in the CRM Software + API bundle.'
    },
    headers={'X-API-Key': 'YOUR_API_KEY', 'Accept': 'application/json'}
)
print(res.json())
```

#### Sample Response (200 OK)
```json
{
    "success": true,
    "message": "Lead captured and processed successfully.",
    "data": {
        "lead_code": "LEAD-2026-0001",
        "name": "Aarav Mehta",
        "email": "aarav.mehta@enterprise-example.com",
        "status": "new",
        "was_existing_merged": false,
        "duplicate_count": 0,
        "created_at": "2026-10-11T14:00:00Z"
    }
}
```

---

### `GET` /api/v1/leads
**List Client-Scoped Leads**
> **Scope:** `leads:read` | **Content-Type:** `application/json`

Returns paginated leads strictly created by the authenticated API client. Never exposes leads owned by other API clients or internal channels.

#### Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `status` | `string` | No | Filter by pipeline status: new, contacted, qualified, proposal_sent, negotiation, won, lost. |
| `limit` | `integer` | No | Records per page (1-50, default 15). |

#### Example Requests
**cURL:**
```bash
curl -X GET "https://hifisys.com/api/v1/leads?limit=15" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
```
**JavaScript:**
```javascript
const res = await fetch('https://hifisys.com/api/v1/leads', {
  headers: { 'X-API-Key': 'YOUR_API_KEY', 'Accept': 'application/json' }
});
const data = await res.json();
```
**PHP:**
```php
$ch = curl_init('https://hifisys.com/api/v1/leads');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: YOUR_API_KEY', 'Accept: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
```
**Python:**
```python
import requests
res = requests.get('https://hifisys.com/api/v1/leads', headers={'X-API-Key': 'YOUR_API_KEY'})
print(res.json())
```

#### Sample Response (200 OK)
```json
{
    "success": true,
    "data": [
        {
            "lead_code": "LEAD-2026-0001",
            "name": "Aarav Mehta",
            "email": "aarav.mehta@enterprise-example.com",
            "status": "new",
            "priority": "medium"
        }
    ],
    "meta": {
        "current_page": 1,
        "total": 1
    }
}
```

---

### `POST` /api/v1/public/leads
**Public Lead Intake Endpoint (Rate-Limited, Write-Only)**
> **Scope:** `public` | **Content-Type:** `application/json`

Rate-limited (20 req/min) write-only public endpoint for website forms and landing page widgets. Validates input, applies honeypot protection, and returns only a lead confirmation reference.

#### Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | **Yes** | Visitor full name. |
| `email` | `string` | **Yes** | Visitor email address. |
| `phone` | `string` | No | Visitor phone number. |
| `company` | `string` | No | Company name. |
| `product_slug` | `string` | No | Interested product slug. |
| `message` | `string` | **Yes** | Inquiry message (min 5 chars). |

#### Example Requests
**cURL:**
```bash
curl -X POST "https://hifisys.com/api/v1/public/leads" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"name":"Priya Sharma","email":"priya@acme.in","product_slug":"enterprise-hrms-suite","message":"Requesting a live demo of the Enterprise HRMS software."}'
```
**JavaScript:**
```javascript
const res = await fetch('https://hifisys.com/api/v1/public/leads', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' },
  body: JSON.stringify({ name: 'Priya Sharma', email: 'priya@acme.in', message: 'Requesting a live demo.' })
});
```
**PHP:**
```php
// Standard JSON POST to https://hifisys.com/api/v1/public/leads
```
**Python:**
```python
import requests
requests.post('https://hifisys.com/api/v1/public/leads', json={'name': 'Priya Sharma', 'email': 'priya@acme.in', 'message': 'Requesting a live demo.'})
```

#### Sample Response (200 OK)
```json
{
    "success": true,
    "message": "Thank you! Your inquiry has been received by our team.",
    "lead_reference": "LEAD-2026-0002"
}
```

---

## Security Best Practices
- Store API keys in environment variables; never commit to public VCS repositories.
- Enforce TLS 1.3 across all client integrations.
- Implement exponential backoff algorithms for rate-limit handling (HTTP 429).

## Support & Contact
- **Email:** info@hifisys.com
- **Phone:** +91 8890897064
- **Website:** [Hifisys](https://hifisys.com)