/v1/leads/{lead_id}Authentication
Bearer API key or Facily session, subject to permissions and facility scope.
Authentication and scopeRequest 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 --request PATCH \
--url 'https://api.staging.facily.ai/v1/leads/<LEAD_ID>' \
--header "Authorization: Bearer $FACILY_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"desired_move_in_date": "2026-10-29",
"email": "string",
"expected_stay": "string",
"first_name": "string",
"interested_unit_group_id": "00000000-0000-4000-8000-000000000001",
"interested_unit_id": "00000000-0000-4000-8000-000000000001",
"kind": "string",
"last_name": "string",
"lead_source_id": "00000000-0000-4000-8000-000000000001",
"notes": "string",
"phone": "string",
"tenant_id": "00000000-0000-4000-8000-000000000001"
}'Parameters
lead_idpath · stringrequiredFormat: uuid
Request body
application/json · Required
desired_move_in_datestring | nullBusiness date the prospect wants to move in.
Format: date
Show desired_move_in_date schema
string | nullBusiness date the prospect wants to move in.
Variant 1: string
stringVariant 2: null
nullemailstring | nullContact email address; null clears it.
Max length: 255
Show email schema
string | nullContact email address; null clears it.
Variant 1: string
stringVariant 2: null
nullexpected_staystring | nullHow long the prospect expects to stay: under_1_month, 1_3_months, 4_6_months, 7_11_months or over_12_months.
Show expected_stay schema
string | nullHow long the prospect expects to stay: under_1_month, 1_3_months, 4_6_months, 7_11_months or over_12_months.
Variant 1: string
stringVariant 2: null
nullfirst_namestring | nullGiven name of the prospective tenant; cannot be null.
Min length: 1 · Max length: 100
Show first_name schema
string | nullGiven name of the prospective tenant; cannot be null.
Variant 1: string
stringVariant 2: null
nullinterested_unit_group_idstring | nullThe unit group the prospect asked about.
Format: uuid
Show interested_unit_group_id schema
string | nullThe unit group the prospect asked about.
Variant 1: string
stringVariant 2: null
nullinterested_unit_idstring | nullA specific unit the prospect asked about; it must be in the chosen unit group.
Format: uuid
Show interested_unit_id schema
string | nullA specific unit the prospect asked about; it must be in the chosen unit group.
Variant 1: string
stringVariant 2: null
nullkindstring | nullHow the enquiry was made: walk_in, phone_call, internet, email, sms or other.
Show kind schema
string | nullHow the enquiry was made: walk_in, phone_call, internet, email, sms or other.
Variant 1: string
stringVariant 2: null
nulllast_namestring | nullFamily name; null clears it.
Max length: 100
Show last_name schema
string | nullFamily name; null clears it.
Variant 1: string
stringVariant 2: null
nulllead_source_idstring | nullWhere the enquiry came from; null clears it.
Format: uuid
Show lead_source_id schema
string | nullWhere the enquiry came from; null clears it.
Variant 1: string
stringVariant 2: null
nullnotesstring | nullFree-text notes about the enquiry.
Max length: 5000
Show notes schema
string | nullFree-text notes about the enquiry.
Variant 1: string
stringVariant 2: null
nullphonestring | nullContact telephone number; stored in international form, null clears it.
Max length: 20
Show phone schema
string | nullContact telephone number; stored in international form, null clears it.
Variant 1: string
stringVariant 2: null
nulltenant_idstring | nullAn existing tenant this enquiry belongs to.
Format: uuid
Show tenant_id schema
string | nullAn existing tenant this enquiry belongs to.
Variant 1: string
stringVariant 2: null
nullResponses
Expand a status to inspect its schema. Generated examples show structure and synthetic values.
200Successful Response
{
"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
dataLeadDetailResponserequiredA lead, with the Rental Review warnings its contact details raise.
Show data schema
assigned_tostring | nullThe staff member responsible for following up.
Format: uuid
Show assigned_to schema
string | nullThe staff member responsible for following up.
Variant 1: string
stringVariant 2: null
nullattributionobjectWhere 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 | nullThe channel the enquiry arrived through.
Format: uuid
Show channel_id schema
string | nullThe channel the enquiry arrived through.
Variant 1: string
stringVariant 2: null
nullclose_notestring | nullThe note written when the lead was closed.
Show close_note schema
string | nullThe note written when the lead was closed.
Variant 1: string
stringVariant 2: null
nullclose_reason_idstring | nullThe reason the lead was closed.
Format: uuid
Show close_reason_id schema
string | nullThe reason the lead was closed.
Variant 1: string
stringVariant 2: null
nullconverted_atstring | nullWhen the lead became a tenant.
Format: date-time
Show converted_at schema
string | nullWhen the lead became a tenant.
Variant 1: string
stringVariant 2: null
nullconverted_lease_idstring | nullThe lease created on conversion.
Format: uuid
Show converted_lease_id schema
string | nullThe lease created on conversion.
Variant 1: string
stringVariant 2: null
nullconverted_tenant_idstring | nullThe tenant record created on conversion.
Format: uuid
Show converted_tenant_id schema
string | nullThe tenant record created on conversion.
Variant 1: string
stringVariant 2: null
nullcreated_atstringrequiredWhen the lead was created.
Format: date-time
creator_typestring | nullWho created the lead: staff, renter, partner, email or unknown.
Show creator_type schema
string | nullWho created the lead: staff, renter, partner, email or unknown.
Variant 1: string
stringVariant 2: null
nulldesired_move_in_datestring | nullBusiness date the prospect wants to move in.
Format: date
Show desired_move_in_date schema
string | nullBusiness date the prospect wants to move in.
Variant 1: string
stringVariant 2: null
nullemailstring | nullContact email address.
Show email schema
string | nullContact email address.
Variant 1: string
stringVariant 2: null
nullemail_declinedbooleanTrue when the prospect asked not to be emailed. An email staff send still goes.
Default: false
expected_staystring | nullHow long the prospect expects to stay.
Show expected_stay schema
string | nullHow long the prospect expects to stay.
Variant 1: string
stringVariant 2: null
nullfacility_idstringrequiredThe facility the enquiry was made at.
Format: uuid
first_contacted_atstring | nullWhen the prospect was first contacted.
Format: date-time
Show first_contacted_at schema
string | nullWhen the prospect was first contacted.
Variant 1: string
stringVariant 2: null
nullfirst_namestringrequiredGiven name of the prospective tenant.
follow_up_datestring | nullBusiness date the next follow-up is due.
Format: date
Show follow_up_date schema
string | nullBusiness date the next follow-up is due.
Variant 1: string
stringVariant 2: null
nullidstringrequiredUnique identifier for this lead.
Format: uuid
interested_unit_group_idstring | nullThe unit group the prospect enquired about.
Format: uuid
Show interested_unit_group_id schema
string | nullThe unit group the prospect enquired about.
Variant 1: string
stringVariant 2: null
nullinterested_unit_idstring | nullA specific unit the prospect enquired about or reserved.
Format: uuid
Show interested_unit_id schema
string | nullA specific unit the prospect enquired about or reserved.
Variant 1: string
stringVariant 2: null
nullinterested_unit_type_idstring | nullThe unit type the prospect enquired about.
Format: uuid
Show interested_unit_type_id schema
string | nullThe unit type the prospect enquired about.
Variant 1: string
stringVariant 2: null
nullkindstring | nullHow the enquiry was made: walk_in, phone_call, internet, email, sms or other.
Show kind schema
string | nullHow the enquiry was made: walk_in, phone_call, internet, email, sms or other.
Variant 1: string
stringVariant 2: null
nulllast_contacted_atstring | nullWhen the prospect was last contacted.
Format: date-time
Show last_contacted_at schema
string | nullWhen the prospect was last contacted.
Variant 1: string
stringVariant 2: null
nulllast_namestring | nullFamily name of the prospective tenant.
Show last_name schema
string | nullFamily name of the prospective tenant.
Variant 1: string
stringVariant 2: null
nulllead_numberstring | nullThe lead's number, unique at its facility.
Show lead_number schema
string | nullThe lead's number, unique at its facility.
Variant 1: string
stringVariant 2: null
nulllead_source_idstring | nullWhere the enquiry came from.
Format: uuid
Show lead_source_id schema
string | nullWhere the enquiry came from.
Variant 1: string
stringVariant 2: null
nulllost_atstring | nullWhen the lead was closed.
Format: date-time
Show lost_at schema
string | nullWhen the lead was closed.
Variant 1: string
stringVariant 2: null
nulllost_reasonstring | nullWhy the lead was lost, as a word.
Show lost_reason schema
string | nullWhy the lead was lost, as a word.
Variant 1: string
stringVariant 2: null
nullnotesstring | nullFree-text notes about the enquiry.
Show notes schema
string | nullFree-text notes about the enquiry.
Variant 1: string
stringVariant 2: null
nulloriginationstring | nullHow the lead began, for example an inquiry or a reservation.
Show origination schema
string | nullHow the lead began, for example an inquiry or a reservation.
Variant 1: string
stringVariant 2: null
nullpartner_refstring | nullThe referring partner's reference, when there is one.
Show partner_ref schema
string | nullThe referring partner's reference, when there is one.
Variant 1: string
stringVariant 2: null
nullphonestring | nullContact telephone number.
Show phone schema
string | nullContact telephone number.
Variant 1: string
stringVariant 2: null
nullquoted_promotion_idstring | nullThe promotion quoted with the rate.
Format: uuid
Show quoted_promotion_id schema
string | nullThe promotion quoted with the rate.
Variant 1: string
stringVariant 2: null
nullquoted_ratestring | nullRate quoted to the prospect.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
Show quoted_rate schema
string | nullRate quoted to the prospect.
Variant 1: string
stringVariant 2: null
nullquoted_rate_basisstring | nullWhat the quoted rate was based on.
Show quoted_rate_basis schema
string | nullWhat the quoted rate was based on.
Variant 1: string
stringVariant 2: null
nullrental_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_namestringrequiredThe facility where the matching person is flagged.
flagged_onstringrequiredThe date they were first flagged, at the facility that flagged them.
Format: date
matched_onstring[]requiredWhich of the lead's email, phone and name matched, in that order.
Show matched_on schema
stringreasonstringrequiredWhy they were flagged: delinquency, fraud, damage, conduct or other.
Values: "delinquency", "fraud", "damage", "conduct", "other"
reservation_expires_atstring | nullWhen an unconverted reservation lapses and the unit is released.
Format: date-time
Show reservation_expires_at schema
string | nullWhen an unconverted reservation lapses and the unit is released.
Variant 1: string
stringVariant 2: null
nullreservation_fee_heldstringThe 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_paidbooleanrequiredTrue when a reservation fee has been taken to hold a unit.
reserved_atstring | nullWhen the unit was reserved.
Format: date-time
Show reserved_at schema
string | nullWhen the unit was reserved.
Variant 1: string
stringVariant 2: null
nullsms_opted_in_atstring | nullWhen the prospect agreed to text messages; empty when they have not.
Format: date-time
Show sms_opted_in_at schema
string | nullWhen the prospect agreed to text messages; empty when they have not.
Variant 1: string
stringVariant 2: null
nullsms_opted_outbooleanTrue when the prospect asked to stop texts; no text reaches them until they agree again.
Default: false
sourcestring | nullThe source as a word, for leads that predate source records.
Show source schema
string | nullThe source as a word, for leads that predate source records.
Variant 1: string
stringVariant 2: null
nullsource_detailstring | nullFiner attribution within source, such as the specific campaign.
Show source_detail schema
string | nullFiner attribution within source, such as the specific campaign.
Variant 1: string
stringVariant 2: null
nullstatusstringrequiredOne of inquiry, reserved, moved_in or cancelled.
tenant_idstring | nullAn existing tenant this enquiry belongs to.
Format: uuid
Show tenant_id schema
string | nullAn existing tenant this enquiry belongs to.
Variant 1: string
stringVariant 2: null
nullupdated_atstringrequiredWhen the lead was last modified.
Format: date-time
wait_list_unit_group_idstring | nullThe unit group the prospect is waiting for.
Format: uuid
Show wait_list_unit_group_id schema
string | nullThe unit group the prospect is waiting for.
Variant 1: string
stringVariant 2: null
nullwait_listed_atstring | nullWhen the prospect joined the wait list.
Format: date-time
Show wait_listed_at schema
string | nullWhen the prospect joined the wait list.
Variant 1: string
stringVariant 2: null
nullmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired400Validation error
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired401Unauthenticated
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired403Permission denied
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired404Not found
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired409Business logic error
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired503Temporary failure
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired