Skip to content
FacilydevelopersDashboard
Build with Facily
DocsREST APIsCreate Partner Lead
Search the full API reference Esc to close

Create Partner Lead

Partner · REST API reference

Get support
POST/v1/partner/leads
Send an inquiry, a reservation or a wait-list sign-up. 201 when this call created the lead; sending the same partner_ref again answers that lead with 200 and changes nothing.

Authentication

Channel-scoped partner key.

A standard staff key is not interchangeable with a partner key. Call this endpoint from your server.

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/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"
}'
An example for building your request, not an executed call. Check required fields, allowed values, and environment configuration before sending.

Request body

application/json · Required

attributionLeadAttribution | null
Show attribution schema
LeadAttribution | null
Variant 1: LeadAttribution
landing_pathstring | null

Path only.

Max length: 1024

Show landing_path schema
string | null

Path only.

Variant 1: string
string
Variant 2: null
null
referrer_hoststring | null

Host only.

Max length: 255

Show referrer_host schema
string | null

Host only.

Variant 1: string
string
Variant 2: null
null
utm_campaignstring | null

Max length: 255

Show utm_campaign schema
string | null
Variant 1: string
string
Variant 2: null
null
utm_contentstring | null

Max length: 255

Show utm_content schema
string | null
Variant 1: string
string
Variant 2: null
null
utm_mediumstring | null

Max length: 255

Show utm_medium schema
string | null
Variant 1: string
string
Variant 2: null
null
utm_sourcestring | null

Max length: 255

Show utm_source schema
string | null
Variant 1: string
string
Variant 2: null
null
utm_termstring | null

Max length: 255

Show utm_term schema
string | null
Variant 1: string
string
Variant 2: null
null
visitor_idstring | null

The site's per-tab visitor id.

Max length: 64

Show visitor_id schema
string | null

The site's per-tab visitor id.

Variant 1: string
string
Variant 2: null
null
Variant 2: null
null
checkout_refstring | null

The checkout this completes.

Min length: 1 · Max length: 100

Show checkout_ref schema
string | null

The checkout this completes.

Variant 1: string
string
Variant 2: null
null
contactPartnerContactRequestrequired
Show contact schema
emailstring | null

Max length: 255

Show email schema
string | null
Variant 1: string
string
Variant 2: null
null
first_namestringrequired

Min length: 1 · Max length: 100

last_namestring | null

Max length: 100

Show last_name schema
string | null
Variant 1: string
string
Variant 2: null
null
phonestring | null

Max length: 40

Show phone schema
string | null
Variant 1: string
string
Variant 2: null
null
facility_idstringrequired

Format: uuid

interestPartnerInterestRequest
Show interest schema
desired_move_in_datestring | null

Format: date

Show desired_move_in_date schema
string | null
Variant 1: string
string
Variant 2: null
null
expected_staystring | null

Values: "under_1_month", "1_3_months", "4_6_months", "7_11_months", "over_12_months"

Show expected_stay schema
string | null
Variant 1: string
string

Values: "under_1_month", "1_3_months", "4_6_months", "7_11_months", "over_12_months"

Variant 2: null
null
lead_source_idstring | null

One of the inventory's lead_sources.

Format: uuid

Show lead_source_id schema
string | null

One of the inventory's lead_sources.

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

Max length: 2000

Show notes schema
string | null
Variant 1: string
string
Variant 2: null
null
unit_group_idstring | null

Format: uuid

Show unit_group_id schema
string | null
Variant 1: string
string
Variant 2: null
null
unit_idstring | null

Format: uuid

Show unit_id schema
string | null
Variant 1: string
string
Variant 2: null
null
partner_refstringrequired

Your reference for this lead. Sending it again answers the same lead.

Min length: 1 · Max length: 100

reservationPartnerReservationRequest | null
Show reservation schema
PartnerReservationRequest | null
Variant 1: PartnerReservationRequest
expected_ratenumber | string | null

The 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 | null

The 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
number
Variant 2: string
string
Variant 3: null
null
promotion_idstring | null

One of the group's promotion_ids. Left out: the first automatic promotion, if any.

Format: uuid

Show promotion_id schema
string | null

One of the group's promotion_ids. Left out: the first automatic promotion, if any.

Variant 1: string
string
Variant 2: null
null
unit_group_idstring | null

Format: uuid

Show unit_group_id schema
string | null
Variant 1: string
string
Variant 2: null
null
unit_idstring | null

Format: uuid

Show unit_id schema
string | null
Variant 1: string
string
Variant 2: null
null
Variant 2: null
null
sms_consentPartnerConsentRequest | null
Show sms_consent schema
PartnerConsentRequest | null
Variant 1: PartnerConsentRequest
captured_atstringrequired

Format: date-time

disclosure_textstringrequired

Min length: 1 · Max length: 2000

ip_addressstring | null

Max length: 45

Show ip_address schema
string | null
Variant 1: string
string
Variant 2: null
null
page_urlstringrequired

Min length: 1 · Max length: 2048

Variant 2: null
null
wait_list_unit_group_idstring | null

Join this group's wait list; never with reservation.

Format: uuid

Show wait_list_unit_group_id schema
string | null

Join this group's wait list; never with reservation.

Variant 1: string
string
Variant 2: null
null

Responses

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

201Successful Response
JSON · generated example
{
  "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

dataPartnerLeadResponserequired
Show data schema
closed_atstring | nullrequired

Format: date-time

Show closed_at schema
string | null
Variant 1: string
string
Variant 2: null
null
createdbooleanrequired

True when this call created the lead; false for a repeat or a read.

facility_idstringrequired

Format: uuid

idstringrequired

Format: uuid

lead_numberstring | nullrequired

The confirmation number to show the renter.

Show lead_number schema
string | null

The confirmation number to show the renter.

Variant 1: string
string
Variant 2: null
null
reservationPartnerLeadReservationResponse | nullrequired
Show reservation schema
PartnerLeadReservationResponse | null
Variant 1: PartnerLeadReservationResponse
expires_atstring | nullrequired

When the hold lapses; null when it does not.

Format: date-time

Show expires_at schema
string | null

When the hold lapses; null when it does not.

Variant 1: string
Variant 2: null
promotion_idstring | nullrequired

Format: uuid

Show promotion_id schema
string | null
Variant 1: string
Variant 2: null
quoted_ratestringrequired

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

rate_basisstringrequired
reserved_atstringrequired

Format: date-time

unit_group_idstring | nullrequired

Format: uuid

Show unit_group_id schema
string | null
Variant 1: string
Variant 2: null
unit_idstringrequired

Format: uuid

unit_numberstringrequired
Variant 2: null
null
statusstringrequired

inquiry, reserved, moved_in or cancelled.

wait_list_unit_group_idstring | nullrequired

Format: uuid

Show wait_list_unit_group_id schema
string | null
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 partner operations
Build something that works beautifully.

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

Create Partner Lead | Facily Developers