Skip to content
FacilydevelopersDashboard
Build with Facily
DocsREST APIsAdd Lead To Wait List
Search the full API reference Esc to close

Add Lead To Wait List

Leads · REST API reference

Get support
POST/v1/leads/{lead_id}/wait-list
Put an inquiry on the wait list for a unit group, or move it to another group.

Authentication

Bearer API key or Facily session, subject to permissions and facility scope.

Authentication and scope

Request example

Replace bracketed path values with real IDs from your environment. The body, where shown, is generated from the schema and uses illustrative values.

cURL
curl --request POST \
  --url 'https://api.staging.facily.ai/v1/leads/<LEAD_ID>/wait-list' \
  --header "Authorization: Bearer $FACILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "unit_group_id": "00000000-0000-4000-8000-000000000001"
}'
An example for building your request, not an executed call. Check required fields, allowed values, and environment configuration before sending.

Parameters

lead_idpath · stringrequired

Format: uuid

Request body

application/json · Required

unit_group_idstringrequired

The unit group the prospect is waiting for.

Format: uuid

Responses

Expand a status to inspect its schema. Generated examples show structure and synthetic values.

200Successful Response
JSON · generated example
{
  "data": {
    "created_at": "2026-10-29T12:00:00Z",
    "facility_id": "00000000-0000-4000-8000-000000000001",
    "first_name": "string",
    "id": "00000000-0000-4000-8000-000000000001",
    "reservation_fee_paid": false,
    "status": "string",
    "updated_at": "2026-10-29T12:00:00Z",
    "assigned_to": "00000000-0000-4000-8000-000000000001",
    "attribution": {},
    "channel_id": "00000000-0000-4000-8000-000000000001",
    "close_note": "string",
    "close_reason_id": "00000000-0000-4000-8000-000000000001"
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

dataLeadDetailResponserequired

A lead, with the Rental Review warnings its contact details raise.

Show data schema
assigned_tostring | null

The staff member responsible for following up.

Format: uuid

Show assigned_to schema
string | null

The staff member responsible for following up.

Variant 1: string
string
Variant 2: null
null
attributionobject

Where a web lead came from: visitor_id, utm_source, utm_medium, utm_campaign, utm_term, utm_content, referrer_host and landing_path, each only when the site sent it.

channel_idstring | null

The channel the enquiry arrived through.

Format: uuid

Show channel_id schema
string | null

The channel the enquiry arrived through.

Variant 1: string
string
Variant 2: null
null
close_notestring | null

The note written when the lead was closed.

Show close_note schema
string | null

The note written when the lead was closed.

Variant 1: string
string
Variant 2: null
null
close_reason_idstring | null

The reason the lead was closed.

Format: uuid

Show close_reason_id schema
string | null

The reason the lead was closed.

Variant 1: string
string
Variant 2: null
null
converted_atstring | null

When the lead became a tenant.

Format: date-time

Show converted_at schema
string | null

When the lead became a tenant.

Variant 1: string
string
Variant 2: null
null
converted_lease_idstring | null

The lease created on conversion.

Format: uuid

Show converted_lease_id schema
string | null

The lease created on conversion.

Variant 1: string
string
Variant 2: null
null
converted_tenant_idstring | null

The tenant record created on conversion.

Format: uuid

Show converted_tenant_id schema
string | null

The tenant record created on conversion.

Variant 1: string
string
Variant 2: null
null
created_atstringrequired

When the lead was created.

Format: date-time

creator_typestring | null

Who created the lead: staff, renter, partner, email or unknown.

Show creator_type schema
string | null

Who created the lead: staff, renter, partner, email or unknown.

Variant 1: string
string
Variant 2: null
null
desired_move_in_datestring | null

Business date the prospect wants to move in.

Format: date

Show desired_move_in_date schema
string | null

Business date the prospect wants to move in.

Variant 1: string
string
Variant 2: null
null
emailstring | null

Contact email address.

Show email schema
string | null

Contact email address.

Variant 1: string
string
Variant 2: null
null
email_declinedboolean

True when the prospect asked not to be emailed. An email staff send still goes.

Default: false

expected_staystring | null

How long the prospect expects to stay.

Show expected_stay schema
string | null

How long the prospect expects to stay.

Variant 1: string
string
Variant 2: null
null
facility_idstringrequired

The facility the enquiry was made at.

Format: uuid

first_contacted_atstring | null

When the prospect was first contacted.

Format: date-time

Show first_contacted_at schema
string | null

When the prospect was first contacted.

Variant 1: string
string
Variant 2: null
null
first_namestringrequired

Given name of the prospective tenant.

follow_up_datestring | null

Business date the next follow-up is due.

Format: date

Show follow_up_date schema
string | null

Business date the next follow-up is due.

Variant 1: string
string
Variant 2: null
null
idstringrequired

Unique identifier for this lead.

Format: uuid

interested_unit_group_idstring | null

The unit group the prospect enquired about.

Format: uuid

Show interested_unit_group_id schema
string | null

The unit group the prospect enquired about.

Variant 1: string
string
Variant 2: null
null
interested_unit_idstring | null

A specific unit the prospect enquired about or reserved.

Format: uuid

Show interested_unit_id schema
string | null

A specific unit the prospect enquired about or reserved.

Variant 1: string
string
Variant 2: null
null
interested_unit_type_idstring | null

The unit type the prospect enquired about.

Format: uuid

Show interested_unit_type_id schema
string | null

The unit type the prospect enquired about.

Variant 1: string
string
Variant 2: null
null
kindstring | null

How the enquiry was made: walk_in, phone_call, internet, email, sms or other.

Show kind schema
string | null

How the enquiry was made: walk_in, phone_call, internet, email, sms or other.

Variant 1: string
string
Variant 2: null
null
last_contacted_atstring | null

When the prospect was last contacted.

Format: date-time

Show last_contacted_at schema
string | null

When the prospect was last contacted.

Variant 1: string
string
Variant 2: null
null
last_namestring | null

Family name of the prospective tenant.

Show last_name schema
string | null

Family name of the prospective tenant.

Variant 1: string
string
Variant 2: null
null
lead_numberstring | null

The lead's number, unique at its facility.

Show lead_number schema
string | null

The lead's number, unique at its facility.

Variant 1: string
string
Variant 2: null
null
lead_source_idstring | null

Where the enquiry came from.

Format: uuid

Show lead_source_id schema
string | null

Where the enquiry came from.

Variant 1: string
string
Variant 2: null
null
lost_atstring | null

When the lead was closed.

Format: date-time

Show lost_at schema
string | null

When the lead was closed.

Variant 1: string
string
Variant 2: null
null
lost_reasonstring | null

Why the lead was lost, as a word.

Show lost_reason schema
string | null

Why the lead was lost, as a word.

Variant 1: string
string
Variant 2: null
null
notesstring | null

Free-text notes about the enquiry.

Show notes schema
string | null

Free-text notes about the enquiry.

Variant 1: string
string
Variant 2: null
null
originationstring | null

How the lead began, for example an inquiry or a reservation.

Show origination schema
string | null

How the lead began, for example an inquiry or a reservation.

Variant 1: string
string
Variant 2: null
null
partner_refstring | null

The referring partner's reference, when there is one.

Show partner_ref schema
string | null

The referring partner's reference, when there is one.

Variant 1: string
string
Variant 2: null
null
phonestring | null

Contact telephone number.

Show phone schema
string | null

Contact telephone number.

Variant 1: string
string
Variant 2: null
null
quoted_promotion_idstring | null

The promotion quoted with the rate.

Format: uuid

Show quoted_promotion_id schema
string | null

The promotion quoted with the rate.

Variant 1: string
string
Variant 2: null
null
quoted_ratestring | null

Rate quoted to the prospect.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

Show quoted_rate schema
string | null

Rate quoted to the prospect.

Variant 1: string
string
Variant 2: null
null
quoted_rate_basisstring | null

What the quoted rate was based on.

Show quoted_rate_basis schema
string | null

What the quoted rate was based on.

Variant 1: string
string
Variant 2: null
null
rental_review_warningsRentalReviewWarningResponse[]

People flagged as do not rent at any facility of the organization whom this lead's email, phone or name matches; empty when none do. A warning never names the tenant, and it never blocks anything.

Show rental_review_warnings schema
facility_namestringrequired

The facility where the matching person is flagged.

flagged_onstringrequired

The date they were first flagged, at the facility that flagged them.

Format: date

matched_onstring[]required

Which of the lead's email, phone and name matched, in that order.

Show matched_on schema
string
reasonstringrequired

Why they were flagged: delinquency, fraud, damage, conduct or other.

Values: "delinquency", "fraud", "damage", "conduct", "other"

reservation_expires_atstring | null

When an unconverted reservation lapses and the unit is released.

Format: date-time

Show reservation_expires_at schema
string | null

When an unconverted reservation lapses and the unit is released.

Variant 1: string
string
Variant 2: null
null
reservation_fee_heldstring

The reservation fee the lead has paid and Facily holds now: a move-in for the lead counts it as paid, so what is due at move-in is its total less this. 0.00 when none is held.

Default: "0.00" · Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

reservation_fee_paidbooleanrequired

True when a reservation fee has been taken to hold a unit.

reserved_atstring | null

When the unit was reserved.

Format: date-time

Show reserved_at schema
string | null

When the unit was reserved.

Variant 1: string
string
Variant 2: null
null
sms_opted_in_atstring | null

When the prospect agreed to text messages; empty when they have not.

Format: date-time

Show sms_opted_in_at schema
string | null

When the prospect agreed to text messages; empty when they have not.

Variant 1: string
string
Variant 2: null
null
sms_opted_outboolean

True when the prospect asked to stop texts; no text reaches them until they agree again.

Default: false

sourcestring | null

The source as a word, for leads that predate source records.

Show source schema
string | null

The source as a word, for leads that predate source records.

Variant 1: string
string
Variant 2: null
null
source_detailstring | null

Finer attribution within source, such as the specific campaign.

Show source_detail schema
string | null

Finer attribution within source, such as the specific campaign.

Variant 1: string
string
Variant 2: null
null
statusstringrequired

One of inquiry, reserved, moved_in or cancelled.

tenant_idstring | null

An existing tenant this enquiry belongs to.

Format: uuid

Show tenant_id schema
string | null

An existing tenant this enquiry belongs to.

Variant 1: string
string
Variant 2: null
null
updated_atstringrequired

When the lead was last modified.

Format: date-time

wait_list_unit_group_idstring | null

The unit group the prospect is waiting for.

Format: uuid

Show wait_list_unit_group_id schema
string | null

The unit group the prospect is waiting for.

Variant 1: string
string
Variant 2: null
null
wait_listed_atstring | null

When the prospect joined the wait list.

Format: date-time

Show wait_listed_at schema
string | null

When the prospect joined the wait list.

Variant 1: string
string
Variant 2: null
null
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
400Validation error
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
401Unauthenticated
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
403Permission denied
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
404Not found
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
409Business logic error
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
503Temporary failure
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
Continue exploringAll leads operations
Build something that works beautifully.

Facily API · Contract v1.200 · Reviewed October 29, 2026

Add Lead To Wait List | Facily Developers