> ## Documentation Index
> Fetch the complete documentation index at: https://developer.lofty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Listings

> Search active and sold MLS listings, retrieve published listings for a site feed, and associate properties with leads using the Lofty REST API.

Listings in Lofty represent MLS properties that agents and their clients can browse, search, and save. The API gives you two ways to access listing data — an agent/office listing search and a published listings feed — and lets you associate specific properties directly with a lead record.

## What listings represent

A listing in Lofty corresponds to a property available on the MLS. Each listing carries the property's address, price, physical attributes (beds, baths, square footage), MLS identifiers, and listing metadata such as days on site and listing type.

Lofty stores both **active** and **sold** listings. The listing search endpoint lets you query across both. The published listings endpoint returns the set of listings your team has published to a site feed in XML format, typically used to power public-facing property search pages.

## Two ways to access listings

### Published listings (V1)

`GET /v1.0/getPublishedListings` returns listings your team has published to a public site feed in XML format. This endpoint is intended for powering site search pages and content syndication rather than programmatic data processing.

```bash theme={null}
GET https://api.lofty.com/v1.0/getPublishedListings
```

### Listing search (V1)

For searching active and sold listings by agent, office, or MLS ID, use:

```bash theme={null}
GET https://api.lofty.com/v1.0/listing
```

<Tip>
  Use `GET /v1.0/listing` for integrations that need to look up listings by agent, office, or MLS ID. Use `GET /v1.0/getPublishedListings` only when you specifically need the XML site feed format.
</Tip>

## Key listing fields

| Field               | Type      | Description                         |
| ------------------- | --------- | ----------------------------------- |
| `listingId`         | string    | Lofty listing ID                    |
| `mlsListingId`      | string    | MLS listing ID (e.g., `ML82040728`) |
| `listingStreetName` | string    | Street address                      |
| `listingCity`       | string    | City                                |
| `listingState`      | string    | State abbreviation                  |
| `listingZipcode`    | string\[] | ZIP code(s)                         |
| `price`             | string    | Listing price                       |
| `beds`              | float     | Number of bedrooms                  |
| `baths`             | float     | Number of bathrooms                 |
| `sqft`              | float     | Square footage                      |
| `builtYear`         | int32     | Year built                          |
| `county`            | string    | County name                         |
| `area`              | string    | Area/submarket name                 |

## Associating a property with a lead

When a lead expresses interest in a specific property, you can attach that property to their record. This drives Lofty's listing alert and inquiry workflows.

```bash theme={null}
POST https://api.lofty.com/v1.0/leads/{leadId}/property
```

Use this endpoint to record a property a lead has viewed, inquired about, or favorited. You can also place a formal inquiry on a lead using `POST /v1.0/leads/{leadId}/inquiry`, which triggers the inquiry workflow within Lofty.

## Endpoint overview

| Method | Endpoint                        | Description                                 |
| ------ | ------------------------------- | ------------------------------------------- |
| `GET`  | `/v1.0/getPublishedListings`    | Get published listings as XML (site feed)   |
| `GET`  | `/v1.0/listing`                 | Search listings by agent, office, or MLS ID |
| `POST` | `/v1.0/leads/{leadId}/property` | Associate a property with a lead            |
| `POST` | `/v1.0/leads/{leadId}/inquiry`  | Place an inquiry on a lead                  |