Create an application

This guide shows you how to create an application using the Applications API. Applications allow you to create new leases, accept move-in payments, and set up contracts.

Prerequisites

Before creating an application, ensure you have:

A unit ID for the property.
An application configuration ID.
Customer information (email at minimum).

Unit availability

New lettings need a unit that is on the market. Retrieve the unit and read availability on the unit object — state is derived from occupancy, the release gate, and available_from.

`availability.state`	Can you create a `standard` or `let_only` application?
`to_let`	Yes. The unit is released to the market.
`coming_available`	Not unless you set `release_unit` to `true`, which releases the unit as part of creating the application.
`available`	Yes. Vacant stock that has not been released is still accepted for a new letting. Set `release_unit` to `true` if you also want it on the market.
`held`	Not unless you set `release_unit` to `true`, which clears the hold and releases the unit.
`under_offer`	No. Cancel or revise the existing application first.
`occupied`	Not unless you set `release_unit` to `true`.
`maintenance`, `offline`, `unmanaged`	No. Change the unit’s status first.

renewal, active_tenancy, and revisions skip this check — they act on a tenancy already in the unit. For an occupied unit that is already to_let, start_date must be on or after availability.available_from.

Retrieve a unit

curl https://api.yorlet.com/v1/units/unit_123 \
  -H "Authorization: Bearer {{API_KEY}}"

availability

{
  "availability": {
    "available_from": 1761782400,
    "held": false,
    "hold_reason": null,
    "released": false,
    "released_at": null,
    "state": "coming_available",
    "tenancy": "app_abc123",
    "tenancy_end": 1761782400
  }
}

To put a coming_available or available unit on the market, release it first, or set release_unit to true when you create the application:

Release a unit to the market

curl https://api.yorlet.com/v1/units/unit_123/release \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{}'

Release on create

{
  "release_unit": true
}

If auto-release is enabled on the account, a coming_available unit is released to to_let N days before available_from. You can wait until availability.state is to_let, call release yourself, or pass release_unit. Holding a unit keeps it off the market even when auto-release is on, unless you pass release_unit.

Occupied stock that has not been released is rejected for new lettings unless you pass release_unit. A 12-month tenancy can sit in coming_available from the day it starts — release it when you are ready to market, pass release_unit on create, or let auto-release list it as the end date approaches.

Application types

Yorlet supports four application types, each designed for different scenarios:

Type	Description	Use case
`standard`	Full application with payments, rent collection, and contracts	New tenancies
`renewal`	Refresh existing tenancies with new terms	Extending current leases
`active_tenancy`	Collect rental payments for existing tenancies	Mid-tenancy onboarding
`let_only`	Full application without rent collection setup	Landlord-managed billing

Create a customer

Before creating an application, you need a customer. You can either create a customer using the Customers API or by providing the applicants.customer_data object in the application request.

Using the Customers API
Inline with application

Create a customer first, then reference their ID in the application.

Create a customer

curl https://api.yorlet.com/v1/customers \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
        "email": "[email protected]",
        "name": "Jane Doe",
        "phone": "+441234567890"
      }'

Response

{
  "id": "cus_lrhplff1u4ZhIPSU",
  "object": "customer",
  "email": "[email protected]",
  "name": "Jane Doe"
}

Use the customer ID in your application request with applicants.customer.

Create a customer inline by providing applicants.customer_data instead of applicants.customer.

Create customer inline

curl https://api.yorlet.com/v1/applications \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
        "applicants": [
          {
            "customer_data": {
              "email": "[email protected]",
              "name": "Jane Doe",
              "phone": "+441234567890",
              "legal": {
                "first_name": "Jane",
                "last_name": "Doe"
              }
            },
            "share_of_rent": 100
          }
        ]
      }'

If you provide customer_data.legal, the customer’s legal information will be used for contract generation.

Building an application request

You can build an application request by adding the required parameters and configuring the optional parameters as needed.

Required parameters

Parameter	Type	Description
`application_configuration`	string	The identifier of the application configuration to create the application with
`type`	string	Application type: `standard`, `renewal`, `active_tenancy`, or `let_only`
`unit`	string	The unit ID for the property
`applicants`	array	Array of applicant objects (min 1, max 10)
`subscription_data`	object	Rent collection configuration

Configure applicants

The applicants array defines who is applying for the tenancy. Each applicant must have either a customer ID or customer_data object, plus a share_of_rent.

Applicants array

{
  "applicants": [
    {
      "customer": "cus_existing123",
      "share_of_rent": 50,
      "lead_tenant": true,
      "requirements": {
        "deposit": true,
        "guarantor": false
      },
      "verification_session_data": {
        "types": ["identity"]
      }
    },
    {
      "customer_data": {
        "email": "[email protected]",
        "name": "John Smith",
        "legal": {
          "first_name": "John",
          "last_name": "Smith",
          "dob": {
            "day": 15,
            "month": 6,
            "year": 1990
          }
        },
        "address": {
          "line1": "10 High Street",
          "city": "London",
          "postal_code": "SW1A 1AA",
          "country": "GB"
        }
      },
      "share_of_rent": 50,
      "lead_tenant": false,
      "permitted_occupier": false,
      "requirements": {
        "deposit": true,
        "guarantor": false,
        "pre_qualification": true
      }
    }
  ]
}

Applicant parameters

Parameter	Type	Required	Description
`share_of_rent`	number	Yes	Percentage of rent this applicant pays (0-100, all must total 100)
`customer`	string	Conditional	Existing customer ID
`customer_data`	object	Conditional	New customer details (required if no `customer`)
`lead_tenant`	boolean	No	Whether this applicant is the lead tenant
`permitted_occupier`	boolean	No	Whether this person is a permitted occupier (not on the contract)
`reference_data`	object	No	Reference configuration (see Referencing)
`requirements`	object	No	Requirements configuration for the applicant
`verification_session_data`	object	No	Set `types` to request a verification session for the applicant (see Verification)

Customer data parameters

Parameter	Type	Required	Description
`email`	string	Yes	Customer email address
`name`	string	No	Customer display name
`phone`	string	No	Customer phone number
`legal`	object	No	Legal information (`first_name`, `last_name`, `dob`) for contract generation
`address`	object	No	Customer address (`line1`, `line2`, `city`, `state`, `postal_code`, `country`)
`metadata`	object	No	Key-value pairs for storing additional information

Requirements parameters

The requirements object controls which steps the applicant must complete.

Parameter	Type	Description
`deposit`	boolean	Whether to collect a deposit from the applicant
`guarantor`	boolean	Whether the applicant needs a guarantor
`pre_qualification`	boolean	Whether the applicant needs to complete pre-qualification

Verification

To request identity or Right to Rent verification, set verification_session_data.types on the applicant.

Verification session data

{
  "verification_session_data": {
    "types": ["identity", "right_to_rent"]
  }
}

Parameter	Type	Description
`types`	array	Verification types to perform: `identity`, `right_to_rent` (min 1)

Configure subscription data

The subscription_data object defines how rent is collected after the application completes. Only collection_method and interval are required.

Subscription data

{
  "subscription_data": {
    "collection_method": "charge_automatically",
    "interval": "month",
    "interval_count": 1,
    "days_until_due": 14,
    "items": [
      {
        "description": "Monthly Rent",
        "type": "rent",
        "unit": "unit_123",
        "price_data": {
          "amount": 150000,
          "currency": "gbp",
          "tax_percent": 0
        }
      },
      {
        "description": "Parking Space",
        "type": "charge",
        "price_data": {
          "amount": 5000,
          "currency": "gbp",
          "tax_percent": 0
        }
      }
    ],
    "start_date": 1712716800,
    "end_date": 1744252800
  }
}

Subscription parameters

Parameter	Type	Required	Description
`collection_method`	string	Yes	`charge_automatically` or `send_invoice`
`interval`	string	Yes	Billing frequency: `month`, `week`, `custom`, or `upfront`
`interval_count`	integer	No	Number of intervals between billing (e.g., `1` for monthly)
`items`	array	No	Line items for each billing period (min 1, max 10)
`start_date`	timestamp	No	When billing begins (Unix timestamp)
`end_date`	timestamp	No	When billing ends (Unix timestamp)
`start_date_config`	object	No	Date object (`day`, `month`, `year`) as alternative to `start_date`
`end_date_config`	object	No	Date object (`day`, `month`, `year`) as alternative to `end_date`
`billing_anchor`	timestamp	No	Date to anchor recurring billing (Unix timestamp)
`billing_anchor_config`	object	No	Anchor config with `day_of_month` (1-31) as alternative to `billing_anchor`
`days_until_due`	integer	No	Days before invoice is due
`days_before_collection`	integer	No	Days before billing date to create invoice (0-7)
`coupon`	string	No	Coupon ID to apply to the subscription
`first_invoice_creation`	string	No	Set to `immediately` to create the first invoice right away
`add_invoice_items`	array	No	One-time invoice items added to the first invoice (max 10)
`phases`	array	No	Subscription phases for changing items over time
`custom_fields`	array	No	Custom fields on invoices (max 4, each with `name` and `value`)

Subscription item parameters

Each item in subscription_data.items requires price_data and type.

Parameter	Type	Required	Description
`type`	string	Yes	`rent`, `charge`, or `product`
`price_data`	object	Yes	Pricing object with `amount`, `currency`, and `tax_percent` (all required)
`description`	string	No	Display description for the line item
`unit`	string	No	Unit ID (required for `rent` type items)
`price`	string	No	Price ID (alternative to `price_data`)
`proration_behavior`	string	No	`create_prorations` or `none`
`schedule`	array	No	Schedule for changing the item amount over time
`tax_rate`	string	No	Tax rate ID
`transfer_behavior`	string	No	`automatic`, `owner`, or `none`
`transfer_destination`	string	No	Owner ID for transfer (only when `transfer_behavior` is `owner`)
`metadata`	object	No	Key-value pairs for storing additional information

Add invoice items

Use add_invoice_items to include one-time charges on the first invoice.

Add invoice items

{
  "subscription_data": {
    "collection_method": "charge_automatically",
    "interval": "month",
    "items": [...],
    "add_invoice_items": [
      {
        "amount": 25000,
        "currency": "gbp",
        "description": "Setup fee",
        "type": "charge",
        "tax_percent": 0,
        "transfer_behavior": "automatic"
      }
    ]
  }
}

Subscription phases

Use phases to schedule changes to subscription items at specific dates.

Subscription phases

{
  "subscription_data": {
    "collection_method": "charge_automatically",
    "interval": "month",
    "items": [
      {
        "description": "Monthly Rent",
        "type": "rent",
        "unit": "unit_123",
        "price_data": {
          "amount": 150000,
          "currency": "gbp",
          "tax_percent": 0
        }
      }
    ],
    "phases": [
      {
        "start_date": 1744252800,
        "items": [
          {
            "description": "Monthly Rent (Year 2)",
            "type": "rent",
            "unit": "unit_123",
            "price_data": {
              "amount": 160000,
              "currency": "gbp",
              "tax_percent": 0
            }
          }
        ]
      }
    ]
  }
}

Configure deposits

Set up security deposit collection using the deposit_amount parameter.

Deposit configuration

{
  "deposit_amount": 75000
}

Parameter	Type	Description
`deposit_amount`	integer	Deposit amount in smallest currency unit (0-99999900)

Use the applicant-level requirements.deposit parameter to control which applicants are required to pay a deposit.

Configure contracts

Control contract generation and signing with the contract_template and contract_options parameters.

Contract configuration

{
  "contract_template": "ct_abc123",
  "contract_options": {
    "automatic_counter_signature": true,
    "owner_signature_required": false,
    "send_applicant_email": true,
    "send_owner_completion_email": false,
    "legal_entity": "le_abc123"
  }
}

The contract_template parameter is required when the application type is standard, renewal, or let_only.

Contract parameters

Parameter	Type	Description
`contract_template`	string	Contract template ID
`contract_options.automatic_counter_signature`	boolean	Auto-sign contract on landlord’s behalf
`contract_options.owner_signature_required`	boolean	Require property owner to sign
`contract_options.send_applicant_email`	boolean	Email contract to applicants
`contract_options.send_owner_completion_email`	boolean	Send contract to owner on completion
`contract_options.legal_entity`	string	Legal entity ID for the contract

Configure application payments

Collect payments during the application process.

Holding fee

{
  "holding_fee_amount": 35000
}

The holding fee is collected early in the application to secure the tenancy. Amount must be between 0 and 99,999,900 (in smallest currency unit).

Advance rent

{
  "advance_rent_amount": 150000
}

Collect rent in advance as part of the application. Amount must be between 0 and 99,999,900 (in smallest currency unit).

Partial payments

Configure partial upfront payments that create credit grants for future rent:

Partial payment

{
  "partial_payment": {
    "amount": 300000,
    "description": "First two months rent"
  }
}

Both amount and description are required when using partial payments.

Partial payments require exactly one applicant with share_of_rent of 100%, and are only supported when subscription_data.interval is month.

Configure dates

Using timestamps

Provide dates as Unix timestamps in UTC:

Date timestamps

{
  "start_date": 1712716800,
  "end_date": 1744252800,
  "move_in_date": 1712716800,
  "move_out_date": 1744252800
}

Using date configuration objects

Alternatively, use date configuration objects for automatic calculation:

Date configuration

{
  "start_date_config": {
    "day": 1,
    "month": 4,
    "year": 2025
  },
  "end_date_config": {
    "day": 31,
    "month": 3,
    "year": 2026
  }
}

When using end_date_config, Yorlet automatically sets the time to 23:59:59 to include the full day.

Date parameters

Parameter	Type	Description
`start_date`	timestamp	Tenancy start date
`end_date`	timestamp	Tenancy end date (null for periodic tenancy)
`start_date_config`	object	Date object (`day`, `month`, `year`) as alternative to `start_date`
`end_date_config`	object	Date object (`day`, `month`, `year`) as alternative to `end_date`
`move_in_date`	timestamp	Actual move-in date (useful for short lets)
`move_out_date`	timestamp	Actual move-out date (useful for short lets)

Referencing

Enable tenant referencing during the application process.

Automatic referencing

{
  "applicants": [
    {
      "customer_data": {
        "email": "[email protected]"
      },
      "share_of_rent": 100,
      "reference_data": {
        "automatic_reference": {
          "enabled": true,
          "provider": "canopy"
        }
      }
    }
  ]
}

Reference providers

Provider	Description
`advance_rent`	Advance Rent referencing
`canopy`	Canopy referencing
`homelet`	HomeLet referencing
`let_alliance`	Let Alliance referencing

Additional options

Accept on create

For active_tenancy applications, set accept to true to immediately accept the application when created.

Accept on create

{
  "type": "active_tenancy",
  "accept": true
}

End behavior

Control what happens when the tenancy reaches its end date:

End behavior

{
  "end_behavior": "roll"
}

Value	Description
`complete`	Mark tenancy as complete (requires an end date)
`roll`	Convert to periodic tenancy

Create subscriptions

Control whether subscriptions are created for the application. Defaults to true.

Skip subscription creation

{
  "create_subscriptions": false
}

Owner options

Configure owner-specific settings:

Owner options

{
  "owner_options": {
    "apply_unit_fees": true
  }
}

Assignees

Assign a team member to the application. Use assignee to set the owner of the application and deal_assignee to set the owner of the underlying deal.

Assignees

{
  "assignee": "user_abc123",
  "deal_assignee": "user_def456"
}

Parameter	Type	Description
`assignee`	string	The identifier of the assignee for the application
`deal_assignee`	string	The identifier of the deal assignee for the application

Update unit rent

Set update_unit_rent to true to update the unit’s rent amount with the pricing used in the application:

Update unit rent

{
  "update_unit_rent": true
}

Release the unit

Set release_unit to true to release the unit to the market as part of creating a standard or let_only application. Use this when the unit is coming_available (occupied, with a known let date, but not yet on the market). It is not allowed on renewals, imported active tenancies, or revisions. In the dashboard, the create application form shows the unit’s availability and lets you release it from there. See Create an application.

Release the unit

{
  "release_unit": true
}

Metadata

Attach custom data to the application:

Metadata

{
  "metadata": {
    "internal_ref": "APP-2025-001",
    "source": "website"
  }
}

Here’s a comprehensive example with commonly used parameters:

Complete application example

curl https://api.yorlet.com/v1/applications \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
        "application_configuration": "appconfig_abc123",
        "type": "standard",
        "unit": "unit_123",
        "release_unit": true,
        "applicants": [
          {
            "customer_data": {
              "email": "[email protected]",
              "name": "Jane Doe",
              "phone": "+441234567890",
              "legal": {
                "first_name": "Jane",
                "last_name": "Doe",
                "dob": {
                  "day": 15,
                  "month": 6,
                  "year": 1990
                }
              }
            },
            "share_of_rent": 100,
            "lead_tenant": true,
            "reference_data": {
              "automatic_reference": {
                "enabled": true,
                "provider": "canopy"
              }
            },
            "requirements": {
              "deposit": true,
              "guarantor": false
            },
            "verification_session_data": {
              "types": ["identity"]
            }
          }
        ],
        "start_date": 1712716800,
        "end_date": 1744252800,
        "subscription_data": {
          "collection_method": "charge_automatically",
          "interval": "month",
          "interval_count": 1,
          "items": [
            {
              "description": "Monthly Rent",
              "type": "rent",
              "unit": "unit_123",
              "price_data": {
                "amount": 150000,
                "currency": "gbp",
                "tax_percent": 0
              }
            }
          ]
        },
        "holding_fee_amount": 35000,
        "deposit_amount": 75000,
        "contract_template": "ct_abc123",
        "contract_options": {
          "automatic_counter_signature": true,
          "send_applicant_email": true
        },
        "end_behavior": "roll",
        "send_email": true,
        "metadata": {
          "source": "api_integration"
        }
      }'

A successful request returns the application object:

Example response

{
  "id": "app_lrhplff1u4ZhIPSU",
  "object": "application",
  "status": "pending",
  "type": "standard",
  "unit": "unit_123",
  "application_configuration": "appconfig_abc123",
  "deposit_amount": 75000,
  "holding_fee_amount": 35000,
  "subscription_data": {
    "collection_method": "charge_automatically",
    "interval": "month",
    "interval_count": 1,
    "items": [...]
  }
}

Next steps

After creating an application:

Send to applicant - If send_email is true, applicants receive the application portal link automatically.
Monitor progress - Use webhooks to track application events.
Complete the application - The application completes based on the steps defined in the application configuration.
Retrieve subscriptions - Listen for subscription.created events to get the subscription IDs.

Retrieve the subscription

After the application completes, a subscription is created asynchronously using the subscription_data object. To retrieve the subscription ID, listen for the subscription.created webhook event.

subscription.created event

{
  "id": "evt_abc123",
  "object": "event",
  "type": "subscription.created",
  "data": {
    "object": {
      "id": "sub_lrhplff1u4ZhIPSU",
      "object": "subscription",
      "application": "app_lrhplff1u4ZhIPSU",
      "customer": "cus_abc123",
      "status": "scheduled",
      // ... other fields on the subscription object
    }
  }
}

The event payload includes:

Field	Description
`data.object.id`	The subscription ID
`data.object.application`	The application ID that created this subscription
`data.object.customer`	The customer ID associated with the subscription

Use the application and customer fields to tie the subscription back to your original application request.

For applications with multiple applicants, a separate subscription is created for each applicant based on their share_of_rent. You will receive a subscription.created event for each subscription.

(Optional) Create a payment method session

In some instances, the application will automatically complete without the applicant needing to visit the application portal. For example, if the application type is set to active_tenancy, the application will automatically complete when created. If you want to collect a payment method from the applicant, you can create a Payment Method Session and associate it with the subscription you retrieved in the subscription.created event.

​Prerequisites

​Unit availability

​Application types

​Create a customer

​Building an application request

​Required parameters

​Configure applicants

​Applicant parameters

​Customer data parameters

​Requirements parameters

​Verification

​Configure subscription data

​Subscription parameters

​Subscription item parameters

​Add invoice items

​Subscription phases

​Configure deposits

​Configure contracts

​Contract parameters

​Configure application payments

​Holding fee

​Advance rent

​Partial payments

​Configure dates

​Using timestamps

​Using date configuration objects

​Date parameters

​Referencing

​Reference providers

​Additional options

​Accept on create

​End behavior

​Create subscriptions

​Owner options

​Assignees

​Update unit rent

​Release the unit

​Metadata