Skip to the documentation
liviamatchAPI

Livia Match API

Run searches, read their results and administer your organization from your own server.

Already have an API key?

Start a match, poll the same URL for its status, then read the shortlist. The same path shows up in Searches and Clients.

POST /api/v1/searches/{searchId}/matches

Then GET /api/v1/matches/{matchId} until status is complete.

Open the quickstartPolling contractGet a key
POST /api/v1/search

Results stay on the execution only. Nothing appears in Searches or Clients.

Headless search

A search is what a client needs. A run of it ("Search now") goes against live listings and returns its results: the homes that fit, each with a score and its reasons. The API does what the app does, from your own server. The product path is /api/v1/searches. Older names (briefs, matches, shortlists) still answer on their old paths: see old words and new.

Kick off → poll → results on one resource. POST starts the work and answers at once with status and a Location. GET that same URL until status is terminal; when it is, the results are on the same payload. No second endpoint. Or name a callback URL and be told when it ends. Prefer the product journey (/searches → /matches) when results should appear in Searches and Clients. Use headless POST /search only when your server wants a shortlist back and has nothing to show in the app.

Where to begin

For AI agents

Every endpoint, field, allowed value and error, as markdown a model can read.

docs.mdopenapi.json

The words the API uses

In the appIn the APIWhat it is
Client/clientsThe person you work for. Give them access before you share.
Search/searches (or headless search)What the client needs. Prefer /searches when you will share; headless search makes executions with nothing in the app.
Run/runsA search run against homes: status, then results on the same GET. A headless execution is not one of these.
Resultsrun.resultsThe homes that fit, in the order you curate.
Share/runs/{id}/sharesResults shared with a client: email them, stop it.
Runs a monththe allowance and limitsEvery run counts one against the org's month and the person's own limit.

To walk the whole path with a key, see From a client to shared results. For the poll loop alone, see Runs and polling.

Conventions

  • JSON over HTTPS, UTF-8. Every path starts with /api/v1. Send Content-Type: application/json with a body.
  • A success is { "data": ... }, and a list adds "links": { "next": ... }. A failure is { "error": { "code", "digest" } }; a 400 adds issues.
  • Ids are UUIDs, timestamps are ISO 8601 in UTC, and fields are camelCase. An unknown value is null, never a placeholder.
  • Unknown fields in a body are refused, so a typo fails loudly.
  • Every answer carries X-Request-Id, the same value as an error's digest. Quote it when you write to us.
  • A key marked Run for another account may send Livia-Account (a realtor's email or user id). The work is saved to that account. Omit the header and the key acts as its maker. A signed-in browser ignores the header.

Which environment

The examples use https://liviamatch.com. A preview or lab deployment has its own base URL, keys and data; a key from one does not open another.