Leads API

The Leads API provides endpoints for capturing contact form submissions, scheduling property tours, and managing leads. The system automatically routes leads to the correct brokerage based on the request domain.

Contact Form Submission

Submit a contact form inquiry. The brokerage is automatically determined from the request domain.

POST /api/contact

Public

Request Body

{
  "firstName": "John",
  "lastName": "Smith",
  "email": "john.smith@example.com",
  "phone": "208-555-0123",
  "subject": "Interested in property at 123 Main St",
  "message": "I'd like to learn more about this listing...",
  "source_page": "/property/202412345",
  "utm_source": "google",
  "utm_medium": "organic",
  "utm_campaign": "spring-2024"
}

Fields

Field	Type	Required	Description
firstName	string	Yes	Contact’s first name
lastName	string	Yes	Contact’s last name
email	string	Yes	Valid email address
phone	string	No	Phone number
subject	string	Yes	Message subject
message	string	Yes	Full message content
source_page	string	No	Page URL where form was submitted
utm_source	string	No	UTM tracking: source
utm_medium	string	No	UTM tracking: medium
utm_campaign	string	No	UTM tracking: campaign

Response

{
  "success": true,
  "message": "Thank you for your message! We'll get back to you within 24 hours.",
  "lead_id": 456
}

Note

The brokerage is determined automatically from the Host header. This enables white-label sites to capture leads correctly without any frontend configuration.

Get Leads Count

Get a summary of lead counts by status for the current domain’s brokerage.

GET /api/leads/count

Auth Required

Response

{
  "new": 12,
  "contacted": 8,
  "qualified": 5,
  "converted": 3,
  "total": 28
}

Tip

This endpoint is useful for dashboard widgets showing lead pipeline metrics.

---

Tour Requests

Schedule property viewing tours.

Request a Tour

POST /api/tours

Public

Request Body

{
  "listing_id": "202412345",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "208-555-0456",
  "preferred_date": "2024-12-30",
  "preferred_time": "10:00 AM",
  "message": "I'm interested in seeing this property. Is it available Saturday morning?"
}

Fields

Field	Type	Required	Description
listing_id	string	Yes	MLS listing ID to tour
name	string	Yes	Requester’s full name
email	string	Yes	Contact email
phone	string	No	Contact phone
preferred_date	string	No	Preferred tour date (YYYY-MM-DD)
preferred_time	string	No	Preferred time slot
message	string	No	Additional notes

Response

{
  "id": 789,
  "listing_id": "202412345",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "status": "pending",
  "created_at": "2024-12-28T15:30:00Z"
}

List Tour Requests

Get tour requests for the authenticated user’s brokerage.

GET /api/tours

Auth Required

Query Parameters

Parameter	Type	Description
status	string	Filter by status (pending, confirmed, completed, cancelled)
listing_id	string	Filter by property

Response

[
  {
    "id": 789,
    "listing_id": "202412345",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "208-555-0456",
    "preferred_date": "2024-12-30",
    "preferred_time": "10:00 AM",
    "status": "pending",
    "created_at": "2024-12-28T15:30:00Z"
  }
]

Get Tour Request

GET /api/tours/{request_id}

Auth Required

---

Newsletter Subscription

Subscribe to a brokerage’s email newsletter.

Subscribe

POST /api/newsletter/subscribe

Public

Request Body

{
  "email": "subscriber@example.com",
  "first_name": "John",
  "interests": ["new-listings", "market-updates"]
}

Response

{
  "success": true,
  "message": "Successfully subscribed to newsletter"
}

---

Lead Status Values

Leads progress through a standard pipeline:

Status	Description
new	Just received, not yet reviewed
contacted	Initial contact made
qualified	Lead is qualified/interested
showing	Scheduled for property showings
offer	Making or negotiating offers
converted	Successfully closed
lost	Lead was lost or not interested

---

Error Responses

Missing Host Header

{
  "detail": "Missing Host header"
}

Status: 400 Bad Request

Brokerage Not Found

{
  "detail": "Brokerage not found"
}

Status: 404 Not Found

Validation Error

{
  "detail": [
    {
      "loc": ["body", "email"],
      "msg": "value is not a valid email address",
      "type": "value_error.email"
    }
  ]
}

Status: 422 Unprocessable Entity

---

Related

• Integrating Contact Forms — Frontend implementation guide
• Multi-Tenant Routing — How domain-based routing works
• API Overview — General API information