Playbook tiers

The playbook tiers endpoint returns how strongly a property fits each of our acquisition playbooks. Each matched playbook is graded gold, silver, or bronze. Playbooks that were evaluated and ruled out are listed in excluded; playbooks no rollup has scored yet are listed in not_evaluated, each with a per-playbook reason. Use it to spot which strategies a property unlocks at a glance. Required scope: market-data:read Cost: 1 request per call

Get playbook tiers for a property

GET /api/v1/playbook-tiers

Returns the tier for each playbook the property matches, plus which playbooks were ruled out and which have not been evaluated yet.

Authentication

Authorization: Bearer paid_your_key

All endpoints accept a paid_* API key or a logged-in Clerk session. Anonymous requests are rejected with 401.

Query parameters

Param	Type	Default	Description
`property_id`	string (UUID)	—	Required. The property’s UUID

Request

curl "https://api.propaideals.co.uk/api/v1/playbook-tiers?property_id=5fa1b2c3-d4e5-6f78-9012-3456789abcde" \
  -H "Authorization: Bearer paid_your_key"

import requests

res = requests.get(
    "https://api.propaideals.co.uk/api/v1/playbook-tiers",
    params={"property_id": "5fa1b2c3-d4e5-6f78-9012-3456789abcde"},
    headers={"Authorization": "Bearer paid_your_key"},
)
tiers = res.json()["data"]["tiers"]

const params = new URLSearchParams({ property_id: "5fa1b2c3-d4e5-6f78-9012-3456789abcde" });
const res = await fetch(
  `https://api.propaideals.co.uk/api/v1/playbook-tiers?${params}`,
  { headers: { Authorization: "Bearer paid_your_key" } },
);
const { data } = await res.json();

Response

{
  "data": {
    "property_id": "5fa1b2c3-d4e5-6f78-9012-3456789abcde",
    "tiers": {
      "brrr_candidate": "gold",
      "hmo_conversion": "silver",
      "recently_reduced": "gold",
      "motivated_seller": "bronze",
      "epc_below_c": "silver",
      "btl_candidate": "gold"
    },
    "excluded": ["serviced_accommodation"],
    "not_evaluated": ["lease_extension", "pd_conversion", "..."],
    "not_evaluated_reasons": {
      "lease_extension": "Lease Extension is evaluated only for active leasehold sale flats with a KNOWN remaining lease term between 25 and 120 years; ..."
    },
    "evaluated_count": 7,
    "playbook_count": 20,
    "coverage_state": {
      "qualified": 6,
      "excluded": 1,
      "not_evaluated": 13,
      "evaluated": 7,
      "playbook_count": 20,
      "not_evaluated_by_reason": {
        "sweep_not_reached": 8,
        "restricted_population": 5
      },
      "dominant_not_evaluated_reason": "sweep_not_reached"
    }
  },
  "meta": {
    "usage": {
      "request_cost": 1,
      "monthly_used": 4826,
      "monthly_limit": 100000
    }
  }
}

Tier values

Value	Meaning
`gold`	Strong fit — the property is a prime candidate for this playbook
`silver`	Good fit — worth investigating
`bronze`	Marginal fit — a possible angle

Response fields

Field	Type	Description
`tiers`	object	Playbooks the property qualifies for, slug → `gold`/`silver`/`bronze`
`excluded`	array	Playbooks evaluated against this property and ruled out — a negative result, not a missing one
`not_evaluated`	array	Playbooks with no stored result yet. Each playbook is backfilled by its own rollup at its own depth, so this list is normally non-empty — absence from `tiers` on its own has never meant “does not qualify”
`not_evaluated_reasons`	object	For each slug in `not_evaluated`, what a missing result means for that playbook. Always present; `{}` when everything is evaluated
`evaluated_count`	integer	Playbooks with a stored result (qualified + excluded)
`playbook_count`	integer	Playbooks this endpoint reports on (20)
`coverage_state`	object	Count rollup: `qualified`, `excluded`, `not_evaluated`, `evaluated`, `playbook_count`, `not_evaluated_by_reason` (counts by `sweep_not_reached` / `restricted_population`) and `dominant_not_evaluated_reason`. A sparse `tiers` map with a low `evaluated` count is the normal state of a property the rollout has barely reached, not an error

A strategy whose playbook verdict here is excluded also publishes no score on strategy scores — the two surfaces answer as one.

Available playbook slugs

Slug	Slug	Slug
`brrr_candidate`	`hmo_conversion`	`serviced_accommodation`
`recently_reduced`	`back_on_market`	`stale_listing`
`motivated_seller`	`tenanted_submarket`	`cash_buyer_only`
`epc_below_c`	`btl_candidate`	`flip_candidate`
`auction_deal`	`probate_sale`	`rent_to_rent`
`brownfield_adjacency`	`pd_conversion`	`plot_subdivision`
`lease_extension`	`house_to_flats`

Common patterns

List the gold-tier playbooks a property unlocks

res = requests.get(
    "https://api.propaideals.co.uk/api/v1/playbook-tiers",
    params={"property_id": property_id},
    headers={"Authorization": "Bearer paid_your_key"},
).json()["data"]

gold = [slug for slug, tier in res["tiers"].items() if tier == "gold"]
print(f"Gold playbooks: {', '.join(gold)}")

Get started

API reference

Granular endpoints

Resources

Playbook tiers endpoint

Playbook tiers

Get playbook tiers for a property

Authentication

Query parameters

Request

Response

Tier values

Response fields

Available playbook slugs

Common patterns

List the gold-tier playbooks a property unlocks

​Playbook tiers

​Get playbook tiers for a property

​Authentication

​Query parameters

​Request

​Response

​Tier values

​Response fields

​Available playbook slugs

​Common patterns

​List the gold-tier playbooks a property unlocks

Playbook tiers

Get playbook tiers for a property

Authentication

Query parameters

Request

Response

Tier values

Response fields

Available playbook slugs

Common patterns

List the gold-tier playbooks a property unlocks