Skip to main content

​
Enquiries API

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

​
Endpoints

MethodPathAuthDescription
POST/enquiriesPublicCreate an enquiry
GET/enquiriesRequiredList enquiries
GET/enquiries/{id}RequiredGet enquiry details
PATCH/enquiries/{id}RequiredUpdate enquiry status
POST/enquiries/verify-whatsappPublicVerify 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. 
POST /enquiries

​
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

FieldTypeRequiredDescription
to_company_iduuidYesSupplier company receiving the enquiry
product_iduuidNoSpecific product of interest
messagestringNoEnquiry message
quantityintNoRequested quantity
user_namestringYesBuyer’s name
user_emailstringYesBuyer’s email
user_phonestringNoBuyer’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

StatusDetail
400Validation error (e.g. company not found)
500Failed to create enquiry

​
List Enquiries

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

​
Query Parameters

ParameterTypeRequiredDefaultDescription
company_iduuidNo—Filter by supplier company (must be yours)
statusstringNo—Filter by status
source_platformstringNo—Filter by source platform
pageintNo1Page number
page_sizeintNo50Items per page (max 100)

​
Status Values

ValueMeaning
pendingNew, not yet acted on
contactedInitial contact made
qualifiedLead qualified
convertedConverted to customer
lostLost opportunity

​
Response 200 OK

{
  "items": [...],
  "total": 142,
  "page": 1,
  "page_size": 50,
  "total_pages": 3
}

​
Errors

StatusDetail
403Not 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

StatusDetail
404Enquiry 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

FieldTypeRequiredDescription
statusstringNoNew status (see status values above)
notesstringNoInternal notes

​
Response 200 OK

Returns the updated enquiry object.

​
Errors

StatusDetail
404Enquiry 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)
Notification failures are logged but do not affect the enquiry creation response.

​
Rate Limits

EndpointLimit
POST /enquiries60/min (public)
POST /enquiries/verify-whatsapp60/min (public)
All authenticated endpoints120/min (general)