Site Visits API

Site visits represent the highest-conversion stage in the real estate sales funnel. BrokerOS tracks scheduled visits, records detailed client feedback, and uses GPS coordinates to verify physical attendance at project locations.

BASE URL: /api/leads

Endpoints Summary

Method	Path	Description	Access
`GET`	`/api/leads/:id/site-visits`	List all site visits scheduled for a lead	Authenticated
`POST`	`/api/leads/:id/site-visits`	Schedule a new site visit	Authenticated
`PATCH`	`/api/leads/site-visits/:siteVisitId`	Update visit details, interest level, and feedback	Authenticated
`DELETE`	`/api/leads/site-visits/:siteVisitId`	Delete or cancel a scheduled visit	Authenticated
`PATCH`	`/api/leads/:id/site-visits/:siteVisitId/arrive`	Record GPS check-in at the project location	Authenticated

List Lead Site Visits

GET /api/leads/:id/site-visits

Returns the chronological list of all site visits scheduled or completed for the specified lead.

Response Example

[
  {
    "id": "cm123sv001",
    "leadId": "cm123lead001",
    "userId": "cm123user002",
    "projectId": "cm123proj001",
    "scheduledDate": "2026-10-04T10:30:00.000Z",
    "status": "SCHEDULED",
    "meetingNotes": "Customer requested visit to model apartment and clubhouse",
    "createdAt": "2026-09-29T11:00:00.000Z"
  }
]

Schedule Site Visit

POST /api/leads/:id/site-visits

Creates a new site visit task. When scheduled, the lead’s status automatically transitions to SITE_VISIT_SCHEDULED and an entry is added to the executive’s mobile calendar.

Request Body

Field	Type	Required	Description
`userId`	`string`	Yes	User ID of the sales executive conducting the visit
`projectId`	`string`	Yes	Project ID where the visit is taking place
`scheduledDate`	`string`	Yes	ISO 8601 date string (e.g. `2026-10-05T11:00:00Z`)
`meetingNotes`	`string`	No	Instructions, pickup location, or specific unit requests
`destinationUrl`	`string`	No	Google Maps direction link or site office pin

Request Example

{
  "userId": "cm123user002",
  "projectId": "cm123proj001",
  "scheduledDate": "2026-10-05T11:00:00.000Z",
  "meetingNotes": "Client arriving with architect; focus on Tower B 3BHK layout."
}

GPS Check-in (Arrive)

PATCH /api/leads/:id/site-visits/:siteVisitId/arrive

Sales executives tap “I Have Arrived” on their BrokerOS mobile app when reaching the project site. The server checks the device’s coordinates against the project’s geofence.

Request Body

Field	Type	Required	Description
`latitude`	`number`	Yes	Device latitude from native GPS
`longitude`	`number`	Yes	Device longitude from native GPS

Verification Rule

Projects must have valid latitude and longitude fields configured in the inventory database for geofence verification to succeed.

Update Site Visit Outcome

PATCH /api/leads/site-visits/:siteVisitId

After the visit is concluded, the executive submits complete qualitative and quantitative feedback.

Request Body

Field	Type	Required	Description
`status`	`string`	No	`SCHEDULED`, `COMPLETED`, `CANCELLED`, `RESCHEDULED`, `NO_SHOW`
`interestLevel`	`string`	No	`VERY_HIGH`, `HIGH`, `MEDIUM`, `LOW`, `NOT_INTERESTED`
`budgetConfirmed`	`number`	No	Verified budget confirmed during face-to-face discussion
`configInterest`	`string`	No	Configuration preferred (e.g. `3BHK-Luxury-East`)
`customerReaction`	`string`	No	Customer reaction to amenities, price, floor plan
`customerObjections`	`string`	No	Objections raised (e.g. possession date, price per sqft)
`closingProbability`	`string`	No	Estimated closing probability percentage (e.g. `80%`)
`nextAction`	`string`	No	Next step (e.g. `Send payment schedule by tonight`)
`completedAt`	`string`	No	ISO timestamp of visit conclusion

Request Example

{
  "status": "COMPLETED",
  "interestLevel": "VERY_HIGH",
  "budgetConfirmed": 14000000,
  "configInterest": "3BHK Tower B Unit 1204",
  "customerReaction": "Loves the view and kitchen layout",
  "customerObjections": "Negotiating on car parking charges",
  "closingProbability": "85%",
  "nextAction": "Director approval requested for 2% parking waiver"
}

Delete Site Visit

DELETE /api/leads/site-visits/:siteVisitId

Removes a mistakenly scheduled visit or clears a cancelled visit from the calendar.

System Architecture

API Reference

Endpoints Summary

List Lead Site Visits

Response Example

Schedule Site Visit

Request Body

Request Example

GPS Check-in (Arrive)

Request Body

Verification Rule

Update Site Visit Outcome

Request Body

Request Example

Delete Site Visit

​Endpoints Summary

​List Lead Site Visits

​Response Example

​Schedule Site Visit

​Request Body

​Request Example

​GPS Check-in (Arrive)

​Request Body

​Verification Rule

​Update Site Visit Outcome

​Request Body

​Request Example

​Delete Site Visit

Endpoints Summary

List Lead Site Visits

Response Example

Schedule Site Visit

Request Body

Request Example

GPS Check-in (Arrive)

Request Body

Verification Rule

Update Site Visit Outcome

Request Body

Request Example

Delete Site Visit