Matching

Explainable requirement ↔ listing matches for leads and listings.

GET/v1/matches/leads/{leadId}

Matching listings (and projects) for a lead

Stored listing matches, best first, with explainable reasons. `include_projects=true` also scores project configurations (buyers and investors). The lead must be visible to the caller.

Access: API key with leads:read, or a member session. Permission leads.view.

Parameters

leadIdpathrequired: Id
Opaque record id.
min_scorequery: integer
statusquery: MatchStatus
limitquery: integer
include_projectsquery: string

Response · 200

datarequired: object
data.matchesrequired: array of PropertyMatch
data.projectsrequired: array of ProjectMatch
data.computed_atrequired: DateTime or null
Instant in ISO 8601, e.g. 2026-10-03T04:30:00.000Z.
metarequired: object

Request

curl -X GET 'https://api.propzolo.com/v1/matches/leads/{leadId}' \
  -H 'Authorization: Bearer pz_live_…'

Response example

{
  "data": {
    "matches": [
      {
        "id": "cmusrceel0000q7kaafxqi1om",
        "score": 0,
        "status": "suggested",
        "reasons": {},
        "property": {
          "id": "cmusrceel0000q7kaafxqi1om",
          "ref_code": "P-2031",
          "listing_type": "sale",
          "category": "residential",
          "property_type": "apartment",
          "title": "string",
          "status": "draft",
          "bhk": 0,
          "bathrooms": 0,
          "layout": "simplex",
          "carpet_area": 0,
          "builtup_area": 0,
          "super_area": 0,
          "plot_area": 0,
          "area_unit": "sqft",
          "area_sqft": 0,
          "price": 850000000,
          "price_per_sqft": 850000000,
          "price_on_request": true,
          "rent_amount": 850000000,
          "deposit_amount": 850000000,
          "maintenance_amount": 850000000,
          "maintenance_period": "string",
          "furnishing": "unfurnished",
          "facing": "north",
          "possession_status": "ready_to_move",
          "possession_date": "2026-10-06",
          "available_from": "2026-10-06",
          "society_name": "string",
          "sub_locality": "string",
          "city": "string",
          "locality": {
            "id": "cmusrceel0000q7kaafxqi1om",
            "name": "string",
            "city": "string"
          },
          "latitude": 0,
          "longitude": 0,
          "location_precision": "exact",
          "cover_url": "string",
          "photos_count": 0,
          "matches_count": 0,
          "listed_by": {
            "id": "cmusrceel0000q7kaafxqi1om",
            "name": "string"
          },
          "is_featured": true,
          "verified_at": "2026-10-06T05:30:00.000Z",
          "verification_badge": {
            "status": "verified",
            "verified_at": "2026-10-06T05:30:00.000Z",
            "expires_at": "2026-10-06T05:30:00.000Z",
            "valid_until": "2026-10-06"
          },
          "views_count": 0,
          "shares_count": 0,
          "enquiries_count": 0,
          "visits_count": 0,
          "created_at": "2026-10-06T05:30:00.000Z",
          "updated_at": "2026-10-06T05:30:00.000Z"
        },
        "updated_at": "2026-10-06T05:30:00.000Z"
      }
    ],
    "projects": [
      {
        "score": 0,
        "reasons": {},
        "project": {
          "id": "cmusrceel0000q7kaafxqi1om",
          "name": "string",
          "locality": "string",
          "possession_date": "string",
          "cp_brokerage_pct": 0
        },
        "configuration": {
          "id": "cmusrceel0000q7kaafxqi1om",
          "name": "string",
          "property_type": "apartment",
          "bhk": 0,
          "price_min": 850000000,
          "price_max": 850000000
        }
      }
    ],
    "computed_at": "2026-10-06T05:30:00.000Z"
  },
  "meta": {}
}

Errors

401 No valid session or API key (missing, expired or revoked).
403 The caller lacks the permission, API-key scope or support grant this operation needs.
404 Not found — records of another company are reported the same way.
422 Invalid input; `error.fields` maps field paths to messages.
429 Too many requests; retry after the Retry-After header.
500 Unexpected error; quote `error.request_id` to support.

GET/v1/matches/properties/{propertyId}

Matching leads for a listing

Open buyer / tenant leads whose requirement fits, limited to the leads the caller may see.

Access: API key with properties:read, or a member session. Permission properties.view.

Parameters

propertyIdpathrequired: Id
Opaque record id.
min_scorequery: integer
statusquery: MatchStatus
limitquery: integer

Response · 200

datarequired: object
data.matchesrequired: array of LeadMatch
data.hiddenrequired: integer
metarequired: object

Request

curl -X GET 'https://api.propzolo.com/v1/matches/properties/{propertyId}' \
  -H 'Authorization: Bearer pz_live_…'

Response example

{
  "data": {
    "matches": [
      {
        "id": "cmusrceel0000q7kaafxqi1om",
        "score": 0,
        "status": "suggested",
        "reasons": {},
        "lead": {
          "id": "cmusrceel0000q7kaafxqi1om",
          "ref": "L-10234",
          "name": "string",
          "lead_type": "buy",
          "temperature": "hot",
          "owner": {
            "id": "cmusrceel0000q7kaafxqi1om",
            "name": "string"
          },
          "budget_min": 850000000,
          "budget_max": 850000000,
          "bhk": [
            0
          ],
          "status_name": "string"
        },
        "updated_at": "2026-10-06T05:30:00.000Z"
      }
    ],
    "hidden": 0
  },
  "meta": {}
}

Errors

401 No valid session or API key (missing, expired or revoked).
403 The caller lacks the permission, API-key scope or support grant this operation needs.
404 Not found — records of another company are reported the same way.
422 Invalid input; `error.fields` maps field paths to messages.
429 Too many requests; retry after the Retry-After header.
500 Unexpected error; quote `error.request_id` to support.

POST/v1/matches/recompute

Recompute matches now

Matches are recomputed automatically on lead and listing changes; this refreshes one at once.

Access: API key with properties:read, or a member session. Permission properties.view.

Request body

No fields.

Response · 200

datarequired: RecomputeResult
metarequired: object

Request

curl -X POST 'https://api.propzolo.com/v1/matches/recompute' \
  -H 'Authorization: Bearer pz_live_…' \
  -H 'Content-Type: application/json' \
  -d '{"lead_id":"cmusrceel0000q7kaafxqi1om"}'

Response example

{
  "data": {
    "matched": 0,
    "removed": 0,
    "skipped": "string"
  },
  "meta": {}
}

Errors

401 No valid session or API key (missing, expired or revoked).
403 The caller lacks the permission, API-key scope or support grant this operation needs.
409 A unique value already exists, a concurrent change won, or the Idempotency-Key is still in use or was sent with a different request.
422 Invalid input; `error.fields` maps field paths to messages.
429 Too many requests; retry after the Retry-After header.
500 Unexpected error; quote `error.request_id` to support.

PATCH/v1/matches/{id}

Dismiss or restore a match

Access: API key with leads:write, or a member session. Permission leads.edit.

Parameters

idpathrequired: Id
Opaque record id.

Request body

statusrequired: "dismissed" | "suggested"

Response · 200

datarequired: object
data.idrequired: Id
Opaque record id.
data.statusrequired: MatchStatus
metarequired: object

Request

curl -X PATCH 'https://api.propzolo.com/v1/matches/{id}' \
  -H 'Authorization: Bearer pz_live_…' \
  -H 'Content-Type: application/json' \
  -d '{"status":"dismissed"}'

Response example

{
  "data": {
    "id": "cmusrceel0000q7kaafxqi1om",
    "status": "suggested"
  },
  "meta": {}
}

Errors

401 No valid session or API key (missing, expired or revoked).
403 The caller lacks the permission, API-key scope or support grant this operation needs.
404 Not found — records of another company are reported the same way.
409 A unique value already exists, a concurrent change won, or the Idempotency-Key is still in use or was sent with a different request.
422 Invalid input; `error.fields` maps field paths to messages.
429 Too many requests; retry after the Retry-After header.
500 Unexpected error; quote `error.request_id` to support.

{ "data": { "matches": [ { "id": "cmusrceel0000q7kaafxqi1om", "score": 0, "status": "suggested", "reasons": {}, "property": { "id": "cmusrceel0000q7kaafxqi1om", "ref_code": "P-2031", "listing_type": "sale", "category": "residential", "property_type": "apartment", "title": "string", "status": "draft", "bhk": 0, "bathrooms": 0, "layout": "simplex", "carpet_area": 0, "builtup_area": 0, "super_area": 0, "plot_area": 0, "area_unit": "sqft", "area_sqft": 0, "price": 850000000, "price_per_sqft": 850000000, "price_on_request": true, "rent_amount": 850000000, "deposit_amount": 850000000, "maintenance_amount": 850000000, "maintenance_period": "string", "furnishing": "unfurnished", "facing": "north", "possession_status": "ready_to_move", "possession_date": "2026-10-06", "available_from": "2026-10-06", "society_name": "string", "sub_locality": "string", "city": "string", "locality": { "id": "cmusrceel0000q7kaafxqi1om", "name": "string", "city": "string" }, "latitude": 0, "longitude": 0, "location_precision": "exact", "cover_url": "string", "photos_count": 0, "matches_count": 0, "listed_by": { "id": "cmusrceel0000q7kaafxqi1om", "name": "string" }, "is_featured": true, "verified_at": "2026-10-06T05:30:00.000Z", "verification_badge": { "status": "verified", "verified_at": "2026-10-06T05:30:00.000Z", "expires_at": "2026-10-06T05:30:00.000Z", "valid_until": "2026-10-06" }, "views_count": 0, "shares_count": 0, "enquiries_count": 0, "visits_count": 0, "created_at": "2026-10-06T05:30:00.000Z", "updated_at": "2026-10-06T05:30:00.000Z" }, "updated_at": "2026-10-06T05:30:00.000Z" } ], "projects": [ { "score": 0, "reasons": {}, "project": { "id": "cmusrceel0000q7kaafxqi1om", "name": "string", "locality": "string", "possession_date": "string", "cp_brokerage_pct": 0 }, "configuration": { "id": "cmusrceel0000q7kaafxqi1om", "name": "string", "property_type": "apartment", "bhk": 0, "price_min": 850000000, "price_max": 850000000 } } ], "computed_at": "2026-10-06T05:30:00.000Z" }, "meta": {} }

{ "data": { "matches": [ { "id": "cmusrceel0000q7kaafxqi1om", "score": 0, "status": "suggested", "reasons": {}, "lead": { "id": "cmusrceel0000q7kaafxqi1om", "ref": "L-10234", "name": "string", "lead_type": "buy", "temperature": "hot", "owner": { "id": "cmusrceel0000q7kaafxqi1om", "name": "string" }, "budget_min": 850000000, "budget_max": 850000000, "bhk": [ 0 ], "status_name": "string" }, "updated_at": "2026-10-06T05:30:00.000Z" } ], "hidden": 0 }, "meta": {} }

PATCH/v1/matches/{id}

Dismiss or restore a match

Access: API key with leads:write, or a member session. Permission leads.edit.

Parameters

idpathrequired: Id
Opaque record id.

Request body

statusrequired: "dismissed" | "suggested"

Response · 200

datarequired: object
data.idrequired: Id
Opaque record id.
data.statusrequired: MatchStatus
metarequired: object

Request

curl -X PATCH 'https://api.propzolo.com/v1/matches/{id}' \
  -H 'Authorization: Bearer pz_live_…' \
  -H 'Content-Type: application/json' \
  -d '{"status":"dismissed"}'

Response example

{
  "data": {
    "id": "cmusrceel0000q7kaafxqi1om",
    "status": "suggested"
  },
  "meta": {}
}

Errors

401 No valid session or API key (missing, expired or revoked).
403 The caller lacks the permission, API-key scope or support grant this operation needs.
404 Not found — records of another company are reported the same way.
409 A unique value already exists, a concurrent change won, or the Idempotency-Key is still in use or was sent with a different request.
422 Invalid input; `error.fields` maps field paths to messages.
429 Too many requests; retry after the Retry-After header.
500 Unexpected error; quote `error.request_id` to support.