API Reference - Leads

Link: https://support.brilliantdirectories.com/support/solutions/articles/12000108049

← Back to API Reference | Getting Started

Leads

Leads are inquiries submitted by visitors seeking to connect with members. Leads can be automatically matched to relevant members based on category, location, and service area criteria.

Model name in URL: leads — DB table: leads

The Lead Object

FieldTypeDescription
lead_idintegerUnique lead ID (primary key, read-only)
lead_namestringContact name of the lead submitter
lead_emailstringEmail address of the lead submitter
lead_phonestringPhone number of the lead submitter
lead_messagetextFull message/description of the lead request
lead_notestextInternal notes about this lead
lead_locationstringFormatted location address for this lead
top_idintegerTop-level category ID for matching
sub_idintegerSub-category ID for matching
latstringLatitude coordinate
lngstringLongitude coordinate
statusstringLead status
lead_pricenumberPrice associated with this lead
date_addedstringDate lead was created (format: YYYYMMDDHHmmss)
formnamestringName of the form used to submit this lead
url_fromstringURL of the page where lead was submitted
tokenstringUnique lead token (auto-generated)
CONTACT_TYPEstringType of contact/inquiry
origin_ipstringIP address of the submitter
flow_sourcestringSource of the lead flow
additional_repliesstring1 to allow additional replies, 0 otherwise
lead_moreintegerFlag indicating additional lead information is available
utokenstringUser token identifying the visitor who submitted the lead
swlatstringSouthwest boundary latitude (geocoded bounding box)
swlngstringSouthwest boundary longitude (geocoded bounding box)
nelatstringNortheast boundary latitude (geocoded bounding box)
nelngstringNortheast boundary longitude (geocoded bounding box)
location_typestringGeocode precision level (e.g. ROOFTOP, APPROXIMATE, postal_code)
country_snstringCountry short name/code from geocoding (e.g. US)
adm_lvl_1_snstringAdministrative level 1 short name from geocoding (e.g. state code CA)
DATEstringLead submission date
user_consenttextRecord of user consent (GDPR/privacy compliance)
revision_timestamptimestampLast revision timestamp
lead_preferred_daystringPreferred day for lead contact
lead_preferred_timestringPreferred time for lead contact
sub_sub_idintegerSub-sub category ID
lead_submission_locationstringLocation from which lead was submitted
auto_geocode_resultstringAutomatic geocode result
lead_matchesobjectNested lead matches data (included on single-record GET responses)
list_professionintegerCategory lookup: has profession listing (0 or 1)
list_services_subintegerCategory lookup: has sub-service listing (0 or 1)
list_services_sub_subintegerCategory lookup: has sub-sub-service listing (0 or 1)

List Leads

GET /api/v2/leads/get
Copy
curl -X GET "https://www.yourdomain.com/api/v2/leads/get?limit=25" \
  -H "X-Api-Key: your-api-key-here"

Retrieve a Lead

GET /api/v2/leads/get/{lead_id}
Copy
curl -X GET "https://www.yourdomain.com/api/v2/leads/get/55" \
  -H "X-Api-Key: your-api-key-here"

Create a Lead

POST /api/v2/leads/create

Creates a new lead. After creation, the lead can be matched to members using the Match endpoint.

Example Request

Copy
curl -X POST "https://www.yourdomain.com/api/v2/leads/create" \
  -H "X-Api-Key: your-api-key-here" \
  -d "lead_name=Bob+Johnson" \
  -d "lead_email=bob@example.com" \
  -d "lead_phone=555-123-4567" \
  -d "lead_message=I+need+a+plumber+for+a+leak" \
  -d "lead_location=Chicago%2C+IL" \
  -d "top_id=12"

Example Response

Copy
{
  "status": "success",
  "message": {
    "lead_id": "201",
    "lead_name": "Bob Johnson",
    "lead_email": "bob@example.com",
    "lead_phone": "555-123-4567",
    "token": "a1b2c3d4e5f6",
    "date_added": "2026-03-01T12:00:00+00:00",
    "status": "2",
    "lead_price": "0.00",
    "lead_more": "0",
    "lead_notes": "",
    "revision_timestamp": "2026-03-01T12:00:00+00:00",
    "lead_message": "I need a plumber for a leak",
    "top_id": "12",
    "sub_id": "0",
    "lead_location": "Chicago, IL",
    "flow_source": "default_flow",
    "lead_status": "1"
  }
}

Match a Lead

POST /api/v2/leads/match

Triggers the automatic lead-matching algorithm for an existing lead. The system finds members whose category, location, and service area match the lead's criteria and sends them lead notification emails.

Parameters

ParameterTypeDescription
lead_idintegerRequired — ID of the lead to match

Example Request

Copy
curl -X POST "https://www.yourdomain.com/api/v2/leads/match" \
  -H "X-Api-Key: your-api-key-here" \
  -d "lead_id=201"

Example Response

Copy
{
  "status": "success",
  "message": "Lead matched to 5 members"
}

Update a Lead

PUT /api/v2/leads/update

Example Request

Copy
curl -X PUT "https://www.yourdomain.com/api/v2/leads/update" \
  -H "X-Api-Key: your-api-key-here" \
  -d "lead_id=201" \
  -d "lead_name=Bob+Johnson+Updated" \
  -d "lead_notes=Resolved+by+member+#42"

Example Response

Copy
{
  "status": "success",
  "message": {
    "lead_id": "201",
    "lead_name": "Bob Johnson Updated",
    "lead_email": "bob@example.com",
    "lead_phone": "555-123-4567",
    "token": "a1b2c3d4e5f6",
    "date_added": "2026-03-01T12:00:00+00:00",
    "status": "2",
    "lead_price": "0.00",
    "lead_more": "0",
    "lead_notes": "Resolved by member #42",
    "revision_timestamp": "2026-03-01T12:00:00+00:00",
    "lead_message": "I need a plumber for a leak",
    "top_id": "12",
    "sub_id": "0",
    "lead_location": "Chicago, IL",
    "flow_source": "default_flow",
    "lead_status": "1"
  }
}

Delete a Lead

DELETE /api/v2/leads/delete

Example Request

Copy
curl -X DELETE "https://www.yourdomain.com/api/v2/leads/delete" \
  -H "X-Api-Key: your-api-key-here" \
  -d "lead_id=201"

Example Response

Copy
{
  "status": "success",
  "message": "leads record was deleted"
}