> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spn.wtf/llms.txt
> Use this file to discover all available pages before exploring further.

# Enquiries API

> Enquiry and lead management

# Enquiries API

Manage enquiries (leads) submitted by buyers to suppliers, with WhatsApp notification support.

## Endpoints

| Method | Path                         | Auth     | Description            |
| ------ | ---------------------------- | -------- | ---------------------- |
| POST   | `/enquiries`                 | Public   | Create an enquiry      |
| GET    | `/enquiries`                 | Required | List enquiries         |
| GET    | `/enquiries/{id}`            | Required | Get enquiry details    |
| PATCH  | `/enquiries/{id}`            | Required | Update enquiry status  |
| POST   | `/enquiries/verify-whatsapp` | Public   | Verify WhatsApp number |

***

## Create Enquiry

Submit a new enquiry from a buyer to a supplier. Public endpoint — no authentication required.
Triggers background WhatsApp/email notifications automatically.

```bash theme={null}
POST /enquiries
```

### Request Body

```json theme={null}
{
  "to_company_id": "7b3f1c2d-4e5a-6f7b-8c9d-0e1f2a3b4c5d",
  "product_id": "9a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "message": "Interested in bulk order of 500 units",
  "quantity": 500,
  "user_name": "Amit Sharma",
  "user_email": "amit@example.com",
  "user_phone": "+91-9876543210"
}
```

### Fields

| Field           | Type   | Required | Description                            |
| --------------- | ------ | -------- | -------------------------------------- |
| `to_company_id` | uuid   | **Yes**  | Supplier company receiving the enquiry |
| `product_id`    | uuid   | No       | Specific product of interest           |
| `message`       | string | No       | Enquiry message                        |
| `quantity`      | int    | No       | Requested quantity                     |
| `user_name`     | string | **Yes**  | Buyer's name                           |
| `user_email`    | string | **Yes**  | Buyer's email                          |
| `user_phone`    | string | No       | Buyer's phone number                   |

### Response `201 Created`

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "to_company_id": "7b3f1c2d-4e5a-6f7b-8c9d-0e1f2a3b4c5d",
  "product_id": "9a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "message": "Interested in bulk order of 500 units",
  "quantity": 500,
  "user_name": "Amit Sharma",
  "user_email": "amit@example.com",
  "user_phone": "+91-9876543210",
  "status": "pending",
  "zoho_lead_id": null,
  "created_at": "2024-01-15T10:30:00Z"
}
```

### Errors

| Status | Detail                                    |
| ------ | ----------------------------------------- |
| `400`  | Validation error (e.g. company not found) |
| `500`  | Failed to create enquiry                  |

***

## List Enquiries

List enquiries with optional filters. Requires authentication. Results are paginated.

```bash theme={null}
GET /enquiries
```

### Query Parameters

| Parameter         | Type   | Required | Default | Description                                |
| ----------------- | ------ | -------- | ------- | ------------------------------------------ |
| `company_id`      | uuid   | No       | —       | Filter by supplier company (must be yours) |
| `status`          | string | No       | —       | Filter by status                           |
| `source_platform` | string | No       | —       | Filter by source platform                  |
| `page`            | int    | No       | `1`     | Page number                                |
| `page_size`       | int    | No       | `50`    | Items per page (max `100`)                 |

### Status Values

| Value       | Meaning               |
| ----------- | --------------------- |
| `pending`   | New, not yet acted on |
| `contacted` | Initial contact made  |
| `qualified` | Lead qualified        |
| `converted` | Converted to customer |
| `lost`      | Lost opportunity      |

### Response `200 OK`

```json theme={null}
{
  "items": [...],
  "total": 142,
  "page": 1,
  "page_size": 50,
  "total_pages": 3
}
```

### Errors

| Status | Detail                                                    |
| ------ | --------------------------------------------------------- |
| `403`  | Not enough permissions to access this company's enquiries |

***

## Get Enquiry

Fetch a single enquiry by ID. Requires authentication.

```bash theme={null}
GET /enquiries/{enquiry_id}
```

### Response `200 OK`

Returns the full enquiry object (same shape as Create response).

### Errors

| Status | Detail            |
| ------ | ----------------- |
| `404`  | Enquiry not found |

***

## Update Enquiry

Update the status or details of an existing enquiry. Requires authentication.

```bash theme={null}
PATCH /enquiries/{enquiry_id}
```

### Request Body

```json theme={null}
{
  "status": "qualified",
  "notes": "Buyer confirmed budget and timeline"
}
```

### Fields

| Field    | Type   | Required | Description                          |
| -------- | ------ | -------- | ------------------------------------ |
| `status` | string | No       | New status (see status values above) |
| `notes`  | string | No       | Internal notes                       |

### Response `200 OK`

Returns the updated enquiry object.

### Errors

| Status | Detail            |
| ------ | ----------------- |
| `404`  | Enquiry not found |

***

## Verify WhatsApp Number

Check whether a phone number is registered on WhatsApp before sending a message. Public endpoint.

```bash theme={null}
POST /enquiries/verify-whatsapp
```

### Request Body

```json theme={null}
{
  "phone": "+91-9876543210"
}
```

### Response `200 OK`

```json theme={null}
{
  "phone": "+91-9876543210",
  "is_valid": true,
  "is_whatsapp": true,
  "error": null
}
```

***

## Background Notifications

When an enquiry is created, background tasks fire automatically:

```
POST /enquiries
  └── Enquiry saved to DB
  └── Background task:
        ├── WhatsApp message → supplier's phone
        ├── Email notification → supplier
        └── Zoho CRM push → Lead created (zoho_lead_id stored on success)
```

Notification failures are logged but do not affect the enquiry creation response.

***

## Rate Limits

| Endpoint                          | Limit             |
| --------------------------------- | ----------------- |
| `POST /enquiries`                 | 60/min (public)   |
| `POST /enquiries/verify-whatsapp` | 60/min (public)   |
| All authenticated endpoints       | 120/min (general) |