API Reference - Lead Matches

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

← Back to API Reference | Getting Started

Lead Matches

Lead Matches represent the associations between leads and the members they were matched to. When a lead is submitted and matched, one record is created per matched member, tracking the match status, pricing, member response, and acceptance state.

Model name in URL: lead_matches — DB table: lead_matches

The Lead Matches Object

FieldTypeDescription
match_idintegerUnique lead match ID (primary key, read-only)
lead_idintegerID of the lead this match belongs to
user_idintegerID of the member who was matched to this lead
lead_matchedstringDate and time the match was created, formatted as YYYYMMDDHHmmss
lead_pointsintegerPoints awarded or deducted for this match
lead_match_notestextInternal notes about this match
lead_statusintegerCurrent status of the match (EG 1 = active, 4 = declined)
match_pricenumberPrice charged to the member for receiving this lead
lead_tokenstringUnique token used to identify this match in email links and tracking
lead_matched_bystringHow the match was created (EG system for automatic matching)
lead_viewedstringDate and time the member viewed this lead, formatted as YYYYMMDDHHmmss
lead_typestringType or category of this lead match
lead_distancestringDistance between the lead location and the matched member
lead_ratingstringRating assigned to this match
lead_chosenintegerWhether the lead submitter chose this member (1 = chosen, 0 = not chosen)
lead_responsetextThe member's response message to the lead
lead_acceptedstringDate and time the member accepted the lead, formatted as YYYYMMDDHHmmss
lead_updatedstringDate and time this record was last updated, formatted as YYYYMMDDHHmmss

List Lead Matches Records

GET /api/v2/lead_matches/get

Returns a paginated list of lead match records.

Example Request

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

Example Response

Copy
{
  "status": "success",
  "message": [
    {
      "tablesExists": true,
      "match_id": "3",
      "lead_id": "1",
      "user_id": "1",
      "lead_matched": "20210107054345",
      "lead_points": "0",
      "lead_match_notes": "",
      "lead_status": "1",
      "match_price": "0.00",
      "lead_token": "578625ef5fa1ffb824f69d099aa16773",
      "lead_matched_by": "system",
      "lead_viewed": "",
      "lead_type": "",
      "lead_distance": "",
      "lead_rating": "",
      "lead_chosen": "0",
      "lead_response": "",
      "lead_accepted": "",
      "lead_updated": "20210107054345"
    }
  ],
  "total": "30",
  "current_page": 1,
  "total_pages": 10,
  "next_page": "MipfKjM="
}

Retrieve a Lead Match

GET /api/v2/lead_matches/get/{match_id}

Example Request

Copy
curl -X GET "https://www.yourdomain.com/api/v2/lead_matches/get/3" \
  -H "X-Api-Key: your-api-key-here"

Example Response

Copy
{
  "status": "success",
  "message": [
    {
      "tablesExists": true,
      "match_id": "3",
      "lead_id": "1",
      "user_id": "1",
      "lead_matched": "20210107054345",
      "lead_points": "0",
      "lead_match_notes": "",
      "lead_status": "1",
      "match_price": "0.00",
      "lead_token": "578625ef5fa1ffb824f69d099aa16773",
      "lead_matched_by": "system",
      "lead_viewed": "",
      "lead_type": "",
      "lead_distance": "",
      "lead_rating": "",
      "lead_chosen": "0",
      "lead_response": "",
      "lead_accepted": "",
      "lead_updated": "20210107054345"
    }
  ],
  "total": "1",
  "current_page": 1,
  "total_pages": 1
}

Create a Lead Match

POST /api/v2/lead_matches/create

Example Request

Copy
curl -X POST "https://www.yourdomain.com/api/v2/lead_matches/create" \
  -H "X-Api-Key: your-api-key-here" \
  -d "lead_id=1" \
  -d "user_id=42" \
  -d "lead_matched=20260403120000" \
  -d "lead_status=1" \
  -d "match_price=0.00" \
  -d "lead_token=abc123uniquetoken" \
  -d "lead_matched_by=system" \
  -d "lead_updated=20260403120000"

Example Response

Copy
{
  "status": "success",
  "message": {
    "match_id": "31",
    "lead_id": "1",
    "user_id": "42",
    "lead_matched": "20260403120000",
    "lead_points": null,
    "lead_match_notes": null,
    "lead_status": "1",
    "match_price": "0.00",
    "lead_token": "abc123uniquetoken",
    "lead_matched_by": "system",
    "lead_viewed": null,
    "lead_type": null,
    "lead_distance": null,
    "lead_rating": null,
    "lead_chosen": null,
    "lead_response": null,
    "lead_accepted": null,
    "lead_updated": "20260403120000"
  }
}

Update a Lead Match

PUT /api/v2/lead_matches/update

Example Request

Copy
curl -X PUT "https://www.yourdomain.com/api/v2/lead_matches/update" \
  -H "X-Api-Key: your-api-key-here" \
  -d "match_id=31" \
  -d "lead_status=2" \
  -d "lead_response=Thank+you+for+reaching+out%2C+I+will+contact+you+soon."

Example Response

Copy
{
  "status": "success",
  "message": {
    "match_id": "31",
    "lead_id": "0",
    "user_id": "0",
    "lead_matched": "",
    "lead_points": "0",
    "lead_match_notes": "",
    "lead_status": "2",
    "match_price": "0.00",
    "lead_token": "",
    "lead_matched_by": "",
    "lead_viewed": "",
    "lead_type": "",
    "lead_distance": "",
    "lead_rating": "",
    "lead_chosen": "0",
    "lead_response": "Thank you for reaching out, I will contact you soon.",
    "lead_accepted": "",
    "lead_updated": ""
  }
}

Delete a Lead Match

DELETE /api/v2/lead_matches/delete

Example Request

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

Example Response

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