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
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.
Request Body
{
"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
{
"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.
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
{
"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.
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.
PATCH /enquiries/{enquiry_id}
Request Body
{
"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.
POST /enquiries/verify-whatsapp
Request Body
{
"phone": "+91-9876543210"
}
Response 200 OK
{
"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)
Rate Limits
| Endpoint | Limit |
|---|
POST /enquiries | 60/min (public) |
POST /enquiries/verify-whatsapp | 60/min (public) |
| All authenticated endpoints | 120/min (general) |
