Skip to main content
POST
Send a reservation

Authorizations

Authorization
string
header
required

The agency's secret key, sent as Authorization: Bearer <key>. One key per agency.

Body

application/json

A unit's reservation and its lead buyer.

development_ref
string
required

Send the development first. An unknown one is a 422.

Required string length: 1 - 128
unit_ref
string
required

Send the unit first. An unknown one is a 422.

Required string length: 1 - 128
ref
string
required

Your id for this reservation or sale. A new buyer for the same unit is a new reservation with a new ref.

Required string length: 1 - 128
status
enum<string>
required

reserved: a booking deposit is paid. exchanged: contracts exchanged (signed in Ireland). completed: the sale has closed. fell_through: the reservation ended without a sale. A reservation call also sets the unit's status: reserved, exchanged and completed set the same status, fell_through sets it back to available. You needn't send the unit as well, and a unit call older than the reservation won't undo it.

Available options:
reserved,
exchanged,
completed,
fell_through
buyer
Contact · object
required

The lead buyer. We find them by contact_id, then your buyer external_id, then phone. With none of those usable, only the unit's status is updated.

reserved_at
string<date-time>
required

When the reservation was made.

updated_at
string<date-time>
required

When it last changed in your system (if you don't track that, send the time of the call). An update older than the one we hold is ignored; the same time again is applied, so retries are safe.

contact_id
string<uuid> | null

Signal's id for the buyer, if you have it.

exchanged_at
string<date-time> | null

When it happened, once it has.

completed_at
string<date-time> | null

When it happened, once it has.

fell_through_at
string<date-time> | null

When it happened, once it has.

fell_through_reason
string | null

Why it ended, if you know. Cut at 500 characters.

Response

Updated, or ignored because we already held a newer version (see applied).

What Signal did with a reservation you sent.

development_ref
string
required

Your development reference.

unit_ref
string
required

Your unit reference.

ref
string
required

Your reservation reference.

status
enum<string>
required

The reservation's status as recorded.

Available options:
reserved,
exchanged,
completed,
fell_through
buyer
enum<string>
required

matched: someone Signal 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.

Available options:
matched,
created,
not_matched
applied
boolean
required

False when we already held a newer version (by updated_at), so this one was ignored.

contact_id
string<uuid> | null

Signal's id for the buyer, when matched or created.