Valuations API

The Valuations API gives you programmatic access to the Home Valuations (AHV) system. You can look up addresses, retrieve property assessment data, run AVM estimates (which consume credits), and fetch past valuation history for the approved website.

Access requirements

You need one of the following to use these endpoints:

• Pro or higher plan with an active Home Valuations add-on for the selected website, plus an API key with valuations:read and/or valuations:write scopes.
• Agency client product grant - your agency administrator enabled theahv product. After website verification, MLS approval, and AHV activation, create a site-bound key in your Developer dashboard with the required valuation scopes.

Authentication and site binding

All requests require a Bearer token and the X-EAI-Site-ID header. The site ID is a public binding token. It is not a secret, but it must be sent on every request. It is generated when a key is bound to a verified website.

Authorization: Bearer eai_<your-key>
X-EAI-Site-ID: site_0123456789abcdef

Credit costs

Running an AVM estimate via POST /api/v1/valuations draws from your account's monthly AHV credit allotment. Address lookup and property info requests do not consume credits.

Endpoints

GET /api/v1/valuations/usage

Read the active Home Valuations plan, total credits, credits used, credits remaining, and current credit period start for the approved website. Requires valuations:read. This request does not run an estimate or consume a credit.

{
  "data": {
    "plan": "ahv_basic",
    "credits_total": 100,
    "credits_used": 6,
    "credits_remaining": 94,
    "credit_period_start": "2026-10-01T00:00:00.000Z"
  }
}

GET /api/v1/valuations/address-search

Address autocomplete for the valuation flow. Returns address suggestions matching the partial query. No credit consumed.

Scope: valuations:read

GET /api/v1/valuations/address-search?q=123+Main+St

{
  "data": [
    { "full_address": "123 Main Street, Austin, TX 78701", "rupid": "PROPERTY_ID" },
    ...
  ]
}

GET /api/v1/valuations/property/:rupid

Fetches property details and assessment data for a known property by its Universal Property ID (RUPID). No credit consumed. Use this to prefill property details in your UI before running the full AVM estimate.

Scope: valuations:read

GET /api/v1/valuations/property/abc123rupid

{
  "data": {
    "address": { "street": "123 Main St", "city": "Austin", "state": "TX", "zip": "78701" },
    "beds": 3, "baths": 2, "sqft": 1850,
    "year_built": 1995, "lot_size_sqft": 6200,
    "assessment": { "tax_amount": "1200" }
  }
}

POST /api/v1/valuations

Runs a full AVM estimate. Consumes 1 credit per unique request. Requests with the same RUPID from the same website within the same minute are deduplicated. The cached result is returned and no additional credit is charged.

Scope: valuations:write

Request body

{
  "rupid": "abc123rupid",
  "contact": {
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "512-555-0100"
  }
}

Response

{
  "data": {
    "id": "val_xxx",
    "rupid": "abc123rupid",
    "address": "123 Main St, Austin, TX 78701",
    "property": { "beds": 3, "baths": 2, "sqft": 1850, ... },
    "valuations": {
      "current_value": 485000,
      "current_value_low_range": 451050,
      "current_value_high_range": 518950,
      "current_value_confidence_score": 0.87,
      "historical_values": [
        { "valuation": 462000, "valuation_date": "2026-01-01" },
        ...
      ]
    },
    "credits_remaining": 94,
    "created_at": "2026-09-07T15:00:00.000Z"
  }
}

Credit deduction rules

• 1 credit is consumed per unique rupid + valuationAccountId + minute combination.
• Submitting the same property twice within the same minute returns the cached result without charging a credit.
• A 402 is returned if no credits remain before the upstream call is made.
• Credit alerts are sent at 50%, 80%, and 100% usage. For agency-managed clients, alerts are routed to the agency partner administrator.

GET /api/v1/valuations

Lists past valuations for the approved website. No upstream call. It reads from the EasyAgentIDX database.

Scope: valuations:read

GET /api/v1/valuations?per_page=10&from=2026-09-01T00:00:00Z

{
  "data": [ { "id": "val_xxx", "address": "...", "valuation": { ... }, ... } ],
  "meta": { "total": 47, "page": 1, "per_page": 10, "total_pages": 5 }
}

GET /api/v1/valuations/:id

Fetches a single past valuation by its EasyAgentIDX ID. Includes full property details, historical values. Comparable sales are not currently supplied, so comparables is null.

Scope: valuations:read

GET /api/v1/valuations/val_xxx

{
  "data": {
    "id": "val_xxx",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "address": "123 Main St, Austin, TX 78701",
    "rupid": "abc123rupid",
    "property_details": { ... },
    "valuations": {
      "current_value": 485000,
      "low_range": 451050,
      "high_range": 518950,
      "confidence_score": 0.87,
      "historical_values": [ ... ],
      "comparables": null
    },
    "created_at": "2026-09-07T15:00:00.000Z"
  }
}

Error codes