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.
Customer information (email at minimum).

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

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",
              "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
`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 (see below)
`subscription_data`	object	Rent collection configuration (see below)

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
    },
    {
      "customer_data": {
        "email": "[email protected]",
        "name": "John Smith",
        "legal": {
          "first_name": "John",
          "last_name": "Smith",
          "dob": {
            "day": 15,
            "month": 6,
            "year": 1990
          }
        }
      },
      "share_of_rent": 50,
      "lead_tenant": false,
      "permitted_occupier": false
    }
  ]
}

Applicant parameters

Parameter	Type	Required	Description
`share_of_rent`	number	Yes	Percentage of rent this applicant pays (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)
`create_reference`	boolean	No	Create a reference request for this applicant
`reference_data`	object	No	Reference configuration (see Referencing)
`verification_session_data`	object	No	Verification session configuration

Configure subscription data

The subscription_data object defines how rent is collected after the application completes.

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"
        }
      }
    ],
    "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	Yes	Number of intervals between billing (e.g., `1` for monthly)
`items`	array	Yes	Line items for each billing period
`start_date`	timestamp	No	When billing begins (Unix timestamp)
`end_date`	timestamp	No	When billing ends (Unix timestamp)
`billing_anchor`	timestamp	No	Date to anchor recurring billing
`days_until_due`	integer	No	Days before invoice is due
`days_before_collection`	integer	No	Days before billing date to create invoice

Subscription item types

Each item in subscription_data.items must have a type:

rent - Rental payments (requires unit parameter)
charge - Additional charges (e.g., parking, utilities)
product - Product-based charges

Configure deposits

Set up security deposit collection using the deposit and deposit_data parameters.

Deposit configuration

{
  "deposit": 75000,
  "create_deposit": true,
  "deposit_data": {
    "scheme": {
      "provider": "dps",
      "type": "custodial"
    },
    "automatic_deposit": {
      "enabled": true,
      "branch_id": "branch_123"
    }
  }
}

Deposit parameters

Parameter	Type	Description
`deposit`	integer	Deposit amount in smallest currency unit
`create_deposit`	boolean	Create a deposit object when payment is collected
`deposit_data.scheme.provider`	string	Deposit provider: `dps`, `mydeposits`, or `tds`
`deposit_data.scheme.type`	string	Deposit type: `custodial` or `insured`
`deposit_data.automatic_deposit.enabled`	boolean	Enable automatic deposit registration
`deposit_data.handled_externally`	boolean	Deposit managed by landlord or third party

Configure contracts

Control contract generation and signing with these parameters.

Contract configuration

{
  "contract_template": "ct_abc123",
  "create_contract_on_accept": true,
  "automatic_counter_signature": true,
  "owner_signature_required": false,
  "contract_address": "123 Main Street, London, SW1A 1AA",
  "contract_options": {
    "send_email": true
  }
}

Contract parameters

Parameter	Type	Description
`contract_template`	string	Contract template ID
`create_contract_on_accept`	boolean	Generate contract when application is accepted
`automatic_counter_signature`	boolean	Auto-sign contract on landlord’s behalf
`owner_signature_required`	boolean	Require property owner to sign
`contract_address`	string	Address to use in the contract (updates unit record)
`contract_legal_entity`	string	Legal entity for the contract (replaces owner details)
`contract_options.send_email`	boolean	Email contract to applicants (default: `true`)
`send_owner_contract`	boolean	Send contract to owner on completion

Configure application payments

Collect payments during the application process.

Holding fee

{
  "holding_fee": 35000
}

The holding fee is collected early in the application to secure the tenancy.

Advance rent

{
  "advance_rent": 150000
}

Collect rent in advance as part of the application.

Partial payments

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

Partial payment

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

Partial payments require exactly one applicant with share_of_rent of 100%.

Post-application payment session

Collect additional payments after contract signing:

Post-application payment session

{
  "post_application_payment_session": {
    "amount": 50000,
    "description": "Admin fee",
    "payment_method_types": ["card", "bacs_debit"],
    "reporting_type": "charge"
  }
}

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": 2024
  },
  "end_date_config": {
    "day": 31,
    "month": 3,
    "year": 2025
  }
}

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)
`move_in_date`	timestamp	Actual move-in date (for short lets)
`move_out_date`	timestamp	Actual move-out date (for short lets)
`checkin_time`	string	Check-in time
`checkout_time`	string	Check-out time

Referencing

Enable tenant referencing during the application process.

Automatic referencing

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

Reference providers

Provider	Description
`canopy`	Canopy referencing
`homelet`	HomeLet referencing
`let_alliance`	Let Alliance referencing

Additional options

Break clause

{
  "break_clause": {
    "notification_date": 1728000000,
    "terms": "Either party may terminate with 2 months notice after 6 months"
  }
}

End behavior

Control what happens when the tenancy reaches its end date:

End behavior

{
  "end_behavior": "roll"
}

Value	Description
`complete`	Mark tenancy as complete
`roll`	Convert to periodic tenancy

Completion behavior

{
  "completion_behavior": "manual"
}

Value	Description
`automatic`	Complete automatically when all steps are done
`manual`	Require manual completion

Metadata

Attach custom data to the application:

Metadata

{
  "metadata": {
    "internal_ref": "APP-2024-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 '{
        "type": "standard",
        "unit": "unit_123",
        "currency": "gbp",
        "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,
            "create_reference": true,
            "reference_data": {
              "automatic_reference": {
                "enabled": true,
                "provider": "canopy"
              }
            }
          }
        ],
        "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"
              }
            }
          ]
        },
        "holding_fee": 35000,
        "deposit": 75000,
        "create_deposit": true,
        "deposit_data": {
          "scheme": {
            "provider": "dps",
            "type": "custodial"
          }
        },
        "contract_template": "ct_abc123",
        "create_contract_on_accept": true,
        "automatic_counter_signature": 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",
  "customers": ["cus_abc123"],
  "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 automatically or manually based on completion_behavior.
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.

Developer tools

Essentials

Integrations

Platforms

Create an application

Prerequisites

Application types

Create a customer

Building an application request

Required parameters

Configure applicants

Applicant parameters

Configure subscription data

Subscription parameters

Subscription item types

Configure deposits

Deposit parameters

Configure contracts

Contract parameters

Configure application payments

Holding fee

Advance rent

Partial payments

Post-application payment session

Configure dates

Using timestamps

Using date configuration objects

Date parameters

Referencing

Reference providers

Additional options

Break clause

End behavior

Completion behavior

Metadata