Leads API

Connect custom forms, websites, CRMs, and workflows to the same lead records used by EasyAgentIDX. Lead access is available on Pro and higher plans.

Warning

Lead records contain private customer information. Keep API keys on the server, authorize every user of your application, and return only the fields each user needs.

Required headers

Authorization: Bearer eai_YOUR_KEY
X-EAI-Site-ID: site_YOUR_SITE_ID
Content-Type: application/json

GET /api/v1/leads

List leads for the approved website in reverse chronological order. Requires leads:read.

Parameter	Type	Description
`status`	string	`new`, `contacted`, `active`, `closed`, or `lost`
`email`	string	Exact email match
`q`	string	Search name, email, or phone. Maximum 200 characters
`created_after`	ISO date	Include records created on or after this time
`created_before`	ISO date	Include records created on or before this time
`page`	integer	Page number. Default 1
`per_page`	integer	Results per page. Default 25, maximum 100

curl "https://app.easyagentidx.com/api/v1/leads?status=new&created_after=2026-08-01&per_page=50"   -H "Authorization: Bearer $EASYAGENTIDX_API_KEY"   -H "X-EAI-Site-ID: $EASYAGENTIDX_SITE_ID"

POST /api/v1/leads

Create a lead from a custom server-side form or application. Requires leads:write.

{
  "email": "jane@example.com",
  "name": "Jane Smith",
  "phone": "+1 619 555 0123",
  "message": "Interested in a private showing",
  "source_listing": "listing-id",
  "source_widget_id": "optional-widget-id",
  "source_search": { "location": "La Jolla, CA" }
}

If source_widget_id is provided, the widget must be active and belong to the approved website bound to the key.

GET /api/v1/leads/:id

Read one lead. Requires leads:read. A lead from another account returns 404.

PATCH /api/v1/leads/:id

Update status, notes, name, or phone. Requires leads:write.

{
  "status": "contacted",
  "notes": "Showing scheduled for Friday"
}

DELETE /api/v1/leads/:id

Permanently delete a lead and its activity history. Requires leads:write. Confirm destructive actions in your own interface before calling this endpoint.

Lead response

{
  "data": {
    "id": "cm...",
    "email": "jane@example.com",
    "name": "Jane Smith",
    "phone": "+1 619 555 0123",
    "status": "new",
    "source": {
      "widget_id": null,
      "domain": "example.com",
      "listing_id": "listing-id"
    },
    "notes": "Interested in a private showing",
    "created_at": "2026-08-25T18:30:00.000Z",
    "updated_at": "2026-08-25T18:30:00.000Z"
  }
}

PreviousTypeahead NextValuations