# Hifisys CRM & Lead Automation Platform API Reference

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

## Overview
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.

## 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
```

## Available Subscription Plans
| Plan | Price | Rate Limit | Monthly Quota | Trial |
|---|---|---|---|---|
| Free Trial | Free Trial | 60 req/min | 2,000 | 7 Days |
| Starter API | USD 39.00/month | 120 req/min | 25,000 | No |
| Business API | USD 119.00/month | 300 req/min | 100,000 | No |
| Enterprise API | USD 299.00/monthly | 600 req/min | 500,000 | No |
| CRM Professional Annual License | USD 349.00/annual | 60 req/min | 50,000 | No |
| CRM Pro Software + API Suite Bundle | USD 499.00/annual | 300 req/min | 250,000 | No |

## API Endpoints
### `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)