> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yorlet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an application

> Learn how to create an application with the Yorlet API.

export const APIBadge = () => {
  return <div style={{
    display: 'inline-block',
    backgroundColor: 'rgb(var(--primary-light))',
    color: '#ffffff',
    padding: '1px 4px',
    borderRadius: '.375rem',
    borderColor: 'rgb(var(--gray-200))',
    borderWidth: '1px',
    position: 'relative',
    top: '-2px',
    marginLeft: '4px',
    fontSize: '11px',
    fontWeight: 700,
    letterSpacing: '0.05em',
    lineHeight: '11px'
  }}>
      API
    </div>;
};

This guide shows you how to create an application using the <a href="/api/leasing/applications/create" target="_blank">Applications API<APIBadge /></a>. 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).

## 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<APIBadge />](https://docs.yorlet.com/api/core/customers/create) or by providing the `applicants.customer_data` object in the application request.

<Tabs>
  <Tab title="Using the Customers API">
    Create a customer first, then reference their ID in the application.

    ```bash Create a customer theme={"theme":"dracula"}
    curl https://api.yorlet.com/v1/customers \
      -H "Authorization: Bearer {{API_KEY}}" \
      -H "Yorlet-Version: 2025-08-21.preview" \
      -H "Content-Type: application/json" \
      -d '{
            "email": "jane@example.com",
            "name": "Jane Doe",
            "phone": "+441234567890"
          }'
    ```

    ```json Response theme={"theme":"dracula"}
    {
      "id": "cus_lrhplff1u4ZhIPSU",
      "object": "customer",
      "email": "jane@example.com",
      "name": "Jane Doe"
    }
    ```

    Use the customer ID in your application request with `applicants.customer`.
  </Tab>

  <Tab title="Inline with application">
    Create a customer inline by providing `applicants.customer_data` instead of `applicants.customer`.

    ```bash Create customer inline theme={"theme":"dracula"}
    curl https://api.yorlet.com/v1/applications \
      -H "Authorization: Bearer {{API_KEY}}" \
      -H "Yorlet-Version: 2025-08-21.preview" \
      -H "Content-Type: application/json" \
      -d '{
            "applicants": [
              {
                "customer_data": {
                  "email": "jane@example.com",
                  "name": "Jane Doe",
                  "phone": "+441234567890",
                  "legal": {
                    "first_name": "Jane",
                    "last_name": "Doe"
                  }
                },
                "share_of_rent": 100
              }
            ]
          }'
    ```

    <Note>
      If you provide `customer_data.legal`, the customer's legal information will be used for contract generation.
    </Note>
  </Tab>
</Tabs>

## 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`.

```json Applicants array theme={"theme":"dracula"}
{
  "applicants": [
    {
      "customer": "cus_existing123",
      "share_of_rent": 50,
      "lead_tenant": true,
      "requirements": {
        "deposit": true,
        "guarantor": false
      },
      "verification_session_data": {
        "types": ["identity"]
      }
    },
    {
      "customer_data": {
        "email": "john@example.com",
        "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](#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](#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.

```json Verification session data theme={"theme":"dracula"}
{
  "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.

```json Subscription data theme={"theme":"dracula"}
{
  "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.

```json Add invoice items theme={"theme":"dracula"}
{
  "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.

```json Subscription phases theme={"theme":"dracula"}
{
  "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.

```json Deposit configuration theme={"theme":"dracula"}
{
  "deposit_amount": 75000
}
```

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

<Note>
  Use the applicant-level `requirements.deposit` parameter to control which applicants are required to pay a deposit.
</Note>

### Configure contracts

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

```json Contract configuration theme={"theme":"dracula"}
{
  "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"
  }
}
```

<Note>
  The `contract_template` parameter is required when the application `type` is `standard`, `renewal`, or `let_only`.
</Note>

#### 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

```json Holding fee theme={"theme":"dracula"}
{
  "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

```json Advance rent theme={"theme":"dracula"}
{
  "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:

```json Partial payment theme={"theme":"dracula"}
{
  "partial_payment": {
    "amount": 300000,
    "description": "First two months rent"
  }
}
```

Both `amount` and `description` are required when using partial payments.

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

### Configure dates

#### Using timestamps

Provide dates as Unix timestamps in UTC:

```json Date timestamps theme={"theme":"dracula"}
{
  "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:

```json Date configuration theme={"theme":"dracula"}
{
  "start_date_config": {
    "day": 1,
    "month": 4,
    "year": 2025
  },
  "end_date_config": {
    "day": 31,
    "month": 3,
    "year": 2026
  }
}
```

<Note>
  When using `end_date_config`, Yorlet automatically sets the time to 23:59:59 to include the full day.
</Note>

#### 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.

```json Automatic referencing theme={"theme":"dracula"}
{
  "applicants": [
    {
      "customer_data": {
        "email": "jane@example.com"
      },
      "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.

```json Accept on create theme={"theme":"dracula"}
{
  "type": "active_tenancy",
  "accept": true
}
```

#### End behavior

Control what happens when the tenancy reaches its end date:

```json End behavior theme={"theme":"dracula"}
{
  "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`.

```json Skip subscription creation theme={"theme":"dracula"}
{
  "create_subscriptions": false
}
```

#### Owner options

Configure owner-specific settings:

```json Owner options theme={"theme":"dracula"}
{
  "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.

```json Assignees theme={"theme":"dracula"}
{
  "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:

```json Update unit rent theme={"theme":"dracula"}
{
  "update_unit_rent": true
}
```

#### Metadata

Attach custom data to the application:

```json Metadata theme={"theme":"dracula"}
{
  "metadata": {
    "internal_ref": "APP-2025-001",
    "source": "website"
  }
}
```

## Create an application

Here's a comprehensive example with commonly used parameters:

```bash Complete application example theme={"theme":"dracula"}
curl https://api.yorlet.com/v1/applications \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Yorlet-Version: 2025-08-21.preview" \
  -H "Content-Type: application/json" \
  -d '{
        "application_configuration": "appconfig_abc123",
        "type": "standard",
        "unit": "unit_123",
        "applicants": [
          {
            "customer_data": {
              "email": "jane@example.com",
              "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:

```json Example response theme={"theme":"dracula"}
{
  "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:

1. **Send to applicant** - If `send_email` is `true`, applicants receive the application portal link automatically.
2. **Monitor progress** - Use [webhooks](/development/webhooks) to track application events.
3. **Complete the application** - The application completes based on the steps defined in the application configuration.
4. **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.

```json subscription.created event highlight {7,9-10} theme={"theme":"dracula"}
{
  "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.

<Note>
  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.
</Note>

### (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](/development/integrations/payments/payment-method-sessions#create-a-payment-method-session) and associate it with the subscription you retrieved in the `subscription.created` event.