Skip to main content

Leads API

Endpoints for managing leads and the sales pipeline.

Lead Object​

{
  "id": "lead_abc123",
  "name": "John Smith",
  "email": "john@example.com",
  "phone": "+1234567890",
  "source": "website",
  "stage": "qualified",
  "score": 75,
  "assigned_agent": "agent_456def",
  "interested_properties": ["unit_789xyz"],
  "budget": {
    "min": 500000,
    "max": 750000,
    "currency": "USD"
  },
  "timeline": "3_months",
  "notes": "Looking for 3BR villa with pool",
  "tags": ["hot", "investor"],
  "last_contacted": "2024-01-24T10:00:00Z",
  "next_follow_up": "2024-01-26T10:00:00Z",
  "created_at": "2024-01-15T08:00:00Z",
  "updated_at": "2024-01-24T10:00:00Z"
}

List Leads​

GET /v1/leads

Query Parameters​

ParameterTypeDescription
stagestringFilter by pipeline stage
sourcestringFilter by lead source
agent_idstringFilter by assigned agent
min_scorenumberMinimum lead score
property_idstringInterested in property
tagsstringFilter by tags (comma-separated)
created_afterstringCreated after date
created_beforestringCreated before date
searchstringSearch name/email/phone

Example Request​

curl -X GET "https://api.propertybase.ai/v1/leads?stage=qualified&min_score=60" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response​

{
  "success": true,
  "data": [
    {
      "id": "lead_abc123",
      "name": "John Smith",
      "email": "john@example.com",
      "stage": "qualified",
      "score": 75,
      "assigned_agent": "agent_456def",
      "last_contacted": "2024-01-24T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 150
  }
}

Get Lead​

GET /v1/leads/:id

Query Parameters​

ParameterTypeDescription
expandstringInclude related data
include_activitybooleanInclude activity log

Example Request​

curl -X GET "https://api.propertybase.ai/v1/leads/lead_abc123?expand=agent,properties&include_activity=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Lead​

POST /v1/leads

Request Body​

FieldTypeRequiredDescription
namestringYesLead's full name
emailstringYesEmail address
phonestringNoPhone number
sourcestringNoLead source
interested_propertiesarrayNoProperty/unit IDs
budgetobjectNoBudget range
timelinestringNoPurchase timeline
notesstringNoInitial notes
assigned_agentstringNoAgent to assign
tagsarrayNoTags to apply

Example Request​

curl -X POST "https://api.propertybase.ai/v1/leads" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "+1987654321",
    "source": "referral",
    "interested_properties": ["unit_789xyz"],
    "budget": {
      "min": 600000,
      "max": 900000,
      "currency": "USD"
    },
    "timeline": "6_months",
    "notes": "Referred by existing client",
    "tags": ["referral", "serious_buyer"]
  }'

Example Response​

{
  "success": true,
  "data": {
    "id": "lead_new456",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "stage": "new",
    "score": 65,
    "created_at": "2024-01-25T14:00:00Z"
  }
}

Update Lead​

PUT /v1/leads/:id

Example Request​

curl -X PUT "https://api.propertybase.ai/v1/leads/lead_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stage": "viewing",
    "next_follow_up": "2024-01-28T10:00:00Z",
    "notes": "Viewing scheduled for Villa A"
  }'

Change Stage​

POST /v1/leads/:id/stage

Move a lead to a different pipeline stage.

Request Body​

FieldTypeRequiredDescription
stagestringYesNew stage
reasonstringNoReason for change
notesstringNoAdditional notes

Example Request​

curl -X POST "https://api.propertybase.ai/v1/leads/lead_abc123/stage" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stage": "negotiation",
    "notes": "Client made an offer"
  }'

Mark as Won​

POST /v1/leads/:id/won

Request Body​

FieldTypeRequiredDescription
property_idstringYesPurchased property
deal_valuenumberYesFinal deal value
commissionnumberNoCommission amount
notesstringNoClosing notes

Example Request​

curl -X POST "https://api.propertybase.ai/v1/leads/lead_abc123/won" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "property_id": "unit_789xyz",
    "deal_value": 825000,
    "commission": 24750,
    "notes": "Closed at asking price"
  }'

Mark as Lost​

POST /v1/leads/:id/lost

Request Body​

FieldTypeRequiredDescription
reasonstringYesLoss reason code
notesstringNoAdditional details

Example Request​

curl -X POST "https://api.propertybase.ai/v1/leads/lead_abc123/lost" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "bought_elsewhere",
    "notes": "Purchased from competitor"
  }'

Add Note​

POST /v1/leads/:id/notes

Example Request​

curl -X POST "https://api.propertybase.ai/v1/leads/lead_abc123/notes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Call summary: Discussed financing options",
    "type": "call"
  }'

Get Activity​

GET /v1/leads/:id/activity

Returns the activity timeline for a lead.

Example Response​

{
  "success": true,
  "data": [
    {
      "id": "activity_001",
      "type": "stage_change",
      "description": "Stage changed from 'qualified' to 'viewing'",
      "user": "agent_456def",
      "timestamp": "2024-01-24T10:00:00Z"
    },
    {
      "id": "activity_002",
      "type": "note",
      "description": "Added note: Viewing scheduled for Friday",
      "user": "agent_456def",
      "timestamp": "2024-01-24T10:05:00Z"
    }
  ]
}

Lead Stages​

StageDescription
newNewly created, not contacted
contactedInitial contact made
qualifiedBudget and needs confirmed
viewingProperty viewing scheduled
negotiationOffer and terms discussion
wonDeal closed successfully
lostDeal not closed

Lead Sources​

SourceDescription
websiteWebsite inquiry
referralClient referral
portalProperty portal
socialSocial media
walk_inWalk-in inquiry
apiAPI integration
manualManual entry

Loss Reasons​

ReasonDescription
price_too_highPrice too high
location_not_suitableLocation not suitable
bought_elsewhereBought from competitor
no_longer_interestedLost interest
unresponsiveNo response
financing_failedCould not secure financing
otherOther reason