PropertyPredator API v1

Run PropertyPredator's appraisal engines and Legal-Pack reader from your own server, with your own API keys, and see every request and credit it used.

Your API keys

Plans and prices

The API is priced separately from the app plans. Prices below are loaded from the same configuration checkout charges, in GBP, VAT as applicable at checkout. Annual billing is twelve months for the price of nine.

Predator Business members have an included allowance without the add-on: 5,000 calculation requests a month, 30 a minute, 2 active keys, and Legal-Pack reviews charged to the plan's own lookup credits. Apex and other plans use the Sandbox tier unless they add Developer or Developer Pro.

Business includes up to 50 standard Legal-Pack AI review attempts and a £25 monthly supplier-cost budget, shared across the app and API. Whichever limit is reached first applies. Failed AI attempts and retries count; an idempotent API replay does not start a new review. Limits reset on the 1st of each month (UTC). Standard reviews must fit a conservative 50p supplier-cost reservation and complete-reading limits; larger packs need a separate quote before AI processing. Successful reviews still use 3 lookup credits; refunded lookup credits do not erase supplier costs.

Billing, cancellation and refunds

• The add-on is a monthly or annual subscription on your existing account, billed by card through our payment provider. Cancel any time from Manage billing; access continues to the end of the paid period and the account returns to Sandbox (or the Business allowance).
• Upgrading from Developer to Developer Pro takes effect immediately; the Developer subscription is cancelled with a pro-rata credit. To move down, cancel Developer Pro first.
• No money-back period applies to the add-on. Refunds are made only when the fault is on our side: a metered request that fails after reservation returns its credits automatically, and a billing error is corrected on request. Statutory rights are unaffected.
• Prices, allowances and limits may change for new periods with notice on this page; the version you are on does not change mid-period.

Getting started

1. Sign in with any PropertyPredator account and create a key above. Give it only the scopes it needs. The Sandbox tier is free; add Developer or Developer Pro when you need volume or the Legal-Pack endpoint.
2. Copy the key when it is shown. We store only a one-way fingerprint of it, so it cannot be shown again; if you lose it, revoke it and create another.
3. Keep the key on your server, in a secret store or environment variable. Never put it in browser code, mobile apps or a public repository.
4. Check it works:

curl https://propertypredator.com/api/v1/account \
  -H "Authorization: Bearer $PP_API_KEY"

The response shows your plan, the key's scopes, your current lookup-credit allowance and the limits below.

Authentication

Send the key in the Authorization header on every request: Authorization: Bearer ppk_…. API keys work only on /api/v1; browser sign-in tokens do not work there, and API keys do not work anywhere else.

Any valid key can call /account and /countries. Active keys per account: Sandbox 1, Business allowance 2, Developer 5, Developer Pro 15.

When a key stops working: when you revoke it, or when the account's sign-in security is reset (for example a password reset or account recovery) — create a new key afterwards. If the add-on lapses, keys keep working on the Sandbox tier and metered requests answer 403 addon_required.

Endpoints

Base URL https://propertypredator.com/api/v1. Requests and responses are JSON unless stated. Money is in the currency of the inputs you send; rates and percentages are decimals (0.25 means 25%). Responses may gain new fields, so ignore fields you do not use.

curl https://propertypredator.com/api/v1/appraisals \
  -H "Authorization: Bearer $PP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"strategy":"brr","inputs":{"purchase_price":150000,"value_after_refurb":210000,
       "expected_monthly_rent":1200,"construction_costs":25000,"legal_fees":1500,"stamp_duty":4500}}'

{"strategy":"brr","result":{"stamp_duty":4500,"refinance_release":157500.0,
  "after_refurb":{"money_left_in":23500.0,"net_monthly_return":366.9375,"ROCE":0.187…},
  "verdict":{"stamp":"BUY","label":"Strong","score":4,"max":4,"checks":[…]}, …}}

curl https://propertypredator.com/api/v1/appraisals/offer \
  -H "Authorization: Bearer $PP_API_KEY" -H "Content-Type: application/json" \
  -d '{"inputs":{"sale_value":250000,"construction_costs":30000,"time_months":6,"legal_fees":1500,"stamp_duty":3000}}'
# {"result":{"max_offer":173833.33,"first_offer":156450.0,"second_offer":165141.67,"feasible":true}}

curl https://propertypredator.com/api/v1/appraisals/scenarios \
  -H "Authorization: Bearer $PP_API_KEY" -H "Content-Type: application/json" \
  -d '{"strategy":"flip","inputs":{"purchase_price":160000,"sale_value":250000,"construction_costs":30000,
       "time_months":6,"stamp_duty":3000,"nation":"england"},
       "stress":{"exit_value_down_pct":10,"rent_down_pct":0,"works_up_pct":15,"time_up_pct":25}}'

curl https://propertypredator.com/api/v1/international/appraisals \
  -H "Authorization: Bearer $PP_API_KEY" -H "Content-Type: application/json" \
  -d '{"country_code":"FR","strategy":"hold","inputs":{"purchase_price":200000,"acquisition_costs":15000,
       "refurb_cost":10000,"loan_fees":1500,"finance_mode":"interest_only","loan_amount":140000,
       "annual_rate":0.04,"rent_amount":1100,"rent_period":"monthly","vacancy_pct":0.05,
       "management_pct":0.08,"maintenance_annual":900,"property_tax_annual":1200,"insurance_annual":400,
       "hoa_annual":0,"other_costs_annual":0,"target_cashflow_monthly":250,"target_coc_pct":0.04}}'
# {"result":{"currency_code":"EUR","metrics":{"cashflow_monthly":286.4,"dscr":1.61,…},"verdict":{…},…}}

curl https://propertypredator.com/api/v1/legal-pack/reviews \
  -H "Authorization: Bearer $PP_API_KEY" \
  -H "Idempotency-Key: pack-14-high-street-v1" \
  -F "file=@legal-pack.pdf;type=application/pdf"
# {"review":{"verdict":"REVIEW NEEDED","summary":"…","flags":[…],"coverage":{…}},
#  "charge":{"credits":3,"reservation_id":"…"}}

Credits, costs and limits

Metered API requests draw on your account's monthly lookup allowance and banked top-ups, the same pot the app uses. Developer adds 60 and Developer Pro adds 300 lookup credits a month to that allowance for API requests only; the app does not see them. Credits are reserved before the AI read starts and returned automatically if the read fails, so a failed review costs nothing. See lookup-credit costs for the wider catalogue.

Retries and idempotency

Calculation endpoints have no side effects and charge nothing, so they are safe to retry.

Legal-Pack reviews charge credits, so each needs an Idempotency-Key header: 8–100 letters, numbers or - _ . :, unique per review. Keys are scoped to your account.

• Retrying a completed review with the same key and the same file returns the original response, with Idempotent-Replayed: true, and charges nothing more, for 24 hours.
• The same key with a different file answers 422 idempotency_key_reused.
• A retry while the first request is still running answers 409 request_in_progress; wait and retry.
• If a review fails, its credits are returned and the same key may be used again.

Errors

Every v1 error has the same shape, and every response carries an X-Request-Id header.

{"error":{"code":"insufficient_scope","message":"This key does not have the 'appraisals' scope.",
          "status":403,"request_id":"req_3f2a9c…"}}

Coverage and restrictions

• Your figures in, our engines out. v1 calculates from the inputs you send. It does not look up or return property data, sold prices, comparables, EPCs, ownership, title, planning, flood or map data.
• UK appraisals use the app's UK engines. Stamp duty is your figure or the app's existing estimate for the nation you state.
• Country profiles: the United Kingdom (including Scotland and Northern Ireland), Ireland, France, Poland, United States, Australia, Greece and Turkey. International appraisals use the figures you send in local currency, with no automatic currency conversion or local tax calculation. A country profile is not a claim about data coverage in that country, and it does not mean ownership data is available there.
• Legal-Pack reviews read the PDF you upload with an AI model run by our AI provider, as in the app. Only send documents you are entitled to share.
• Outputs are decision support, not financial, investment, tax, legal, planning or surveying advice.
• Use is subject to the Terms and Privacy notice. Keys are for your account's own use.

Usage visibility and what we record

For each API request we record the key's prefix, the endpoint, method, status, error code, duration, credits and the credit reservation id, for 90 days. We do not record the key itself, request bodies, query strings, uploaded files or responses in that log. The response to a completed Legal-Pack review is kept for 24 hours only so a retry can be replayed, then deleted. Charges also appear in your account's credit history with the tool and key prefix.

Support

Email support@propertypredator.com with the request_id from the error or the X-Request-Id header, the endpoint and the time. Never send your API key; we will never ask for it.