Skip to content
FacilydevelopersDashboard
Build with Facily
DocsREST APIsSet Lease Insurance
Search the full API reference Esc to close

Set Lease Insurance

Leases · REST API reference

Get support
PUT/v1/leases/{lease_id}/insurance
Start or change the lease's coverage (Step 13 design 5.11): a facility plan, the tenant's own policy, or a decline. The active enrolment is replaced, never edited; the new premium bills from the next period. 409 `insurance_required` for a decline where the facility requires insurance, `lease_busy` while billing runs.

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 PUT \
  --url 'https://api.staging.facily.ai/v1/leases/<LEASE_ID>/insurance' \
  --header "Authorization: Bearer $FACILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "coverage_type": "facility_plan",
  "insurance_plan_id": "00000000-0000-4000-8000-000000000001",
  "own_policy": {
    "carrier": "string",
    "certificate_document_id": "00000000-0000-4000-8000-000000000001",
    "expires_on": "2026-10-29",
    "policy_number": "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

coverage_typestringrequired

Values: "facility_plan", "own_policy", "declined"

insurance_plan_idstring | null

The facility's plan. Required for facility_plan, refused otherwise.

Format: uuid

Show insurance_plan_id schema
string | null

The facility's plan. Required for facility_plan, refused otherwise.

Variant 1: string
string
Variant 2: null
null
own_policyOwnPolicyRequest | null

Required for own_policy, refused otherwise.

Show own_policy schema
OwnPolicyRequest | null

Required for own_policy, refused otherwise.

Variant 1: OwnPolicyRequest
carrierstringrequired

The insurer.

Min length: 1 · Max length: 100

certificate_document_idstring | null

An uploaded certificate of insurance (a document on the tenant or lease).

Format: uuid

Show certificate_document_id schema
string | null

An uploaded certificate of insurance (a document on the tenant or lease).

Variant 1: string
string
Variant 2: null
null
expires_onstring | null

Format: date

Show expires_on schema
string | null
Variant 1: string
string
Variant 2: null
null
policy_numberstring | null

Max length: 100

Show policy_number schema
string | null
Variant 1: string
string
Variant 2: null
null
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": {
    "coverage_type": "string",
    "effective_date": "2026-10-29",
    "id": "00000000-0000-4000-8000-000000000001",
    "lease_id": "00000000-0000-4000-8000-000000000001",
    "status": "string",
    "tenant_id": "00000000-0000-4000-8000-000000000001",
    "cancel_reason": "string",
    "cancellation_date": "2026-10-29",
    "carrier": "string",
    "certificate_document_id": "00000000-0000-4000-8000-000000000001",
    "coverage_amount": "<VALUE_MATCHING_PATTERN>",
    "expires_on": "2026-10-29"
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

dataInsuranceEnrollmentResponserequired
Show data schema
cancel_reasonstring | null
Show cancel_reason schema
string | null
Variant 1: string
string
Variant 2: null
null
cancellation_datestring | null

Format: date

Show cancellation_date schema
string | null
Variant 1: string
string
Variant 2: null
null
carrierstring | null
Show carrier schema
string | null
Variant 1: string
string
Variant 2: null
null
certificate_document_idstring | null

Format: uuid

Show certificate_document_id schema
string | null
Variant 1: string
string
Variant 2: null
null
coverage_amountstring | null

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

Show coverage_amount schema
string | null
Variant 1: string
string
Variant 2: null
null
coverage_typestringrequired
effective_datestringrequired

Format: date

expires_onstring | null

Format: date

Show expires_on schema
string | null
Variant 1: string
string
Variant 2: null
null
idstringrequired

Format: uuid

insurance_plan_idstring | null

Format: uuid

Show insurance_plan_id schema
string | null
Variant 1: string
string
Variant 2: null
null
lease_idstringrequired

Format: uuid

policy_numberstring | null
Show policy_number schema
string | null
Variant 1: string
string
Variant 2: null
null
predecessor_enrollment_idstring | null

Format: uuid

Show predecessor_enrollment_id schema
string | null
Variant 1: string
string
Variant 2: null
null
premiumstring | null

The monthly premium billed, snapshotted from the plan.

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

Show premium schema
string | null

The monthly premium billed, snapshotted from the plan.

Variant 1: string
string
Variant 2: null
null
start_reasonstring | null
Show start_reason schema
string | null
Variant 1: string
string
Variant 2: null
null
statusstringrequired
tenant_idstringrequired

Format: uuid

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

Set Lease Insurance | Facily Developers