Leads API - How to Edit Lead Data with API Calls

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

The API allows getting, creating, updating, matching, and deleting leads on the website. However, only one lead can be updated or deleted at a time.

For the system to auto-geocode the lead, the Enable All Location Features for "Pretty URL" Search Results Pages (Additional Google Maps API Cost) setting must be configured in the site's Advanced Settings. 


Available API Endpoints

Below is a list of the available endpoints for Leads:


https://example.com/api/v2/leads/get/{id}

https://example.com/api/v2/leads/create

https://example.com/api/v2/leads/update

https://example.com/api/v2/leads/match

https://example.com/api/v2/leads/delete/{id}


Get a Lead

This action retrieves the information for a single lead based on its ID.

Endpoint:

GET api/v2/leads/get/{id}

curl -H "Authorization: YOUR_API_KEY" \
  "https://example.com/api/v2/leads/get/{id}"


Example Request:

https://example.com/api/v2/leads/get/t?property=lead_id&property_value=1


Query Parameters:

propertyThe property key (eg., lead_id).
property_valueThe value associated with the property.

{
    "status": "success",
    "message": [
        {
            "lead_id": "1",
            "lead_name": "Sample Lead",
            "lead_email": "sample@sample.com",
            "lead_phone": "",
            "token": "35c32f52096a485531ea862e4b155fa2",
            "date_added": "2021-02-27T05:04:36+00:00",
            "status": "2",
            "lead_price": "0.00",
            "lead_more": "0",
            "lead_notes": "",
            "revision_timestamp": "2021-04-20T17:23:03+00:00",
            "lead_message": "This is a sample lead. Leads are inquiries from visitors who contact members. Leads can be free or you can charge a fee for members to view the full details of the lead. ",
            "top_id": "-1",
            "sub_id": "0",
            "lat": "37.09024",
            "lng": "-95.712891",
            "location_type": "country",
            "lead_location": "United States",
            "country_sn": "US",
            "adm_lvl_1_sn": "",
            "flow_source": "default_flow",
            "formname": "bootstrap_get_match",
            "CONTACT_TYPE": "bootstrap_get_match",
            "additional_replies": "",
            "url_from": "/united-states/los-angeles/top-level-category/sample-member",
            "DATE": "2021-02-27T05:04:36+00:00",
            "origin_ip": "55.555.555.55",
            "user_consent": "",
            "showCategory": "1",
        }
    ],
    "total": "1",
    "current_page": 1,
    "total_pages": 1


Create a Lead

This action adds a new lead to the database.

Parameter Notes: To use this action, your request should include the same variables found within the Website - Lead Form - Get Matched form. For a lead to be auto-matched, it must have either category information (top category or sub and sub-category), geocoded location information including lat and lon values, or both. Using the auto_geocode functionality will provide a geocoded location as long as Google Maps can provide that information based on the location name submitted with the lead.


Endpoint:

POST https://example.com/api/v2/leads/create


Example Request:

{
  "lead_name": "I need a carpenter",
  "lead_phone": "+14582051030",
  "lead_location": "830 N Shaver St, Portland, OR 97227, United States",
  "auto_match": "1",
  "auto_geocode": "1",
  "top_category_name": "Jazz",
  "sub_category_name": "Restaurant-Cafe",
  "lead_email": "francella@brilliantdirectories.com",
  "bdapi_model": "leads"
}



Query Parameters:

lead_idUnique identifier for the lead. (integer($primary_key))
lead_nameThe name of the lead.
lead_emailThe email address of the lead. 
lead_phoneThe phone number of the lead. 
date_addedTimestamp when the lead was added. 
statusThe current status of the lead. 
lead_priceThe price associated with the lead, if applicable.
lead_notesAdditional notes or comments about the lead. 
revision_timestampTimestamp of the last revision or update to the lead. (string($datetime))
lead_messageThe message or inquiry submitted by the lead.
top_idID of the top-level category associated with the lead.
sub_idID of the sub-category associated with the lead.
latLatitude coordinate of the lead's location.
lngLongitude coordinate of the lead's location.
swlatSouth-west latitude of the lead's location bounding box. 
swlngSouth-west longitude of the lead's location bounding box. 
nelatNorth-east latitude of the lead's location bounding box. 
nelngNorth-east longitude of the lead's location bounding box. 
location_typeType of location (e.g., country, city, address). 
lead_locationHuman-readable name of the lead's location.
country_snShort name (e.g., US) for the lead's country.
adm_lvl_1_snShort name for the first administrative level (e.g., state, province). 
flow_sourceThe source of the lead generation flow.
formnameThe name of the form through which the lead was submitted. 
url_fromThe URL from which the lead originated. 
origin_ipThe IP address from which the lead was submitted. (string)
auto_matchAutomatically matches the lead with possible members. (1 to enable, 0 to disable) 
auto_geocodeAutomatically geocodes the lead's location. (1 to enable, 0 to disable) 
sub_sub_idID of the sub-sub-category associated with the lead. 
send_lead_email_notificationActivates lead email notifications (1 to enable, 0 to disable). 
top_category_nameThe name of the top-level category. 
sub_category_nameThe name of the sub-category. 
sub_sub_category_nameThe name of the sub-sub-category. 



Example Response:


{
    "status": "success",
    "message": {
        "lead_id": "6",
        "lead_name": "I need a carpenter",
        "lead_email": "francella@brilliantdirectories.com",
        "lead_phone": "+14582051030",
        "token": "730802c7af4e6f02519d94cd56204389",
        "date_added": "2025-06-10T10:17:16+00:00",
        "status": "2",
        "lead_price": "0.00",
        "lead_more": "0",
        "revision_timestamp": "2025-06-10T10:17:16+00:00",
        "top_id": "4",
        "sub_id": "86",
        "lead_location": "830 N Shaver St, Portland, OR 97227, United States",
        "flow_source": "default_flow",
        "formname": "bootstrap_get_match",
        "CONTACT_TYPE": "bootstrap_get_match",
        "url_from": "Recebido de fonte externa",
        "DATE": "1970-01-01T00:00:00+00:00",
        "auto_match": "1",
        "auto_geocode": "1",
        "top_category_name": "Jazz",
        "sub_category_name": "Restaurant-Cafe",
        "lead_matches": false,
        "list_profession": {
            "profession_id": "4",
            "name": "Jazz",
            "filename": "jazz",
            "revision_timestamp": "2025-06-10 12:15:39",
            "sort_order": "0",
            "lead_price": null,
        },
        "list_services_sub": {
            "service_id": "86",
            "name": "Restaurant-Cafe",
            "profession_id": "4",
            "master_id": "0",
            "filename": "restaurant-cafe",
            "revision_timestamp": "2025-06-10 12:16:01",
            "sort_order": "0",
            "lead_price": null
        },
        "list_services_sub_sub": false
    }
}


Update a Lead

Add a new lead to the database.

Parameter Notes: With this action, you'll need to include the lead ID and the variables for the specific information that needs to be updated.


Endpoint:

POST https://example.com/api/v2/leads/update


Example Request:

{
  "lead_name": "I need to book a table",
  "lead_phone": "+14582051030",
  "lead_location": "830 N Shaver St, Portland, OR 97227, United States",
  "top_category_name": "Jazz",
  "sub_category_name": "Restaurant-Cafe",
  "lead_email": "francella@brilliantdirectories.com",
  "lead_id": "6",
  "bdapi_model": "leads"
}



Example Response:

{
    "status": "success",
    "message": {
        "lead_id": "6",
        "lead_name": "I need to book a table",
        "lead_email": "francella@brilliantdirectories.com",
        "lead_phone": "+14582051030",
        "token": "730802c7af4e6f02519d94cd56204389",
        "date_added": "2025-06-10T10:17:16+00:00",
        "status": "2",
        "lead_price": "0.00",
        "lead_more": "0",
        "revision_timestamp": "2025-06-10T10:17:16+00:00",
        "top_id": "4",
        "sub_id": "86",
        "lead_location": "830 N Shaver St, Portland, OR 97227, United States",
        "flow_source": "default_flow",
        "formname": "bootstrap_get_match",
        "CONTACT_TYPE": "bootstrap_get_match",
        "url_from": "Recebido de fonte externa",
        "DATE": "1970-01-01T00:00:00+00:00",
        "showCategory": null,
        "lead_preferred_day": null,
        "lead_preferred_time": null,
        "lead_matches": false,
        "list_profession": {
            "profession_id": "4",
            "name": "Jazz",
            "filename": "jazz",
            "revision_timestamp": "2025-06-10 12:15:39",
            "sort_order": "0",
            "lead_price": null,
        },
        "list_services_sub": {
            "service_id": "86",
            "name": "Restaurant-Cafe",
            "profession_id": "4",
            "master_id": "0",
            "filename": "restaurant-cafe",
            "revision_timestamp": "2025-06-10 12:16:01",
            "sort_order": "0",
            "lead_price": null
        },
        "list_services_sub_sub": false
    }
}


Match a Lead

Match lead to members.

This action requires the lead ID and either the IDs or email addresses of the members to whom the lead will be matched.



Endpoint:

POST https://example.com/api/v2/leads/match



Example Request:

{
  "lead_id": "6",
  "users_to_match": "testing@test.com,fran@test.com",
  "bdapi_model": "leads",
  "action": "match"
}


Query Parameters:

lead_idThe ID of the lead.
users_to_matchAdd the IDs or email addresses of the members to whom the lead will be matched. 



Example Response:

{
    "status": "success",
    "message": {
        "succes_matches": "testing@test.com - ID#1080",
        "fail_matches": "fran@test.com - ID#23"
    }
}


Delete a Lead

Use this action to remove a lead from the website.
Parameter Notes: Use lead_id to delete a lead.


Endpoint:


DELETE https://example.com/api/v2/leads/delete/{id}


Example Request:

{
  "lead_id": "5",
  "bdapi_model": "leads"
}


Example Response:

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