/v1/partner/leadsAuthentication
Channel-scoped partner key.
A standard staff key is not interchangeable with a partner key. Call this endpoint from your server.
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 POST \
--url 'https://api.staging.facily.ai/v1/partner/leads' \
--header "Authorization: Bearer $FACILY_PARTNER_KEY" \
--header 'Content-Type: application/json' \
--data '{
"contact": {
"first_name": "string",
"email": "string",
"last_name": "string",
"phone": "string"
},
"facility_id": "00000000-0000-4000-8000-000000000001",
"partner_ref": "string",
"attribution": {
"landing_path": "string",
"referrer_host": "string",
"utm_campaign": "string",
"utm_content": "string",
"utm_medium": "string",
"utm_source": "string",
"utm_term": "string",
"visitor_id": "string"
},
"checkout_ref": "string",
"interest": {
"desired_move_in_date": "2026-10-29",
"expected_stay": "under_1_month",
"lead_source_id": "00000000-0000-4000-8000-000000000001",
"notes": "string",
"unit_group_id": "00000000-0000-4000-8000-000000000001",
"unit_id": "00000000-0000-4000-8000-000000000001"
},
"reservation": {
"expected_rate": 0,
"promotion_id": "00000000-0000-4000-8000-000000000001",
"unit_group_id": "00000000-0000-4000-8000-000000000001",
"unit_id": "00000000-0000-4000-8000-000000000001"
},
"sms_consent": {
"captured_at": "2026-10-29T12:00:00Z",
"disclosure_text": "string",
"page_url": "string",
"ip_address": "string"
},
"wait_list_unit_group_id": "00000000-0000-4000-8000-000000000001"
}'Request body
application/json · Required
attributionLeadAttribution | nullShow attribution schema
LeadAttribution | nullVariant 1: LeadAttribution
landing_pathstring | nullPath only.
Max length: 1024
Show landing_path schema
string | nullPath only.
Variant 1: string
stringVariant 2: null
nullreferrer_hoststring | nullHost only.
Max length: 255
Show referrer_host schema
string | nullHost only.
Variant 1: string
stringVariant 2: null
nullutm_campaignstring | nullMax length: 255
Show utm_campaign schema
string | nullVariant 1: string
stringVariant 2: null
nullutm_contentstring | nullMax length: 255
Show utm_content schema
string | nullVariant 1: string
stringVariant 2: null
nullutm_mediumstring | nullMax length: 255
Show utm_medium schema
string | nullVariant 1: string
stringVariant 2: null
nullutm_sourcestring | nullMax length: 255
Show utm_source schema
string | nullVariant 1: string
stringVariant 2: null
nullutm_termstring | nullMax length: 255
Show utm_term schema
string | nullVariant 1: string
stringVariant 2: null
nullvisitor_idstring | nullThe site's per-tab visitor id.
Max length: 64
Show visitor_id schema
string | nullThe site's per-tab visitor id.
Variant 1: string
stringVariant 2: null
nullVariant 2: null
nullcheckout_refstring | nullThe checkout this completes.
Min length: 1 · Max length: 100
Show checkout_ref schema
string | nullThe checkout this completes.
Variant 1: string
stringVariant 2: null
nullcontactPartnerContactRequestrequiredShow contact schema
emailstring | nullMax length: 255
Show email schema
string | nullVariant 1: string
stringVariant 2: null
nullfirst_namestringrequiredMin length: 1 · Max length: 100
last_namestring | nullMax length: 100
Show last_name schema
string | nullVariant 1: string
stringVariant 2: null
nullphonestring | nullMax length: 40
Show phone schema
string | nullVariant 1: string
stringVariant 2: null
nullfacility_idstringrequiredFormat: uuid
interestPartnerInterestRequestShow interest schema
desired_move_in_datestring | nullFormat: date
Show desired_move_in_date schema
string | nullVariant 1: string
stringVariant 2: null
nullexpected_staystring | nullValues: "under_1_month", "1_3_months", "4_6_months", "7_11_months", "over_12_months"
Show expected_stay schema
string | nullVariant 1: string
stringValues: "under_1_month", "1_3_months", "4_6_months", "7_11_months", "over_12_months"
Variant 2: null
nulllead_source_idstring | nullOne of the inventory's lead_sources.
Format: uuid
Show lead_source_id schema
string | nullOne of the inventory's lead_sources.
Variant 1: string
stringVariant 2: null
nullnotesstring | nullMax length: 2000
Show notes schema
string | nullVariant 1: string
stringVariant 2: null
nullunit_group_idstring | nullFormat: uuid
Show unit_group_id schema
string | nullVariant 1: string
stringVariant 2: null
nullunit_idstring | nullFormat: uuid
Show unit_id schema
string | nullVariant 1: string
stringVariant 2: null
nullpartner_refstringrequiredYour reference for this lead. Sending it again answers the same lead.
Min length: 1 · Max length: 100
reservationPartnerReservationRequest | nullShow reservation schema
PartnerReservationRequest | nullVariant 1: PartnerReservationRequest
expected_ratenumber | string | nullThe rate you showed, as a decimal string. Required with unit_group_id; with unit_id, a different current rate is refused as rate_changed.
Minimum: 0 · Pattern: ^(?!^[-+.]*$)[+-]?0*(?:\d{0,8}|(?=[\d.]{1,11}0*$)\d{0,8}\.\d{0,2}0*$)
Show expected_rate schema
number | string | nullThe rate you showed, as a decimal string. Required with unit_group_id; with unit_id, a different current rate is refused as rate_changed.
Variant 1: number
numberVariant 2: string
stringVariant 3: null
nullpromotion_idstring | nullOne of the group's promotion_ids. Left out: the first automatic promotion, if any.
Format: uuid
Show promotion_id schema
string | nullOne of the group's promotion_ids. Left out: the first automatic promotion, if any.
Variant 1: string
stringVariant 2: null
nullunit_group_idstring | nullFormat: uuid
Show unit_group_id schema
string | nullVariant 1: string
stringVariant 2: null
nullunit_idstring | nullFormat: uuid
Show unit_id schema
string | nullVariant 1: string
stringVariant 2: null
nullVariant 2: null
nullsms_consentPartnerConsentRequest | nullShow sms_consent schema
PartnerConsentRequest | nullVariant 1: PartnerConsentRequest
captured_atstringrequiredFormat: date-time
disclosure_textstringrequiredMin length: 1 · Max length: 2000
ip_addressstring | nullMax length: 45
Show ip_address schema
string | nullVariant 1: string
stringVariant 2: null
nullpage_urlstringrequiredMin length: 1 · Max length: 2048
Variant 2: null
nullwait_list_unit_group_idstring | nullJoin this group's wait list; never with reservation.
Format: uuid
Show wait_list_unit_group_id schema
string | nullJoin this group's wait list; never with reservation.
Variant 1: string
stringVariant 2: null
nullResponses
Expand a status to inspect its schema. Generated examples show structure and synthetic values.
201Successful Response
{
"data": {
"closed_at": "2026-10-29T12:00:00Z",
"created": false,
"facility_id": "00000000-0000-4000-8000-000000000001",
"id": "00000000-0000-4000-8000-000000000001",
"lead_number": "string",
"reservation": {
"expires_at": "2026-10-29T12:00:00Z",
"promotion_id": "00000000-0000-4000-8000-000000000001",
"quoted_rate": "<VALUE_MATCHING_PATTERN>",
"rate_basis": "string",
"reserved_at": "2026-10-29T12:00:00Z",
"unit_group_id": "00000000-0000-4000-8000-000000000001",
"unit_id": "00000000-0000-4000-8000-000000000001",
"unit_number": "string"
},
"status": "string",
"wait_list_unit_group_id": "00000000-0000-4000-8000-000000000001"
},
"meta": {
"request_id": "string"
}
}application/json
dataPartnerLeadResponserequiredShow data schema
closed_atstring | nullrequiredFormat: date-time
Show closed_at schema
string | nullVariant 1: string
stringVariant 2: null
nullcreatedbooleanrequiredTrue when this call created the lead; false for a repeat or a read.
facility_idstringrequiredFormat: uuid
idstringrequiredFormat: uuid
lead_numberstring | nullrequiredThe confirmation number to show the renter.
Show lead_number schema
string | nullThe confirmation number to show the renter.
Variant 1: string
stringVariant 2: null
nullreservationPartnerLeadReservationResponse | nullrequiredShow reservation schema
PartnerLeadReservationResponse | nullVariant 1: PartnerLeadReservationResponse
expires_atstring | nullrequiredWhen the hold lapses; null when it does not.
Format: date-time
Show expires_at schema
string | nullWhen the hold lapses; null when it does not.
Variant 1: string
Variant 2: null
promotion_idstring | nullrequiredFormat: uuid
Show promotion_id schema
string | nullVariant 1: string
Variant 2: null
quoted_ratestringrequiredPattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
rate_basisstringrequiredreserved_atstringrequiredFormat: date-time
unit_group_idstring | nullrequiredFormat: uuid
Show unit_group_id schema
string | nullVariant 1: string
Variant 2: null
unit_idstringrequiredFormat: uuid
unit_numberstringrequiredVariant 2: null
nullstatusstringrequiredinquiry, reserved, moved_in or cancelled.
wait_list_unit_group_idstring | nullrequiredFormat: uuid
Show wait_list_unit_group_id schema
string | nullVariant 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