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

# Listings and new homes

> Keep Signal's copy of your listings, developments and units up to date.

Your system is the record. Signal stores what you send, never edits it, and **never messages anyone because of a
change**. Signal shows these records read-only to the agency's staff.

| Call | What |
| - | - |
| `POST /listings` | One resale or letting listing |
| `POST /developments` | A new-homes development and its house types |
| `POST /units` | One unit in a development: send its development first |
| `POST /reservations` | A unit's reservation and its buyer: send the unit first |

Send each record again whenever it changes, and **send the whole record each time**: a field you leave out is cleared.
References travel in the body, so slashes are fine. A development's `house_types` is the full list: a type you leave
out is removed, and renaming one is a removal plus an addition.

## Order

Every record carries `updated_at`: when it last changed in your system. An update older than the one we hold is
ignored, and the response says `"applied": false`. So retries and out-of-order deliveries are safe.

## Listings

`portal_ids` (your Daft and MyHome ids) let Signal match a portal enquiry to your listing, so events about it carry
your `ref`. A listing that leaves `available` stops Signal starting new conversations about it, and stops it chasing
people who haven't replied. People mid-conversation are flagged to the negotiator instead.

## Units

A unit's `ref` is your id for it; `plot_number` is what buyers see ("Plot 7") and is unique within the development.
A unit's `status` is what Signal's new-homes conversation offers: once it leaves `available`, it isn't offered. To take
a unit off sale, send `unreleased`.

## Reservations

| `buyer` in the response | Meaning |
| - | - |
| `matched` | Someone Signal already knows |
| `created` | New to Signal: recorded, never messaged automatically |
| `not_matched` | No `contact_id` we know and no usable phone number, so only the unit's status was updated |

Each reservation has its own `ref`: a new buyer for the same unit is a new reservation. We find the lead buyer by
`contact_id`, then your buyer `external_id`, then phone. A reservation also sets the unit's status (`fell_through` puts
it back to `available`), so you needn't send the unit as well.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.