# Quickstart

The Lift Data API scores a property address and returns a rehab-aware valuation, a
likely investor price and a deal viability verdict. One request is enough to see it
work.

## Before you start

- **The API is prepaid.** Your Account holds a Balance of Credits, and **one Credit is
  spent per Scored Call at every Tier** — a Balance of N means N calls. There is
  nothing recurring: you buy Credits, you spend Credits.
- **You need an API Key.** Issue one from the Portal. It is shown to you once, in
  full, at creation; after that only its masked prefix is displayed.

## Score a property

Replace `YOUR_API_KEY` with your own API Key. Everything else runs as written.

> **Trying it in the API playground?** This API accepts JSON bodies only. Keep the
> playground's body in its plain-text mode with valid JSON in it, and make sure a
> `Content-Type: application/json` header is active before you send — any other body
> mode, or a missing content type, is answered with a 400. Picking the request example
> from the playground's Examples menu sets the body and the header in one step.

```bash
curl https://api.investorliftdata.com/v1/predict \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8b2f6c1a-4d0e-4f7a-9c3b-2e5d8a1f0b64" \
  -d '{"address": "1026 N Beckley Ave, Dallas, TX 75203"}'
```

The `Idempotency-Key` header is there so a retry can never charge you twice: send the
same request with the same key and you get the stored result back instead of a second
Spend. Any value unique to the request works — a UUID is the usual choice. The header
is optional, and a request without one is never an error; it is simply charged per
call. The full contract is on the [Idempotency page](/idempotency).

A success is an HTTP 200 whose body carries the valuation members —
`comp_band`, `likely_investor_price`, `flip_viability` and the rest. What each member
means, and what this valuation is and is not, is on
[Reading a score](/reading-a-score). The complete request and response schema is in
the [API reference](/api).

## Check a key or an address shape for free

`POST /v1/validate` is free: it consumes no Credits, makes no Ledger call at all, and
keeps working at a zero Balance. It requires only a valid API Key. It also **ignores**
any `Idempotency-Key` header — there is no Spend to protect, so there is nothing for
the key to do.

```bash
curl https://api.investorliftdata.com/v1/validate \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address": "1026 N Beckley Ave, Dallas, TX 75203"}'
```

## When something fails

Every error this API returns is an RFC 9457 Problem Detail with a stable `type` URI
that resolves to its own page in the [error reference](/errors) — the link inside the
error body you are holding is the documentation for it. Each page states what the
error costs and whether it is worth retrying. No automatic retry happens on our side,
ever: a Metered Call can consume a Credit before it fails, so retry is yours to
control, and your `Idempotency-Key` is what makes it safe.