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

Create Rate Schedule

Leases · REST API reference

Get support
POST/v1/leases/{lease_id}/rate-schedules

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/leases/<LEASE_ID>/rate-schedules' \
  --header "Authorization: Bearer $FACILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "effective_date": "2026-10-29",
  "new_rate": 0,
  "ignore_rules": [
    "move_in"
  ],
  "notice_required_days": 0,
  "reason": "string"
}'
An example for building your request, not an executed call. Check required fields, allowed values, and environment configuration before sending.

Parameters

lease_idpath · stringrequired

Format: uuid

Request body

application/json · Required

effective_datestringrequired

Format: date

ignore_rulesstring[]

Default raise rules to skip for this raise: the months-since-move-in and months-since-last-increase minimums.

Show ignore_rules schema
string

Values: "move_in", "last_increase"

new_ratenumber | stringrequired

Pattern: ^(?!^[-+.]*$)[+-]?0*(?:\d{0,8}|(?=[\d.]{1,11}0*$)\d{0,8}\.\d{0,2}0*$)

Show new_rate schema
number | string
Variant 1: number
number
Variant 2: string
string
notice_required_daysinteger | null

Advance notice in days. Defaults to the facility's rate_change_notice_days and may only lengthen it.

Minimum: 0 · Maximum: 365

Show notice_required_days schema
integer | null

Advance notice in days. Defaults to the facility's rate_change_notice_days and may only lengthen it.

Variant 1: integer
integer
Variant 2: null
null
reasonstring | null

Why the rent is changing. Required for an adjustment; optional for an increase, where it is kept on the rate change.

Max length: 255

Show reason schema
string | null

Why the rent is changing. Required for an adjustment; optional for an increase, where it is kept on the rate change.

Variant 1: string
string
Variant 2: null
null

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",
    "effective_date": "2026-10-29",
    "id": "00000000-0000-4000-8000-000000000001",
    "lease_id": "00000000-0000-4000-8000-000000000001",
    "new_rate": "<VALUE_MATCHING_PATTERN>",
    "notice_required_days": 0,
    "previous_rate": "<VALUE_MATCHING_PATTERN>",
    "status": "string",
    "applied_at": "2026-10-29T12:00:00Z",
    "batch_id": "00000000-0000-4000-8000-000000000001",
    "held_reason": "string",
    "kind": "increase"
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

dataRateScheduleResponserequired
Show data schema
applied_atstring | null

When the change was actually applied to the lease.

Format: date-time

Show applied_at schema
string | null

When the change was actually applied to the lease.

Variant 1: string
string
Variant 2: null
null
batch_idstring | null

The rent raise this change belongs to, when it came from one.

Format: uuid

Show batch_id schema
string | null

The rent raise this change belongs to, when it came from one.

Variant 1: string
string
Variant 2: null
null
created_atstringrequired

When the rate change was scheduled.

Format: date-time

effective_datestringrequired

Business date the new rent takes effect. Billing on or after this date uses new_rate.

Format: date

held_reasonstring | null

notice_late or notice_undelivered when billing held the change at its effective date.

Show held_reason schema
string | null

notice_late or notice_undelivered when billing held the change at its effective date.

Variant 1: string
string
Variant 2: null
null
idstringrequired

Unique identifier for this rate change.

Format: uuid

kindstring

increase (needed an advance notice and passed the raise guardrails) or adjustment (a decrease or a backdated correction).

Default: "increase"

lease_idstringrequired

The lease whose rent is changing.

Format: uuid

new_ratestringrequired

Rent after the change.

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

notice_attemptsinteger

Failed attempts to send the notice; the third makes it undeliverable.

Default: 0

notice_channelstring | null

email, sms or manual.

Show notice_channel schema
string | null

email, sms or manual.

Variant 1: string
string
Variant 2: null
null
notice_notestring | null

How staff delivered the notice outside Facily, when recorded.

Show notice_note schema
string | null

How staff delivered the notice outside Facily, when recorded.

Variant 1: string
string
Variant 2: null
null
notice_required_daysintegerrequired

How many days of advance notice the tenant must be given before the change may take effect.

notice_sent_atstring | null

When notice of the change was sent to the tenant. Null when notice is still outstanding.

Format: date-time

Show notice_sent_at schema
string | null

When notice of the change was sent to the tenant. Null when notice is still outstanding.

Variant 1: string
string
Variant 2: null
null
notice_statusstring

pending, sending, sent, undeliverable, manual, imported, not_required or legacy. Billing applies an increase only when its notice was given in time.

Default: "pending"

previous_ratestringrequired

Rent before the change.

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

reasonstring | null

Why the rent is changing, for example a scheduled increase or a negotiated adjustment.

Show reason schema
string | null

Why the rent is changing, for example a scheduled increase or a negotiated adjustment.

Variant 1: string
string
Variant 2: null
null
statusstringrequired

Where the change stands: scheduled, applied, cancelled, replaced or held.

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 leases operations
Build something that works beautifully.

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

Create Rate Schedule | Facily Developers