# Activity log Source: https://docs.yorlet.com/account/audit-logs Review who changed account settings, and from where. The activity log records settings changes on your account, so you can see who did what and when. Each entry shows the team member, the action, the device, the IP address, and the time. You can review activity from [Settings → Security → Activity](https://dashboard.yorlet.com/settings/security/activity). To see who changed a Customer, Invoice, or other record — rather than account settings — use [Events and logs](/development/events). ## What is recorded The log includes changes such as: * Updates to billing, leasing, deposits, payment methods, and owner payout settings * Connecting or removing an integration * Enabling Recover * Changes to account security and two-step authentication ## Read an entry Each row shows: * **Action**: The team member's email and what they changed. * **Device ID**: A short identifier for the device they used. * **IP address**: The IP address, with a country flag when it is known. * **Time**: When the change happened. # Branding Source: https://docs.yorlet.com/account/branding Add your business name, colour, and icon so emails and receipts look like your brand. Branding is how customers recognise you in Yorlet. Your business name, colour, and icon appear on emails and receipts, so every message looks like it came from you. [Workflows](/business-automation/workflows/actions#send-email) that send a **Branded** email, and new outbound from the [assistant](/business-automation/ai/assistant), use the same logo, colours, and support details. You can update branding from [Settings → Branding](https://dashboard.yorlet.com/settings/branding). ## Update your branding To update your branding, follow these steps: 1. Go to [Branding](https://dashboard.yorlet.com/settings/branding). 2. Enter your **Business name**. This is the name customers see on emails and receipts. 3. Set your **Brand color**. Use a 6-character hex code, for example `001328`. 4. Upload a **Brand icon**. Use a PNG up to 400 × 400 pixels. A square image with a white background works best. 5. Check the **Preview** on the right to see how a receipt will look. 6. Click **Save changes**. The preview uses your colour as the email background, and picks a readable text colour automatically. # Authentication Source: https://docs.yorlet.com/api/authentication ```bash theme={"theme":"dracula"} curl https://api.yorlet.com/v1/applications \ -H "Authorization: Bearer {API_KEY}" \ ``` To use the API you must authenticate a request using your API key. You can find the key in the Dashboard. There are two API keys in the dashboard: Publishable and Secret. You can find out more about the differences here. The API key should be included in all API requests to the server in a header that looks like the following: `Authorization: Bearer {API_KEY}` # Create a coupon Source: https://docs.yorlet.com/api/billing/coupons/create openapi-billing.json POST /v1/coupons Create a coupon # Delete a coupon Source: https://docs.yorlet.com/api/billing/coupons/delete openapi-billing.json DELETE /v1/coupons/{id} Delete a coupon # List all coupons Source: https://docs.yorlet.com/api/billing/coupons/list openapi-billing.json GET /v1/coupons List all coupons # The coupon object Source: https://docs.yorlet.com/api/billing/coupons/object # Retrieve a coupon Source: https://docs.yorlet.com/api/billing/coupons/retrieve openapi-billing.json GET /v1/coupons/{id} Retrieve a coupon # Update a coupon Source: https://docs.yorlet.com/api/billing/coupons/update openapi-billing.json POST /v1/coupons/{id} Update a coupon # Create a credit grant Source: https://docs.yorlet.com/api/billing/credit-grants/create openapi-billing.json POST /v1/credit_grants Create a credit grant # List all credit grants Source: https://docs.yorlet.com/api/billing/credit-grants/list openapi-billing.json GET /v1/credit_grants List all credit grants # The credit grant object Source: https://docs.yorlet.com/api/billing/credit-grants/object # Retrieve a credit grant Source: https://docs.yorlet.com/api/billing/credit-grants/retrieve openapi-billing.json GET /v1/credit_grants/{id} Retrieve a credit grant # Update a credit grant Source: https://docs.yorlet.com/api/billing/credit-grants/update openapi-billing.json POST /v1/credit_grants/{id} Update a credit grant # Void a credit grant Source: https://docs.yorlet.com/api/billing/credit-grants/void openapi-billing.json POST /v1/credit_grants/{id}/void Void a credit grant # Create a credit note Source: https://docs.yorlet.com/api/billing/credit-notes/create openapi-billing.json POST /v1/credit_notes # Retrieve a credit note's line items Source: https://docs.yorlet.com/api/billing/credit-notes/lines openapi-billing.json GET /v1/credit_notes/{id}/lines # List all credit notes Source: https://docs.yorlet.com/api/billing/credit-notes/list openapi-billing.json GET /v1/credit_notes # The credit note object Source: https://docs.yorlet.com/api/billing/credit-notes/object # Preview a credit note Source: https://docs.yorlet.com/api/billing/credit-notes/preview openapi-billing.json POST /v1/credit_notes/preview # Retrieve a credit note Source: https://docs.yorlet.com/api/billing/credit-notes/retrieve openapi-billing.json GET /v1/credit_notes/{id} # Update a credit note Source: https://docs.yorlet.com/api/billing/credit-notes/update openapi-billing.json POST /v1/credit_notes/{id} # Void a credit note Source: https://docs.yorlet.com/api/billing/credit-notes/void openapi-billing.json POST /v1/credit_notes/{id}/void # Create a customer balance transaction Source: https://docs.yorlet.com/api/billing/customer-balance-transactions/create openapi-billing.json POST /v1/customer_balance_transactions Create a customer balance transaction # List all customer balance transactions Source: https://docs.yorlet.com/api/billing/customer-balance-transactions/list openapi-billing.json GET /v1/customer_balance_transactions List all customer balance transactions # Update a customer balance transaction Source: https://docs.yorlet.com/api/billing/customer-balance-transactions/update openapi-billing.json POST /v1/customer_balance_transactions/{id} Re-scope a customer balance transaction to an application, or remove the scope. # Create a invoice item Source: https://docs.yorlet.com/api/billing/invoice-items/create openapi-billing.json POST /v1/invoice_items Create a invoice item # Delete a invoice item Source: https://docs.yorlet.com/api/billing/invoice-items/delete openapi-billing.json DELETE /v1/invoice_items/{id} Delete a invoice item # List all invoice items Source: https://docs.yorlet.com/api/billing/invoice-items/list openapi-billing.json GET /v1/invoice_items List all invoice items # The invoice item object Source: https://docs.yorlet.com/api/billing/invoice-items/object # Retrieve a invoice item Source: https://docs.yorlet.com/api/billing/invoice-items/retrieve openapi-billing.json GET /v1/invoice_items/{id} Retrieve a invoice item # Update a invoice item Source: https://docs.yorlet.com/api/billing/invoice-items/update openapi-billing.json POST /v1/invoice_items/{id} Update a invoice item # Attach a payment to an invoice Source: https://docs.yorlet.com/api/billing/invoices/attach-payment openapi-billing.json POST /v1/invoices/{id}/attach_payment Attach a payment to an invoice # Create an invoice Source: https://docs.yorlet.com/api/billing/invoices/create openapi-billing.json POST /v1/invoices Create an invoice # Delete an invoice Source: https://docs.yorlet.com/api/billing/invoices/delete openapi-billing.json DELETE /v1/invoices/{id} Delete an invoice # Finalize an invoice Source: https://docs.yorlet.com/api/billing/invoices/finalize openapi-billing.json POST /v1/invoices/{id}/finalize Finalize an invoice # List invoices Source: https://docs.yorlet.com/api/billing/invoices/list openapi-billing.json GET /v1/invoices List invoices # Mark an invoice as paid Source: https://docs.yorlet.com/api/billing/invoices/mark-paid openapi-billing.json POST /v1/invoices/{id}/mark_paid Mark an invoice as paid # Mark an invoice as uncollectible Source: https://docs.yorlet.com/api/billing/invoices/mark-uncollectible openapi-billing.json POST /v1/invoices/{id}/mark_uncollectible Mark an invoice as uncollectible # Void an invoice Source: https://docs.yorlet.com/api/billing/invoices/mark-void openapi-billing.json POST /v1/invoices/{id}/void Void an invoice # The invoice object Source: https://docs.yorlet.com/api/billing/invoices/object # Retrieve an invoice Source: https://docs.yorlet.com/api/billing/invoices/retrieve openapi-billing.json GET /v1/invoices/{id} Retrieve an invoice # Retrieve an upcoming invoice Source: https://docs.yorlet.com/api/billing/invoices/retrieve-upcoming openapi-billing.json GET /v1/invoices/upcoming Retrieve an upcoming invoice # Retry failed invoice transfers Source: https://docs.yorlet.com/api/billing/invoices/retry-transfers openapi-billing.json POST /v1/invoices/{id}/retry_transfers Retry failed or stuck (processing) owner transfers for a paid invoice. Successfully completed slices are left untouched. # Send an invoice Source: https://docs.yorlet.com/api/billing/invoices/send openapi-billing.json POST /v1/invoices/{id}/send Send an invoice # Update an invoice Source: https://docs.yorlet.com/api/billing/invoices/update openapi-billing.json POST /v1/invoices/{id} Update an invoice # Accept a payment plan Source: https://docs.yorlet.com/api/billing/payment-plans/accept openapi-billing.json POST /v1/payment_plans/{id}/accept Accepts a proposed plan and starts collecting installments. Any installment already due is collected immediately. # Cancel a payment plan Source: https://docs.yorlet.com/api/billing/payment-plans/cancel openapi-billing.json POST /v1/payment_plans/{id}/cancel Stops collecting installments and returns the recovery case to open. # Create a payment plan Source: https://docs.yorlet.com/api/billing/payment-plans/create openapi-billing.json POST /v1/payment_plans Proposes a plan for a recovery case. The plan only starts collecting once it is accepted. # List all payment plans Source: https://docs.yorlet.com/api/billing/payment-plans/list openapi-billing.json GET /v1/payment_plans # The payment plan object Source: https://docs.yorlet.com/api/billing/payment-plans/object # Retrieve a payment plan Source: https://docs.yorlet.com/api/billing/payment-plans/retrieve openapi-billing.json GET /v1/payment_plans/{id} # Create a price Source: https://docs.yorlet.com/api/billing/prices/create openapi-billing.json POST /v1/prices Create a price # List all prices Source: https://docs.yorlet.com/api/billing/prices/list openapi-billing.json GET /v1/prices List all prices # The price object Source: https://docs.yorlet.com/api/billing/prices/object # Retrieve a price Source: https://docs.yorlet.com/api/billing/prices/retrieve openapi-billing.json GET /v1/prices/{id} Retrieve a price # Update a price Source: https://docs.yorlet.com/api/billing/prices/update openapi-billing.json POST /v1/prices/{id} Update a price # Create a product Source: https://docs.yorlet.com/api/billing/products/create openapi-billing.json POST /v1/products Create a product # List all products Source: https://docs.yorlet.com/api/billing/products/list openapi-billing.json GET /v1/products List all products # The product object Source: https://docs.yorlet.com/api/billing/products/object # Retrieve a product Source: https://docs.yorlet.com/api/billing/products/retrieve openapi-billing.json GET /v1/products/{id} Retrieve a product # Update a product Source: https://docs.yorlet.com/api/billing/products/update openapi-billing.json POST /v1/products/{id} Update a product # Cancel a recovery case Source: https://docs.yorlet.com/api/billing/recovery-cases/cancel openapi-billing.json POST /v1/recovery_cases/{id}/cancel Stops recovery and releases the enrolled invoices so no further success fee is charged. # Create a recovery case Source: https://docs.yorlet.com/api/billing/recovery-cases/create openapi-billing.json POST /v1/recovery_cases Enrol a customer’s past-due invoices in recovery. # List all recovery cases Source: https://docs.yorlet.com/api/billing/recovery-cases/list openapi-billing.json GET /v1/recovery_cases # The recovery case object Source: https://docs.yorlet.com/api/billing/recovery-cases/object # Pay a recovery case Source: https://docs.yorlet.com/api/billing/recovery-cases/pay openapi-billing.json POST /v1/recovery_cases/{id}/pay Settles the case in full, charging every enrolled invoice’s remaining balance to the supplied payment method. # Retrieve a recovery case Source: https://docs.yorlet.com/api/billing/recovery-cases/retrieve openapi-billing.json GET /v1/recovery_cases/{id} # Update a recovery case Source: https://docs.yorlet.com/api/billing/recovery-cases/update openapi-billing.json POST /v1/recovery_cases/{id} Update metadata or add eligible invoices to an open case. # Create a subscription item Source: https://docs.yorlet.com/api/billing/subscription-items/create openapi-billing.json POST /v1/subscription_items Create a subscription item # Delete a subscription item Source: https://docs.yorlet.com/api/billing/subscription-items/delete openapi-billing.json DELETE /v1/subscription_items/{id} Delete a subscription item # List all subscription items Source: https://docs.yorlet.com/api/billing/subscription-items/list openapi-billing.json GET /v1/subscription_items List all subscription items # The subscription item object Source: https://docs.yorlet.com/api/billing/subscription-items/object # Retrieve a subscription item Source: https://docs.yorlet.com/api/billing/subscription-items/retrieve openapi-billing.json GET /v1/subscription_items/{id} Retrieve a subscription item # Update a subscription item Source: https://docs.yorlet.com/api/billing/subscription-items/update openapi-billing.json POST /v1/subscription_items/{id} Update a subscription item # Cancel a subscription Source: https://docs.yorlet.com/api/billing/subscriptions/cancel openapi-billing.json POST /v1/subscriptions/{id}/cancel Cancel a subscription # Create a subscription Source: https://docs.yorlet.com/api/billing/subscriptions/create openapi-billing.json POST /v1/subscriptions Create a subscription # List all subscriptions Source: https://docs.yorlet.com/api/billing/subscriptions/list openapi-billing.json GET /v1/subscriptions A list object with a data property that contains an array of subscriptions. # The subscription object Source: https://docs.yorlet.com/api/billing/subscriptions/object # Progress a subscription Source: https://docs.yorlet.com/api/billing/subscriptions/progress openapi-billing.json POST /v1/subscriptions/{id}/progress Progress a subscription # Retrieve a subscription Source: https://docs.yorlet.com/api/billing/subscriptions/retrieve openapi-billing.json GET /v1/subscriptions/{id} Retrieve a subscription # Update a subscription Source: https://docs.yorlet.com/api/billing/subscriptions/update openapi-billing.json POST /v1/subscriptions/{id} Update a subscription # Create a tax rate Source: https://docs.yorlet.com/api/billing/tax-rates/create openapi-billing.json POST /v1/tax_rates Create a tax rate # List all tax rates Source: https://docs.yorlet.com/api/billing/tax-rates/list openapi-billing.json GET /v1/tax_rates List all tax rates # The tax rate object Source: https://docs.yorlet.com/api/billing/tax-rates/object # Retrieve a tax rate Source: https://docs.yorlet.com/api/billing/tax-rates/retrieve openapi-billing.json GET /v1/tax_rates/{id} Retrieve a tax rate # Update a tax rate Source: https://docs.yorlet.com/api/billing/tax-rates/update openapi-billing.json POST /v1/tax_rates/{id} Update a tax rate # Cancel a checkout session Source: https://docs.yorlet.com/api/checkout/checkout-sessions/cancel openapi-checkout.json POST /v1/checkout_sessions/{id}/cancel Cancels a checkout session. # Create a checkout session Source: https://docs.yorlet.com/api/checkout/checkout-sessions/create openapi-checkout.json POST /v1/checkout_sessions Creates a new checkout session. # List all checkout sessions Source: https://docs.yorlet.com/api/checkout/checkout-sessions/list openapi-checkout.json GET /v1/checkout_sessions Returns a list of checkout sessions. The checkout sessions are returned sorted by creation date, with the most recent checkout sessions appearing first. # The checkout session object Source: https://docs.yorlet.com/api/checkout/checkout-sessions/object # Retrieve a checkout session Source: https://docs.yorlet.com/api/checkout/checkout-sessions/retrieve openapi-checkout.json GET /v1/checkout_sessions/{id} Retrieves the checkout session with the given ID. # Update a checkout session Source: https://docs.yorlet.com/api/checkout/checkout-sessions/update openapi-checkout.json POST /v1/checkout_sessions/{id} Updates a checkout session. # Create a building Source: https://docs.yorlet.com/api/core/buildings/create openapi-core.json POST /v1/buildings # Delete a building Source: https://docs.yorlet.com/api/core/buildings/delete openapi-core.json DELETE /v1/buildings/{id} # List all buildings Source: https://docs.yorlet.com/api/core/buildings/list openapi-core.json GET /v1/buildings # The building object Source: https://docs.yorlet.com/api/core/buildings/object # Retrieve a building Source: https://docs.yorlet.com/api/core/buildings/retrieve openapi-core.json GET /v1/buildings/{id} # Update a building Source: https://docs.yorlet.com/api/core/buildings/update openapi-core.json POST /v1/buildings/{id} # Create a customer Source: https://docs.yorlet.com/api/core/customers/create openapi-core.json POST /v1/customers # Delete a customer Source: https://docs.yorlet.com/api/core/customers/delete openapi-core.json DELETE /v1/customers/{id} # List all customers Source: https://docs.yorlet.com/api/core/customers/list openapi-core.json GET /v1/customers # The customer object Source: https://docs.yorlet.com/api/core/customers/object # Retrieve a customer Source: https://docs.yorlet.com/api/core/customers/retrieve openapi-core.json GET /v1/customers/{id} # Update a customer Source: https://docs.yorlet.com/api/core/customers/update openapi-core.json POST /v1/customers/{id} # Create a document Source: https://docs.yorlet.com/api/core/documents/create openapi-core.json POST /v1/documents # Delete a document Source: https://docs.yorlet.com/api/core/documents/delete openapi-core.json DELETE /v1/documents/{id} # List all documents Source: https://docs.yorlet.com/api/core/documents/list openapi-core.json GET /v1/documents # The document object Source: https://docs.yorlet.com/api/core/documents/object # Retrieve a document Source: https://docs.yorlet.com/api/core/documents/retrieve openapi-core.json GET /v1/documents/{id} # Update a document Source: https://docs.yorlet.com/api/core/documents/update openapi-core.json POST /v1/documents/{id} # Check address availability Source: https://docs.yorlet.com/api/core/email-addresses/availability openapi-core.json GET /v1/email_addresses/availability Check whether a local-part is available on a domain. # Create an email address Source: https://docs.yorlet.com/api/core/email-addresses/create openapi-core.json POST /v1/email_addresses Provision a vanity address such as vita@yorlet.email. # Delete an email address Source: https://docs.yorlet.com/api/core/email-addresses/delete openapi-core.json DELETE /v1/email_addresses/{id} # List email addresses Source: https://docs.yorlet.com/api/core/email-addresses/list openapi-core.json GET /v1/email_addresses # Update an email address Source: https://docs.yorlet.com/api/core/email-addresses/update openapi-core.json POST /v1/email_addresses/{id} Update the display name, matching priority, or set the address as the agent identity. # Add a custom domain Source: https://docs.yorlet.com/api/core/email-domains/create openapi-core.json POST /v1/email_domains Create a custom domain and return the DNS records required to verify it. # Delete a custom domain Source: https://docs.yorlet.com/api/core/email-domains/delete openapi-core.json DELETE /v1/email_domains/{id} # List custom domains Source: https://docs.yorlet.com/api/core/email-domains/list openapi-core.json GET /v1/email_domains # Verify a custom domain Source: https://docs.yorlet.com/api/core/email-domains/verify openapi-core.json POST /v1/email_domains/{id}/verify Re-check the domain’s DNS records. # Send an email Source: https://docs.yorlet.com/api/core/emails/create openapi-core.json POST /v1/emails Send an email from a provisioned address to a customer, owner, or raw email address. # List emails Source: https://docs.yorlet.com/api/core/emails/list openapi-core.json GET /v1/emails # The message object Source: https://docs.yorlet.com/api/core/emails/object # Retrieve an email Source: https://docs.yorlet.com/api/core/emails/retrieve openapi-core.json GET /v1/emails/{id} # Create a letter template Source: https://docs.yorlet.com/api/core/letter-templates/create openapi-core.json POST /v1/letter_templates Create a reusable letter template with text, headings, and signatures. # Delete a letter template Source: https://docs.yorlet.com/api/core/letter-templates/delete openapi-core.json DELETE /v1/letter_templates/{id} # List all letter templates Source: https://docs.yorlet.com/api/core/letter-templates/list openapi-core.json GET /v1/letter_templates # The letter template object Source: https://docs.yorlet.com/api/core/letter-templates/object # Retrieve a letter template Source: https://docs.yorlet.com/api/core/letter-templates/retrieve openapi-core.json GET /v1/letter_templates/{id} # Update a letter template Source: https://docs.yorlet.com/api/core/letter-templates/update openapi-core.json POST /v1/letter_templates/{id} # Cancel a letter Source: https://docs.yorlet.com/api/core/letters/cancel openapi-core.json POST /v1/letters/{id}/cancel Cancel a letter before Pingen prints it. # Create a letter Source: https://docs.yorlet.com/api/core/letters/create openapi-core.json POST /v1/letters Create a letter from a template or content blocks. Set `auto_send` to print and post immediately. # Delete a letter Source: https://docs.yorlet.com/api/core/letters/delete openapi-core.json DELETE /v1/letters/{id} Permanently delete a draft letter. # List all letters Source: https://docs.yorlet.com/api/core/letters/list openapi-core.json GET /v1/letters # The letter object Source: https://docs.yorlet.com/api/core/letters/object # Retrieve a letter Source: https://docs.yorlet.com/api/core/letters/retrieve openapi-core.json GET /v1/letters/{id} # Send a letter Source: https://docs.yorlet.com/api/core/letters/send openapi-core.json POST /v1/letters/{id}/send Render the letter and submit it to Pingen for printing and postage. # Update a letter Source: https://docs.yorlet.com/api/core/letters/update openapi-core.json POST /v1/letters/{id} Update a draft letter. # Create a task Source: https://docs.yorlet.com/api/core/tasks/create openapi-core.json POST /v1/tasks # Delete a task Source: https://docs.yorlet.com/api/core/tasks/delete openapi-core.json DELETE /v1/tasks/{id} # List all tasks Source: https://docs.yorlet.com/api/core/tasks/list openapi-core.json GET /v1/tasks # The task object Source: https://docs.yorlet.com/api/core/tasks/object # Retrieve a task Source: https://docs.yorlet.com/api/core/tasks/retrieve openapi-core.json GET /v1/tasks/{id} # Update a task Source: https://docs.yorlet.com/api/core/tasks/update openapi-core.json POST /v1/tasks/{id} # List threads Source: https://docs.yorlet.com/api/core/threads/list openapi-core.json GET /v1/threads Returns a list of threads. Supports filtering by `channel`, `status`, `customer`, `owner`, and `assignee`. Pass `unassigned` as the assignee to return threads with no assignee. Date-range filters apply to `last_message_at`. # List timeline entries Source: https://docs.yorlet.com/api/core/threads/list-timeline-entries openapi-core.json GET /v1/threads/{id}/timeline_entries Returns paginated thread activity, newest first. Filter by `type` (`message`, `status_change`, `assignee_change`). Pass `expand[]=message` to hydrate the message object. # The thread object Source: https://docs.yorlet.com/api/core/threads/object # Retrieve a thread Source: https://docs.yorlet.com/api/core/threads/retrieve openapi-core.json GET /v1/threads/{id} Returns the thread. Pass `include[]=timeline_entries` for the first page of activity, or list `GET /v1/threads/:id/timeline_entries` for paginated history. # Update a thread Source: https://docs.yorlet.com/api/core/threads/update openapi-core.json POST /v1/threads/{id} Update a thread’s status or assignee. Each change is recorded as a timeline entry. # Create a unit group Source: https://docs.yorlet.com/api/core/unit-groups/create openapi-core.json POST /v1/unit_groups # Delete a unit group Source: https://docs.yorlet.com/api/core/unit-groups/delete openapi-core.json DELETE /v1/unit_groups/{id} # List all unit groups Source: https://docs.yorlet.com/api/core/unit-groups/list openapi-core.json GET /v1/unit_groups # The unit group object Source: https://docs.yorlet.com/api/core/unit-groups/object # Retrieve a unit group Source: https://docs.yorlet.com/api/core/unit-groups/retrieve openapi-core.json GET /v1/unit_groups/{id} # Update a unit group Source: https://docs.yorlet.com/api/core/unit-groups/update openapi-core.json POST /v1/unit_groups/{id} # List all unit owners Source: https://docs.yorlet.com/api/core/unit-owners/list openapi-core.json GET /v1/unit_owners # Update a unit owner Source: https://docs.yorlet.com/api/core/unit-owners/update openapi-core.json POST /v1/unit_owners/{id} # Apply for a unit Source: https://docs.yorlet.com/api/core/units/apply openapi-core.json POST /v1/units/{id}/apply Starts a self-serve application for a unit that has been released to the market, using the account default application configuration and contract template. The applicant is emailed a link to complete the application themselves. Requires self-serve applications to be enabled on the account, and the unit to be in the `to_let` availability state. # Create a unit Source: https://docs.yorlet.com/api/core/units/create openapi-core.json POST /v1/units Creates a unit. # Delete a unit Source: https://docs.yorlet.com/api/core/units/delete openapi-core.json DELETE /v1/units/{id} Permanently deletes a unit. This cannot be undone. # Hold a unit back from the market Source: https://docs.yorlet.com/api/core/units/hold openapi-core.json POST /v1/units/{id}/hold Holds a unit back from the market, so it is not offered to leads or applicants while works, an owner instruction, or an eviction is outstanding. # List all units Source: https://docs.yorlet.com/api/core/units/list openapi-core.json GET /v1/units Returns a list of units. The units are returned sorted by creation date, with the most recent units appearing first. # The unit object Source: https://docs.yorlet.com/api/core/units/object # Release a unit to the market Source: https://docs.yorlet.com/api/core/units/release openapi-core.json POST /v1/units/{id}/release Releases a unit to the market so it can be marketed and applied for. A unit that is still occupied can be released once its outgoing tenancy has an end date, which puts it in the `to_let` availability state ahead of the move-out. # Retrieve a unit Source: https://docs.yorlet.com/api/core/units/retrieve openapi-core.json GET /v1/units/{id} Retrieves the unit with the given ID. # Update a unit Source: https://docs.yorlet.com/api/core/units/update openapi-core.json POST /v1/units/{id} Updates the specified unit by setting the values of the parameters passed. Any parameters not provided will be left unchanged. # Create a webhook endpoint Source: https://docs.yorlet.com/api/core/webhook-endpoints/create openapi-core.json POST /v1/webhook_endpoints Creates a webhook endpoint. # Delete a webhook endpoint Source: https://docs.yorlet.com/api/core/webhook-endpoints/delete openapi-core.json DELETE /v1/webhook_endpoints/{id} Permanently deletes a webhook endpoint. This cannot be undone. # List all webhook endpoints Source: https://docs.yorlet.com/api/core/webhook-endpoints/list openapi-core.json GET /v1/webhook_endpoints Returns a list of webhook endpoints. The webhook endpoints are returned sorted by creation date, with the most recent webhook endpoints appearing first. # The webhook endpoint object Source: https://docs.yorlet.com/api/core/webhook-endpoints/object # Retrieve a webhook endpoint Source: https://docs.yorlet.com/api/core/webhook-endpoints/retrieve openapi-core.json GET /v1/webhook_endpoints/{id} Retrieves the webhook endpoint with the given ID. # Roll a webhook endpoint signing secret Source: https://docs.yorlet.com/api/core/webhook-endpoints/roll-secret openapi-core.json POST /v1/webhook_endpoints/{id}/roll_secret Generates a new signing secret for the webhook endpoint, invalidating the previous one. Use this if the existing secret has been compromised. # Update a webhook endpoint Source: https://docs.yorlet.com/api/core/webhook-endpoints/update openapi-core.json POST /v1/webhook_endpoints/{id} Updates the specified webhook endpoint by setting the values of the parameters passed. Any parameters not provided will be left unchanged. # Environments Source: https://docs.yorlet.com/api/environments Our API and Dashboard are available in two environments: | Name | API URL | Dashboard URL | | ---------- | ------------------------------------------------ | ------------------------------------------------------------ | | Sandbox | [https://api.yorlet.io](https://api.yorlet.io) | [https://dashboard.yorlet.io](https://dashboard.yorlet.io) | | Production | [https://api.yorlet.com](https://api.yorlet.com) | [https://dashboard.yorlet.com](https://dashboard.yorlet.com) | # Errors Source: https://docs.yorlet.com/api/errors ```json theme={"theme":"dracula"} { "error": { "message": "The supplied customer was not found.", "param": "customer", "type": "invalid_request" }, "status": 404 } ``` Yorlet uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate an error with Yorlet's servers. #### Attributes *
error object
The error object.
error.message string
A human-readable message providing more details about the error.
error.param string
If the error is parameter-specific, the parameter related to the error.
error.type string
The type of error returned.
*
status integer
The status code.
| Error code | Meaning | | ---------------------------------- | ------------------------------------------------------------------------ | | 400 Bad Request | The request was unacceptable, often due to missing a required parameter. | | 401 Unauthorized | No valid API key was provided. | | 403 Forbidden | The API key doesn't have permissions to perform the request. | | 404 Not Found | The requested resource doesn't exist. | | 429 Too Many Requests | Too many requests hit the API too quickly. | | 5XX Server Error | We had a problem with our server. Try again later. | # Types of events Source: https://docs.yorlet.com/api/events A complete list of the event types Yorlet sends to your webhook endpoints. This is a complete list of the events Yorlet currently sends. Subscribe to these on your [webhook endpoints](/development/webhooks) to receive notifications when they occur. ## account | Event | Description | | ------------------ | -------------------------------------- | | `account.updated` | Occurs whenever an account is updated. | ## approval | Event | Description | | -------------------- | ----------------------------------------------- | | `approval.approved` | Occurs whenever an approval is approved. | | `approval.created` | Occurs whenever an approval is created. | | `approval.denied` | Occurs whenever an approval is denied. | | `approval.executed` | Occurs whenever an approved action is executed. | ## [account\_collection](/api/owners/account-collections/object) | Event | Description | | ------------------------------ | -------------------------------------------------- | | `account_collection.approved` | Occurs whenever an account collection is approved. | | `account_collection.canceled` | Occurs whenever an account collection is canceled. | | `account_collection.created` | Occurs whenever an account collection is created. | | `account_collection.updated` | Occurs whenever an account collection is updated. | ## [application](/api/leasing/applications/object) | Event | Description | | ------------------------ | -------------------------------------------- | | `application.accepted` | Occurs whenever an application is accepted. | | `application.canceled` | Occurs whenever an application is canceled. | | `application.created` | Occurs whenever an application is created. | | `application.completed` | Occurs whenever an application is completed. | | `application.updated` | Occurs whenever an application is updated. | ## [building](/api/core/buildings/object) | Event | Description | | ------------------- | -------------------------------------- | | `building.created` | Occurs whenever a building is created. | | `building.deleted` | Occurs whenever a building is deleted. | | `building.updated` | Occurs whenever a building is updated. | ## [checkout\_session](/api/checkout/checkout-sessions/object) | Event | Description | | ----------------------------- | ------------------------------------------------ | | `checkout_session.canceled` | Occurs whenever a checkout session is canceled. | | `checkout_session.created` | Occurs whenever a checkout session is created. | | `checkout_session.completed` | Occurs whenever a checkout session is completed. | ## contract | Event | Description | | ----------------------------- | ----------------------------------------------------- | | `contract.created` | Occurs whenever a contract is created. | | `contract.completed` | Occurs whenever a contract is completed. | | `contract.out_for_signature` | Occurs whenever a contract is sent out for signature. | | `contract.voided` | Occurs whenever a contract is voided. | | `contract.unvoided` | Occurs whenever a contract is unvoided. | ## [customer](/api/core/customers/object) | Event | Description | | ------------------- | -------------------------------------- | | `customer.created` | Occurs whenever a customer is created. | | `customer.deleted` | Occurs whenever a customer is deleted. | | `customer.updated` | Occurs whenever a customer is updated. | ## message | Event | Description | | ------------------- | --------------------------------------------------------- | | `message.received` | Occurs whenever an inbound message is received. | | `message.sent` | Occurs whenever a message is sent through the Emails API. | ## dispute | Event | Description | | ------------------- | -------------------------------------- | | `dispute.created` | Occurs whenever a dispute is created. | | `dispute.resolved` | Occurs whenever a dispute is resolved. | ## [invoice](/api/billing/invoices/object) | Event | Description | | ------------------------------ | ---------------------------------------------------------- | | `invoice.created` | Occurs whenever a invoice is created. | | `invoice.finalization_failed` | Occurs whenever a invoice fails finalization. | | `invoice.finalized` | Occurs whenever a invoice is finalized and marked as open. | | `invoice.paid` | Occurs whenever a invoice is paid. | | `invoice.payment_failed` | Occurs whenever a invoice payment fails. | | `invoice.sent` | Occurs whenever an invoice email is sent. | | `invoice.voided` | Occurs whenever a invoice is voided. | ## [leads.enquiry](/api/leads/leads-enquiries/object) | Event | Description | | ------------------------- | ------------------------------------------------------------------------ | | `leads.enquiry.attached` | Occurs whenever a qualification configuration is attached to an enquiry. | | `leads.enquiry.created` | Occurs whenever an enquiry is created. | | `leads.enquiry.updated` | Occurs whenever an enquiry is updated. | ## [leads.viewing](/api/leads/leads-viewings/object) | Event | Description | | ------------------------ | ------------------------------------- | | `leads.viewing.created` | Occurs whenever a viewing is created. | | `leads.viewing.updated` | Occurs whenever a viewing is updated. | ## [letter](/api/core/letters/object) | Event | Description | | ------------------ | --------------------------------------------------------------- | | `letter.canceled` | Occurs whenever a letter is canceled. | | `letter.created` | Occurs whenever a letter is created. | | `letter.failed` | Occurs whenever sending a letter fails. | | `letter.sent` | Occurs whenever a letter is submitted for printing and postage. | ## [maintenance\_issue](/api/maintenance/maintenance-issues/object) | Event | Description | | ----------------------------- | ------------------------------------------------ | | `maintenance.issue.created` | Occurs whenever a maintenance issue is created. | | `maintenance.issue.deleted` | Occurs whenever a maintenance issue is deleted. | | `maintenance.issue.resolved` | Occurs whenever a maintenance issue is resolved. | | `maintenance.issue.updated` | Occurs whenever a maintenance issue is updated. | ## [owners](/api/owners/owners/object) | Event | Description | | ---------------- | ------------------------------------ | | `owner.created` | Occurs whenever an owner is created. | | `owner.updated` | Occurs whenever an owner is updated. | ## [payment\_method](/api/payments/payment-methods/object) | Event | Description | | ---------------------------- | ---------------------------------------------------- | | `payment_method.chargeable` | Occurs whenever a payment method becomes chargeable. | | `payment_method.created` | Occurs whenever a payment method is created. | | `payment_method.failed` | Occurs whenever a payment method fails. | ## payment\_method\_transaction | Event | Description | | ------------------------------------- | -------------------------------------------------------- | | `payment_method_transaction.created` | Occurs whenever a payment method transaction is created. | ## [payment\_session](/api/payments/payment-sessions/object) | Event | Description | | -------------------------- | --------------------------------------------- | | `payment_session.created` | Occurs whenever a payment session is created. | | `payment_session.paid` | Occurs whenever a payment session is paid. | ## [renewal\_intent](/api/leasing/renewal-intents/object) | Event | Description | | --------------------------- | ----------------------------------------------- | | `renewal_intent.canceled` | Occurs whenever an renewal intent is canceled. | | `renewal_intent.created` | Occurs whenever an renewal intent is created. | | `renewal_intent.completed` | Occurs whenever an renewal intent is completed. | | `renewal_intent.updated` | Occurs whenever an renewal intent is updated. | ## [subscription](/api/billing/subscriptions/object) | Event | Description | | ------------------------- | -------------------------------------------- | | `subscription.canceled` | Occurs whenever a subscription is canceled. | | `subscription.completed` | Occurs whenever a subscription is completed. | | `subscription.created` | Occurs whenever a subscription is created. | | `subscription.updated` | Occurs whenever a subscription is updated. | ## [tenancy](/api/leasing/tenancies/object) | Event | Description | | -------------------- | ---------------------------------------- | | `tenancy.activated` | Occurs whenever an tenancy is activated. | | `tenancy.canceled` | Occurs whenever an tenancy is canceled. | | `tenancy.created` | Occurs whenever an tenancy is created. | | `tenancy.completed` | Occurs whenever an tenancy is completed. | | `tenancy.updated` | Occurs whenever an tenancy is updated. | ## thread | Event | Description | | ----------------- | ------------------------------------ | | `thread.created` | Occurs whenever a thread is created. | | `thread.updated` | Occurs whenever a thread is updated. | ## [transaction](/api/payments/transactions/object) | Event | Description | | ----------------------------- | -------------------------------------------- | | `transaction.canceled` | Occurs whenever a transaction is canceled. | | `transaction.created` | Occurs whenever a transaction is created. | | `transaction.payment_failed` | Occurs whenever a transaction fails. | | `transaction.processing` | Occurs whenever a transaction is processing. | | `transaction.succeeded` | Occurs whenever a transaction has succeeded. | ## [unit](/api/core/units/object) | Event | Description | | ---------------- | ----------------------------------- | | `unit.archived` | Occurs whenever a unit is archived. | | `unit.created` | Occurs whenever a unit is created. | | `unit.deleted` | Occurs whenever a unit is deleted. | | `unit.updated` | Occurs whenever a unit is updated. | # Expanding objects Source: https://docs.yorlet.com/api/expanding ```bash theme={"theme":"dracula"} curl https://api.yorlet.com/v1/applications/app_ki8ufmnsFtvwQmmL \ -H "Authorization: Bearer {access_token}" \ -d "expand[]"=unit \ -G ``` Many objects contain the ID of a related object in their response properties. For example, an Application may have an associated Unit ID. Those objects can be expanded inline with the expand request parameter. Objects that can be expanded are noted in this documentation. This parameter is available on all API requests, and applies to the response of that request only. You can expand multiple objects at once by identifying multiple items in the expand array. # Create a verification session Source: https://docs.yorlet.com/api/guardrails/verification-sessions/create openapi-guardrails.json POST /v1/verification_sessions # List all verification sessions Source: https://docs.yorlet.com/api/guardrails/verification-sessions/list openapi-guardrails.json GET /v1/verification_sessions # The verification session object Source: https://docs.yorlet.com/api/guardrails/verification-sessions/object # Retrieve a verification session Source: https://docs.yorlet.com/api/guardrails/verification-sessions/retrieve openapi-guardrails.json GET /v1/verification_sessions/{id} # Idempotency Source: https://docs.yorlet.com/api/idempotency ```shell theme={"theme":"dracula"} curl https://api.yorlet.com/v1/customers \ -H "Authorization: Bearer {access_token}" \ -H "Idempotency-Key: {unique_key}" \ ``` The Yorlet API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to create a new enquiry does not respond due to a network connection error, you can retry the request with the same idempotency key to guarantee that no more than one enquiry is created. To perform an idempotent request, provide an additional Idempotency-Key element to the request header. Yorlet's idempotency architecture works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, including 500 errors. An idempotency key is a unique value generated by the client which the server uses to recognise subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions. Keys expire after 24 hours, so a new request is generated if a key is reused outside of that time frame. The idempotency layer compares incoming parameters to those of the original request and errors unless they're the same to prevent accidental misuse. Results are only saved if an API endpoint started executing. If incoming parameters failed validation, or the request conflicted with another that was executing concurrently, no idempotent result is saved because no API endpoint began execution. It is safe to retry these requests. All POST requests accept idempotency keys. Sending idempotency keys in GET and DELETE requests has no effect and should be avoided, as these requests are idempotent by definition. # Introduction Source: https://docs.yorlet.com/api/introduction Welcome to the Yorlet API Reference. The API is designed to use standard HTTP protocols and return JSON payloads in response to HTTP requests, and are internally implemented based on the RESTful principles. These docs are for the latest version of the API. To use this API please [upgrade to the latest version](/development/versioning) or include the `Yorlet-Version` header with the value of `2025-08-21` or higher. We recommend building against this version of the API to ensure compatibility with the latest features and improvements. You can view the legacy docs [here](https://api-docs.yorlet.com). Learn how to version your API requests Learn about the changes introduced in each version of the API # Attach a qualification configuration to an enquiry Source: https://docs.yorlet.com/api/leads/leads-enquiries/attach openapi-leads.json POST /v1/leads/enquiries/{id}/attach Attach a qualification configuration to a leads enquiry. Optionally emails the hosted qualification form to the lead. # Create a viewing booking link for an enquiry Source: https://docs.yorlet.com/api/leads/leads-enquiries/booking-link openapi-leads.json POST /v1/leads/enquiries/{id}/booking_link Returns the self-serve viewing booking link for the enquiry, creating it if one does not exist yet. Optionally emails the link to the lead. # Create an enquiry Source: https://docs.yorlet.com/api/leads/leads-enquiries/create openapi-leads.json POST /v1/leads/enquiries Create a new enquiry. Can be created independently or via a qualification form. # List all enquiries Source: https://docs.yorlet.com/api/leads/leads-enquiries/list openapi-leads.json GET /v1/leads/enquiries Returns a list of enquiries. The enquiries are returned sorted by creation date. # The leads.enquiry object Source: https://docs.yorlet.com/api/leads/leads-enquiries/object # Create a qualification form link for an enquiry Source: https://docs.yorlet.com/api/leads/leads-enquiries/qualification-link openapi-leads.json POST /v1/leads/enquiries/{id}/qualification_link Returns the hosted qualification form link for the enquiry, creating it if one does not exist yet. Optionally emails the link to the lead. # Submit qualification answers for an enquiry Source: https://docs.yorlet.com/api/leads/leads-enquiries/qualify openapi-leads.json POST /v1/leads/enquiries/{id}/qualify Records qualification answers against an existing enquiry from the hosted qualification form. # Retrieve an enquiry Source: https://docs.yorlet.com/api/leads/leads-enquiries/retrieve openapi-leads.json GET /v1/leads/enquiries/{id} Retrieves the details of an existing enquiry. # Transition an enquiry status Source: https://docs.yorlet.com/api/leads/leads-enquiries/status openapi-leads.json POST /v1/leads/enquiries/{id}/status Moves an enquiry through the lead pipeline. Records review metadata for qualified/disqualified. # Update an enquiry Source: https://docs.yorlet.com/api/leads/leads-enquiries/update openapi-leads.json POST /v1/leads/enquiries/{id} Updates the specified enquiry. Can be used to apply a qualification configuration and add answers. # Create a leads qualification configuration Source: https://docs.yorlet.com/api/leads/leads-qualification-configurations/create openapi-leads.json POST /v1/leads/qualification_configurations # List all leads qualification configurations Source: https://docs.yorlet.com/api/leads/leads-qualification-configurations/list openapi-leads.json GET /v1/leads/qualification_configurations # The leads.qualification configuration object Source: https://docs.yorlet.com/api/leads/leads-qualification-configurations/object # Retrieve a leads qualification configuration Source: https://docs.yorlet.com/api/leads/leads-qualification-configurations/retrieve openapi-leads.json GET /v1/leads/qualification_configurations/{id} # Roll a leads qualification configuration form token Source: https://docs.yorlet.com/api/leads/leads-qualification-configurations/roll-token openapi-leads.json POST /v1/leads/qualification_configurations/{id}/token Issues a new hosted form token and immediately invalidates the previous one. # Update a leads qualification configuration Source: https://docs.yorlet.com/api/leads/leads-qualification-configurations/update openapi-leads.json POST /v1/leads/qualification_configurations/{id} # Create a qualification route Source: https://docs.yorlet.com/api/leads/leads-qualification-routes/create openapi-leads.json POST /v1/leads/qualification_routes Create a route that attaches a qualification configuration to matching inbound enquiries. # List all qualification routes Source: https://docs.yorlet.com/api/leads/leads-qualification-routes/list openapi-leads.json GET /v1/leads/qualification_routes Returns a list of qualification routes, sorted by priority. # The leads.qualification route object Source: https://docs.yorlet.com/api/leads/leads-qualification-routes/object # Retrieve a qualification route Source: https://docs.yorlet.com/api/leads/leads-qualification-routes/retrieve openapi-leads.json GET /v1/leads/qualification_routes/{id} Retrieves the details of an existing qualification route. # Update a qualification route Source: https://docs.yorlet.com/api/leads/leads-qualification-routes/update openapi-leads.json POST /v1/leads/qualification_routes/{id} Updates the specified qualification route. # Book a viewing Source: https://docs.yorlet.com/api/leads/leads-viewings/create openapi-leads.json POST /v1/leads/viewings Books a viewing against an enquiry. Bookings made with a viewing booking link must fall on an available slot. # List all viewings Source: https://docs.yorlet.com/api/leads/leads-viewings/list openapi-leads.json GET /v1/leads/viewings Returns a list of viewings. The viewings are returned sorted by start time. # The leads.viewing object Source: https://docs.yorlet.com/api/leads/leads-viewings/object # Retrieve a viewing Source: https://docs.yorlet.com/api/leads/leads-viewings/retrieve openapi-leads.json GET /v1/leads/viewings/{id} Retrieves the details of an existing viewing. # List bookable viewing slots Source: https://docs.yorlet.com/api/leads/leads-viewings/slots openapi-leads.json GET /v1/leads/viewings/slots Returns the slots a lead can book, derived from the account's weekly viewing availability minus anything already booked. # Transition a viewing status Source: https://docs.yorlet.com/api/leads/leads-viewings/status openapi-leads.json POST /v1/leads/viewings/{id}/status Records the outcome of a viewing. A viewing booking link may only be used to cancel the viewing it belongs to. # Update a viewing Source: https://docs.yorlet.com/api/leads/leads-viewings/update openapi-leads.json POST /v1/leads/viewings/{id} Updates the specified viewing. Used to reschedule, reassign or annotate a viewing. # Create an application configuration Source: https://docs.yorlet.com/api/leasing/application-configurations/create openapi-leasing.json POST /v1/application_configurations Create an application configuration # List all application configurations Source: https://docs.yorlet.com/api/leasing/application-configurations/list openapi-leasing.json GET /v1/application_configurations List all application configurations # The application configuration object Source: https://docs.yorlet.com/api/leasing/application-configurations/object # Retrieve an application configuration Source: https://docs.yorlet.com/api/leasing/application-configurations/retrieve openapi-leasing.json GET /v1/application_configurations/{id} Retrieve an application configuration # Update an application configuration Source: https://docs.yorlet.com/api/leasing/application-configurations/update openapi-leasing.json POST /v1/application_configurations/{id} Update an application configuration # Create an application session Source: https://docs.yorlet.com/api/leasing/application-sessions/create openapi-leasing.json POST /v1/application_sessions Creates a new application session for the specified application. # Create an application event Source: https://docs.yorlet.com/api/leasing/applications-events/create openapi-leasing.json POST /v1/applications/{id}/events # List all application events Source: https://docs.yorlet.com/api/leasing/applications-events/list openapi-leasing.json GET /v1/applications/{id}/events # Accept an application Source: https://docs.yorlet.com/api/leasing/applications/accept openapi-leasing.json POST /v1/applications/{id}/accept # Cancel an application Source: https://docs.yorlet.com/api/leasing/applications/cancel openapi-leasing.json POST /v1/applications/{id}/cancel # Complete an application Source: https://docs.yorlet.com/api/leasing/applications/complete openapi-leasing.json POST /v1/applications/{id}/complete # Create an application Source: https://docs.yorlet.com/api/leasing/applications/create openapi-leasing.json POST /v1/applications # List all applications Source: https://docs.yorlet.com/api/leasing/applications/list openapi-leasing.json GET /v1/applications Returns a list of applications. Supports filtering by assignee, building, customer, status, type, unit, and current step. Pass `unassigned` as the assignee to return applications with no assignee. # List all applicants for an application Source: https://docs.yorlet.com/api/leasing/applications/list-applicants openapi-leasing.json GET /v1/applications/{id}/applicants # Mark an applicant as paid Source: https://docs.yorlet.com/api/leasing/applications/mark-applicant-paid openapi-leasing.json POST /v1/applications/{id}/applicants/{applicantId}/mark_paid # The application object Source: https://docs.yorlet.com/api/leasing/applications/object # Progress an application Source: https://docs.yorlet.com/api/leasing/applications/progress openapi-leasing.json POST /v1/applications/{id}/progress Advance the application to the next step. Used to progress past waitpoints in configuration mode. # Retrieve an application Source: https://docs.yorlet.com/api/leasing/applications/retrieve openapi-leasing.json GET /v1/applications/{id} # Retrieve an applicant Source: https://docs.yorlet.com/api/leasing/applications/retrieve-applicant openapi-leasing.json GET /v1/applications/{id}/applicants/{applicantId} # Revert a step Source: https://docs.yorlet.com/api/leasing/applications/revert-step openapi-leasing.json POST /v1/applications/{id}/steps/{stepId}/revert Roll back a skipped step, or a complete money step whose requirements are no longer met, so the application re-enters it. Configuration mode only. # Update an application Source: https://docs.yorlet.com/api/leasing/applications/update openapi-leasing.json POST /v1/applications/{id} # Update an applicant Source: https://docs.yorlet.com/api/leasing/applications/update-applicant openapi-leasing.json POST /v1/applications/{id}/applicants/{applicantId} # Accept a deposit charge Source: https://docs.yorlet.com/api/leasing/deposits-charges/accept openapi-leasing.json POST /v1/deposits/{id}/charges/{chargeId}/accept Accept the deposit charge with the given ID. # Cancel a deposit charge Source: https://docs.yorlet.com/api/leasing/deposits-charges/cancel openapi-leasing.json POST /v1/deposits/{id}/charges/{chargeId}/cancel Cancel the deposit charge with the given ID. # Create a deposit charge Source: https://docs.yorlet.com/api/leasing/deposits-charges/create openapi-leasing.json POST /v1/deposits/{id}/charges Creates a new deposit charge. # Delete a deposit charge Source: https://docs.yorlet.com/api/leasing/deposits-charges/delete openapi-leasing.json DELETE /v1/deposits/{id}/charges/{chargeId} Deletes the deposit charge with the given ID. # Dispute a deposit charge Source: https://docs.yorlet.com/api/leasing/deposits-charges/dispute openapi-leasing.json POST /v1/deposits/{id}/charges/{chargeId}/dispute Dispute the deposit charge with the given ID. # List all deposit charges Source: https://docs.yorlet.com/api/leasing/deposits-charges/list openapi-leasing.json GET /v1/deposits/{id}/charges A list of deposit charges. The deposit charges are returned sorted by creation date, with the most recent deposit charges appearing first. # The deposit charge object Source: https://docs.yorlet.com/api/leasing/deposits-charges/object # Retrieve a deposit charge Source: https://docs.yorlet.com/api/leasing/deposits-charges/retrieve openapi-leasing.json GET /v1/deposits/{id}/charges/{chargeId} Retrieves the deposit charge with the given ID. # Update a deposit charge Source: https://docs.yorlet.com/api/leasing/deposits-charges/update openapi-leasing.json POST /v1/deposits/{id}/charges/{chargeId} Updates the deposit charge with the given ID. # Activate a deposit Source: https://docs.yorlet.com/api/leasing/deposits/activate openapi-leasing.json POST /v1/deposits/{id}/activate Activate a deposit. # Create a deposit Source: https://docs.yorlet.com/api/leasing/deposits/create openapi-leasing.json POST /v1/deposits Creates a new deposit. # Delete a deposit Source: https://docs.yorlet.com/api/leasing/deposits/delete openapi-leasing.json DELETE /v1/deposits/{id} Deletes the deposit with the given ID. # List all deposits Source: https://docs.yorlet.com/api/leasing/deposits/list openapi-leasing.json GET /v1/deposits A list of deposits. The deposits are returned sorted by creation date, with the most recent deposits appearing first. # List TDS branches Source: https://docs.yorlet.com/api/leasing/deposits/list-tds-branches openapi-leasing.json GET /v1/deposits/integrations/tds/branches Lists the branches available for the configured TDS member. # Mark a deposit as returned Source: https://docs.yorlet.com/api/leasing/deposits/mark-returned openapi-leasing.json POST /v1/deposits/{id}/mark_returned Marking a deposit as returned is the final step in returning a deposit. # The deposit object Source: https://docs.yorlet.com/api/leasing/deposits/object # Retrieve a deposit Source: https://docs.yorlet.com/api/leasing/deposits/retrieve openapi-leasing.json GET /v1/deposits/{id} Retrieves the deposit with the given ID. # Return a deposit Source: https://docs.yorlet.com/api/leasing/deposits/return openapi-leasing.json POST /v1/deposits/{id}/return Return a deposit. # Mark a deposit as transferred Source: https://docs.yorlet.com/api/leasing/deposits/transfer openapi-leasing.json POST /v1/deposits/{id}/transfer Marking a deposit as transferred is the final step in activating certain deposits. # Update a deposit Source: https://docs.yorlet.com/api/leasing/deposits/update openapi-leasing.json POST /v1/deposits/{id} Updates the deposit with the given ID. # Create a guarantor Source: https://docs.yorlet.com/api/leasing/guarantors/create openapi-leasing.json POST /v1/guarantors # Detach a guarantor Source: https://docs.yorlet.com/api/leasing/guarantors/detach openapi-leasing.json POST /v1/guarantors/{id}/detach # The guarantor object Source: https://docs.yorlet.com/api/leasing/guarantors/object # Retrieve a guarantor Source: https://docs.yorlet.com/api/leasing/guarantors/retrieve openapi-leasing.json GET /v1/guarantors/{id} # Cancel a reference Source: https://docs.yorlet.com/api/leasing/references/cancel openapi-leasing.json POST /v1/references/{id}/cancel # Create a reference Source: https://docs.yorlet.com/api/leasing/references/create openapi-leasing.json POST /v1/references # List all references Source: https://docs.yorlet.com/api/leasing/references/list openapi-leasing.json GET /v1/references # The reference object Source: https://docs.yorlet.com/api/leasing/references/object # Retrieve a reference Source: https://docs.yorlet.com/api/leasing/references/retrieve openapi-leasing.json GET /v1/references/{id} # Update a reference Source: https://docs.yorlet.com/api/leasing/references/update openapi-leasing.json POST /v1/references/{id} # Cancel a renewal intent Source: https://docs.yorlet.com/api/leasing/renewal-intents/cancel openapi-leasing.json POST /v1/renewal_intents/{id}/cancel Permanently cancel a renewal intent. This cannot be undone. # Complete a renewal intent Source: https://docs.yorlet.com/api/leasing/renewal-intents/complete openapi-leasing.json POST /v1/renewal_intents/{id}/complete Completes a renewal intent. For no_renewal type, marks as complete. For rent_increase type, marks as effective (requires status to be accepted or tribunal_decided). This cannot be undone. # Create a renewal intent Source: https://docs.yorlet.com/api/leasing/renewal-intents/create openapi-leasing.json POST /v1/renewal_intents Creates a new renewal intent. Pass type "rent_increase" to create a rent review intent. Rent review intents include a due_at date indicating the suggested notice serving date. # List all renewal intents Source: https://docs.yorlet.com/api/leasing/renewal-intents/list openapi-leasing.json GET /v1/renewal_intents Returns a list of renewal intents. Supports filtering by status (single via `status` or multiple via `statuses`), excluding statuses via `exclude_statuses`, type, assignee, unit, and building. Renewal intents are returned sorted by creation date, with the most recent first. # The renewal intent object Source: https://docs.yorlet.com/api/leasing/renewal-intents/object # Retrieve a renewal intent Source: https://docs.yorlet.com/api/leasing/renewal-intents/retrieve openapi-leasing.json GET /v1/renewal_intents/{id} Retrieves the renewal intent with the given ID. # Reverse an effective rent increase Source: https://docs.yorlet.com/api/leasing/renewal-intents/reverse openapi-leasing.json POST /v1/renewal_intents/{id}/reverse Reverses a rent increase that has already taken effect. This is intended for cases where a tenant referred the increase to a tribunal before the effective date but did not communicate this in time. The intent status is reverted to challenged, the subscription schedule change is undone, and the intent is re-linked to the tenancy. Only applicable to rent_increase intents in effective status. # Send the rent increase notice email Source: https://docs.yorlet.com/api/leasing/renewal-intents/send-notice-email openapi-leasing.json POST /v1/renewal_intents/{id}/send_notice_email Sends (or re-sends) the rent increase notice email with the Form 4 attached to the tenants on the source tenancy. Only valid for rent_increase intents that have already had notice served and have a Form 4 attached. # Update a renewal intent Source: https://docs.yorlet.com/api/leasing/renewal-intents/update openapi-leasing.json POST /v1/renewal_intents/{id} Updates the specified renewal intent. For rent_increase type, you can transition the status through the rent increase flow (pending -> notice_served -> accepted/challenged -> effective) and set rent increase fields. The notice_served_at date cannot be in the past. By default, notice can only be served on or after the system-suggested due date, and the effective_date must be at least 12 months after the last rent increase or tenancy start. Accounts can enable the renewals "allow_early_notice" setting to waive those timing restrictions and serve notice at any time without enforcing the 12-month cycle. The effective_date must always be at least 2 months after notice_served_at. Pass send_form_4=true alongside a status=notice_served transition to email the tenants the rent increase notice with the Form 4 attached. # Cancel a tenancy Source: https://docs.yorlet.com/api/leasing/tenancies/cancel openapi-leasing.json POST /v1/tenancies/{id}/cancel Cancels a tenancy, optionally scheduling the cancellation for a future date. By default, associated subscriptions are also canceled and a credit note is generated for any prepaid period. # List all tenancies Source: https://docs.yorlet.com/api/leasing/tenancies/list openapi-leasing.json GET /v1/tenancies Returns a list of tenancies. Supports filtering by status, assignee, building, customer, unit, and date range. Tenancies are returned sorted by creation date, with the most recent first. # The tenancy object Source: https://docs.yorlet.com/api/leasing/tenancies/object # Retrieve a tenancy Source: https://docs.yorlet.com/api/leasing/tenancies/retrieve openapi-leasing.json GET /v1/tenancies/{id} Retrieves the tenancy with the given ID. # Send compliance documents Source: https://docs.yorlet.com/api/leasing/tenancies/send-compliance openapi-leasing.json POST /v1/tenancies/{id}/send_compliance Emails the unit's current compliance documents (EPC, electric safety, gas safety) to the tenancy's customers. # Stop a scheduled tenancy cancellation Source: https://docs.yorlet.com/api/leasing/tenancies/stop-cancellation openapi-leasing.json POST /v1/tenancies/{id}/stop_cancellation Stops a pending (future-dated) tenancy cancellation, clearing the scheduled cancellation date and reversing the scheduled cancellation of any still-active associated subscriptions. # Update a tenancy Source: https://docs.yorlet.com/api/leasing/tenancies/update openapi-leasing.json POST /v1/tenancies/{id} Updates the assignee or review configuration on a tenancy. Most other fields are managed via the lease changes sub-resource or the application that created the tenancy. # Create a message Source: https://docs.yorlet.com/api/loyalty/loyalty-messages/create openapi-loyalty.json POST /v1/loyalty/messages Create and send a message to a building or a customer with an active tenancy # List all messages Source: https://docs.yorlet.com/api/loyalty/loyalty-messages/list openapi-loyalty.json GET /v1/loyalty/messages List all messages # The loyalty.message object Source: https://docs.yorlet.com/api/loyalty/loyalty-messages/object # Retrieve a message Source: https://docs.yorlet.com/api/loyalty/loyalty-messages/retrieve openapi-loyalty.json GET /v1/loyalty/messages/{id} Retrieve a message # Create a loyalty program event adjustment Source: https://docs.yorlet.com/api/loyalty/loyalty-program-event-adjustments/create openapi-loyalty.json POST /v1/loyalty/program_event_adjustments Create a loyalty program event adjustment # Create a loyalty program event Source: https://docs.yorlet.com/api/loyalty/loyalty-program-events/create openapi-loyalty.json POST /v1/loyalty/program_events Create a loyalty program event # List all loyalty program events Source: https://docs.yorlet.com/api/loyalty/loyalty-program-events/list openapi-loyalty.json GET /v1/loyalty/program_events List all loyalty program events # Create a loyalty program Source: https://docs.yorlet.com/api/loyalty/loyalty-programs/create openapi-loyalty.json POST /v1/loyalty/programs Create a loyalty program # List all loyalty programs Source: https://docs.yorlet.com/api/loyalty/loyalty-programs/list openapi-loyalty.json GET /v1/loyalty/programs List all loyalty programs # The loyalty.program object Source: https://docs.yorlet.com/api/loyalty/loyalty-programs/object # Retrieve a loyalty program Source: https://docs.yorlet.com/api/loyalty/loyalty-programs/retrieve openapi-loyalty.json GET /v1/loyalty/programs/{id} Retrieve a loyalty program # Update a loyalty program Source: https://docs.yorlet.com/api/loyalty/loyalty-programs/update openapi-loyalty.json POST /v1/loyalty/programs/{id} Update a loyalty program # Create a resident Source: https://docs.yorlet.com/api/loyalty/loyalty-residents/create openapi-loyalty.json POST /v1/loyalty/residents Create a resident # List all residents Source: https://docs.yorlet.com/api/loyalty/loyalty-residents/list openapi-loyalty.json GET /v1/loyalty/residents List all residents # The resident object Source: https://docs.yorlet.com/api/loyalty/loyalty-residents/object # Retrieve a resident Source: https://docs.yorlet.com/api/loyalty/loyalty-residents/retrieve openapi-loyalty.json GET /v1/loyalty/residents/{id} Retrieve a resident # Update a resident Source: https://docs.yorlet.com/api/loyalty/loyalty-residents/update openapi-loyalty.json POST /v1/loyalty/residents/{id} Update a resident # Create a tier Source: https://docs.yorlet.com/api/loyalty/loyalty-tiers/create openapi-loyalty.json POST /v1/loyalty/tiers Create a tier # List all tiers Source: https://docs.yorlet.com/api/loyalty/loyalty-tiers/list openapi-loyalty.json GET /v1/loyalty/tiers List all tiers # The loyalty.tier object Source: https://docs.yorlet.com/api/loyalty/loyalty-tiers/object # Retrieve a tier Source: https://docs.yorlet.com/api/loyalty/loyalty-tiers/retrieve openapi-loyalty.json GET /v1/loyalty/tiers/{id} Retrieve a tier # Update a tier Source: https://docs.yorlet.com/api/loyalty/loyalty-tiers/update openapi-loyalty.json POST /v1/loyalty/tiers/{id} Update a tier # Create a maintenance issue Source: https://docs.yorlet.com/api/maintenance/maintenance-issues/create openapi-maintenance.json POST /v1/maintenance/issues # Delete a maintenance issue Source: https://docs.yorlet.com/api/maintenance/maintenance-issues/delete openapi-maintenance.json DELETE /v1/maintenance/issues/{id} # List all maintenance issues Source: https://docs.yorlet.com/api/maintenance/maintenance-issues/list openapi-maintenance.json GET /v1/maintenance/issues # The maintenance.issue object Source: https://docs.yorlet.com/api/maintenance/maintenance-issues/object # Retrieve a maintenance issue Source: https://docs.yorlet.com/api/maintenance/maintenance-issues/retrieve openapi-maintenance.json GET /v1/maintenance/issues/{id} # Update a maintenance issue Source: https://docs.yorlet.com/api/maintenance/maintenance-issues/update openapi-maintenance.json POST /v1/maintenance/issues/{id} # Cancel an account collection subscription Source: https://docs.yorlet.com/api/owners/account-collection-subscriptions/cancel openapi-owners.json POST /v1/account_collection_subscriptions/{id}/cancel Cancels an account collection subscription. # Create an account collection subscription Source: https://docs.yorlet.com/api/owners/account-collection-subscriptions/create openapi-owners.json POST /v1/account_collection_subscriptions Creates a new account collection subscription. # List all account collection subscriptions Source: https://docs.yorlet.com/api/owners/account-collection-subscriptions/list openapi-owners.json GET /v1/account_collection_subscriptions Returns a list of account collection subscriptions. The account collection subscriptions are returned sorted by creation date, with the most recent appearing first. # The account collection subscription object Source: https://docs.yorlet.com/api/owners/account-collection-subscriptions/object # Retrieve an account collection subscription Source: https://docs.yorlet.com/api/owners/account-collection-subscriptions/retrieve openapi-owners.json GET /v1/account_collection_subscriptions/{id} Retrieves the account collection subscription with the given ID. # Approve an account collection Source: https://docs.yorlet.com/api/owners/account-collections/approve openapi-owners.json POST /v1/account_collections/{id}/approve Approves a pending account collection. # Cancel an account collection Source: https://docs.yorlet.com/api/owners/account-collections/cancel openapi-owners.json POST /v1/account_collections/{id}/cancel Cancels a pending account collection. # Create an account collection Source: https://docs.yorlet.com/api/owners/account-collections/create openapi-owners.json POST /v1/account_collections Creates a new account collection. # List all account collections Source: https://docs.yorlet.com/api/owners/account-collections/list openapi-owners.json GET /v1/account_collections Returns a list of account collections. The account collections are returned sorted by creation date, with the most recent account collections appearing first. # The account collection object Source: https://docs.yorlet.com/api/owners/account-collections/object # Retrieve an account collection Source: https://docs.yorlet.com/api/owners/account-collections/retrieve openapi-owners.json GET /v1/account_collections/{id} Retrieves the account collection with the given ID. # Create an owner balance transaction Source: https://docs.yorlet.com/api/owners/owner-balance-transactions/create openapi-owners.json POST /v1/owner_balance_transactions Creates a new owner balance transaction (adjustment). # List all owner balance transactions Source: https://docs.yorlet.com/api/owners/owner-balance-transactions/list openapi-owners.json GET /v1/owner_balance_transactions Returns a list of owner balance transactions. They are returned sorted by creation date, with the most recent transactions appearing first. # The owner balance transaction object Source: https://docs.yorlet.com/api/owners/owner-balance-transactions/object # Retrieve an owner balance transaction Source: https://docs.yorlet.com/api/owners/owner-balance-transactions/retrieve openapi-owners.json GET /v1/owner_balance_transactions/{id} Retrieves the owner balance transaction with the given ID. # Update an owner balance transaction Source: https://docs.yorlet.com/api/owners/owner-balance-transactions/update openapi-owners.json POST /v1/owner_balance_transactions/{id} Change whether the owner balance transaction can be seen on statements and payout receipts by owners. # List all owner payments Source: https://docs.yorlet.com/api/owners/owner-payments/list openapi-owners.json GET /v1/owner_payments Returns a list of owner payments. The owner payments are returned sorted by creation date, with the most recent owner payments appearing first. # The owner payment object Source: https://docs.yorlet.com/api/owners/owner-payments/object # Retrieve an owner payment Source: https://docs.yorlet.com/api/owners/owner-payments/retrieve openapi-owners.json GET /v1/owner_payments/{id} Retrieves the owner payment with the given ID. # Update an owner payment Source: https://docs.yorlet.com/api/owners/owner-payments/update openapi-owners.json POST /v1/owner_payments/{id} Updates an owner payment. # Approve an owner payout Source: https://docs.yorlet.com/api/owners/owner-payouts/approve openapi-owners.json POST /v1/owner_payouts/{id}/approve # Cancel an owner payout Source: https://docs.yorlet.com/api/owners/owner-payouts/cancel openapi-owners.json POST /v1/owner_payouts/{id}/cancel # Create an owner payout Source: https://docs.yorlet.com/api/owners/owner-payouts/create openapi-owners.json POST /v1/owner_payouts # List all owner payouts Source: https://docs.yorlet.com/api/owners/owner-payouts/list openapi-owners.json GET /v1/owner_payouts # Mark an owner payout as failed Source: https://docs.yorlet.com/api/owners/owner-payouts/mark-failed openapi-owners.json POST /v1/owner_payouts/{id}/mark_failed # Mark an owner payout as paid Source: https://docs.yorlet.com/api/owners/owner-payouts/mark-paid openapi-owners.json POST /v1/owner_payouts/{id}/mark_paid # The owner payout object Source: https://docs.yorlet.com/api/owners/owner-payouts/object # Pay an owner payout Source: https://docs.yorlet.com/api/owners/owner-payouts/pay openapi-owners.json POST /v1/owner_payouts/{id}/pay # Preview an owner payout Source: https://docs.yorlet.com/api/owners/owner-payouts/preview openapi-owners.json POST /v1/owner_payouts/preview # Preview an owner payout approval Source: https://docs.yorlet.com/api/owners/owner-payouts/preview-approve openapi-owners.json POST /v1/owner_payouts/{id}/approve/preview # Retrieve an owner payout Source: https://docs.yorlet.com/api/owners/owner-payouts/retrieve openapi-owners.json GET /v1/owner_payouts/{id} # Send an owner payout receipt Source: https://docs.yorlet.com/api/owners/owner-payouts/send-receipt openapi-owners.json POST /v1/owner_payouts/{id}/send_receipt # Create an onboarding session Source: https://docs.yorlet.com/api/owners/owners-onboarding/create openapi-owners.json POST /v1/owners/{id}/onboarding # Create a person Source: https://docs.yorlet.com/api/owners/owners-persons/create openapi-owners.json POST /v1/owners/{id}/persons # Delete a person Source: https://docs.yorlet.com/api/owners/owners-persons/delete openapi-owners.json DELETE /v1/owners/{id}/persons/{personId} Deletes an existing person’s relationship to the account’s legal entity. # List all persons Source: https://docs.yorlet.com/api/owners/owners-persons/list openapi-owners.json GET /v1/owners/{id}/persons # The owner.person object Source: https://docs.yorlet.com/api/owners/owners-persons/object # Retrieve a person Source: https://docs.yorlet.com/api/owners/owners-persons/retrieve openapi-owners.json GET /v1/owners/{id}/persons/{personId} # Update a person Source: https://docs.yorlet.com/api/owners/owners-persons/update openapi-owners.json POST /v1/owners/{id}/persons/{personId} # Create an owner Source: https://docs.yorlet.com/api/owners/owners/create openapi-owners.json POST /v1/owners # Delete an owner Source: https://docs.yorlet.com/api/owners/owners/delete openapi-owners.json DELETE /v1/owners/{id} # List all owners Source: https://docs.yorlet.com/api/owners/owners/list openapi-owners.json GET /v1/owners # The owner object Source: https://docs.yorlet.com/api/owners/owners/object # Retrieve an owner Source: https://docs.yorlet.com/api/owners/owners/retrieve openapi-owners.json GET /v1/owners/{id} # Update an owner Source: https://docs.yorlet.com/api/owners/owners/update openapi-owners.json POST /v1/owners/{id} # Approve a payment run Source: https://docs.yorlet.com/api/owners/payment-runs/approve openapi-owners.json POST /v1/payment_runs/{id}/approve # Cancel a payment run Source: https://docs.yorlet.com/api/owners/payment-runs/cancel openapi-owners.json POST /v1/payment_runs/{id}/cancel # Create a payment run Source: https://docs.yorlet.com/api/owners/payment-runs/create openapi-owners.json POST /v1/payment_runs # List all payment runs Source: https://docs.yorlet.com/api/owners/payment-runs/list openapi-owners.json GET /v1/payment_runs # The payment run object Source: https://docs.yorlet.com/api/owners/payment-runs/object # Retrieve a payment run Source: https://docs.yorlet.com/api/owners/payment-runs/retrieve openapi-owners.json GET /v1/payment_runs/{id} # Create a tax filing Source: https://docs.yorlet.com/api/owners/tax-filings/create openapi-owners.json POST /v1/tax_filings # List all tax filings Source: https://docs.yorlet.com/api/owners/tax-filings/list openapi-owners.json GET /v1/tax_filings # The tax filing object Source: https://docs.yorlet.com/api/owners/tax-filings/object # Retrieve a tax filing Source: https://docs.yorlet.com/api/owners/tax-filings/retrieve openapi-owners.json GET /v1/tax_filings/{id} # Create a tax form Source: https://docs.yorlet.com/api/owners/tax-forms/create openapi-owners.json POST /v1/tax_forms # Delete a tax form Source: https://docs.yorlet.com/api/owners/tax-forms/delete openapi-owners.json DELETE /v1/tax_forms/{id} # List all tax forms Source: https://docs.yorlet.com/api/owners/tax-forms/list openapi-owners.json GET /v1/tax_forms # The tax form object Source: https://docs.yorlet.com/api/owners/tax-forms/object # Retrieve a tax form Source: https://docs.yorlet.com/api/owners/tax-forms/retrieve openapi-owners.json GET /v1/tax_forms/{id} # Create a transfer reversal Source: https://docs.yorlet.com/api/owners/transfers-reversals/create openapi-owners.json POST /v1/transfers/{id}/reversals # List all transfer reversals Source: https://docs.yorlet.com/api/owners/transfers-reversals/list openapi-owners.json GET /v1/transfers/{id}/reversals # The transfer reversal object Source: https://docs.yorlet.com/api/owners/transfers-reversals/object # Retrieve a transfer reversal Source: https://docs.yorlet.com/api/owners/transfers-reversals/retrieve openapi-owners.json GET /v1/transfers/{id}/reversals/{id} # Update a transfer reversal Source: https://docs.yorlet.com/api/owners/transfers-reversals/update openapi-owners.json POST /v1/transfers/{id}/reversals/{id} # Create a transfer Source: https://docs.yorlet.com/api/owners/transfers/create openapi-owners.json POST /v1/transfers # List all transfers Source: https://docs.yorlet.com/api/owners/transfers/list openapi-owners.json GET /v1/transfers # The transfer object Source: https://docs.yorlet.com/api/owners/transfers/object # Retrieve a transfer Source: https://docs.yorlet.com/api/owners/transfers/retrieve openapi-owners.json GET /v1/transfers/{id} # Update a transfer Source: https://docs.yorlet.com/api/owners/transfers/update openapi-owners.json POST /v1/transfers/{id} # List all balance transactions Source: https://docs.yorlet.com/api/payments/balance-transactions/list openapi-payments.json GET /v1/balance_transactions Returns a list of balance transactions. They are returned sorted by creation date, with the most recent transactions appearing first. # The balance object Source: https://docs.yorlet.com/api/payments/balance/object # Retrieve owner balance Source: https://docs.yorlet.com/api/payments/balance/retrieve openapi-payments.json GET /v1/balance/owners Retrieves the current owner balance for an owner on the account. # List all disputes Source: https://docs.yorlet.com/api/payments/disputes/list openapi-payments.json GET /v1/disputes List all disputes # Mark a dispute as resolved Source: https://docs.yorlet.com/api/payments/disputes/mark-resolved openapi-payments.json POST /v1/disputes/{id}/mark_resolved Marks the dispute as resolved. # The dispute object Source: https://docs.yorlet.com/api/payments/disputes/object # Retrieve a dispute Source: https://docs.yorlet.com/api/payments/disputes/retrieve openapi-payments.json GET /v1/disputes/{id} Retrieve a dispute # Submit dispute evidence Source: https://docs.yorlet.com/api/payments/disputes/submit-evidence openapi-payments.json POST /v1/disputes/{id}/submit_evidence Uploads the collected evidence and submits it to the bank for review. Set `submit` to `false` to stage evidence without final submission. # Update a dispute Source: https://docs.yorlet.com/api/payments/disputes/update openapi-payments.json POST /v1/disputes/{id} Update a dispute # Acknowledge the confirmation of payee Source: https://docs.yorlet.com/api/payments/external-accounts/acknowledge-confirmation-of-payee openapi-payments.json POST /v1/external_accounts/{id}/acknowledge_confirmation_of_payee Acknowledge the confirmation of payee for the external account. # Create an external account Source: https://docs.yorlet.com/api/payments/external-accounts/create openapi-payments.json POST /v1/external_accounts Create a new external account. # Delete an external account Source: https://docs.yorlet.com/api/payments/external-accounts/delete openapi-payments.json DELETE /v1/external_accounts/{id} Deletes the external account. # List all external accounts Source: https://docs.yorlet.com/api/payments/external-accounts/list openapi-payments.json GET /v1/external_accounts Returns a list of external accounts. The external accounts are returned sorted by creation date, with the most recently created external accounts appearing first. # The external account object Source: https://docs.yorlet.com/api/payments/external-accounts/object # Retrieve an external account Source: https://docs.yorlet.com/api/payments/external-accounts/retrieve openapi-payments.json GET /v1/external_accounts/{id} Retrieve the details about a specific external account. # Create a payment initiation Source: https://docs.yorlet.com/api/payments/payment-initiations/create openapi-payments.json POST /v1/payment_initiations Create a payment initiation request. Yorlet supports two types of payment initiation: type=inbound_payment initiates a payment from an external bank account to a bank account in Yorlet, and type=outbound_payment initiates a payment from your bank account to an external bank account. # List all payment initiations Source: https://docs.yorlet.com/api/payments/payment-initiations/list openapi-payments.json GET /v1/payment_initiations Returns a list of your payment initiations. The payment initiations are returned sorted by creation date, with the most recently created payment initiations appearing first. # The payment initiation object Source: https://docs.yorlet.com/api/payments/payment-initiations/object # Retrieves a payment initiation Source: https://docs.yorlet.com/api/payments/payment-initiations/retrieve openapi-payments.json GET /v1/payment_initiations/{id} Retrieves a Payment Initiation. # Create a payment initiation token Source: https://docs.yorlet.com/api/payments/payment-initiations/token openapi-payments.json POST /v1/payment_initiations/{id}/tokens Creates a single-use token that can be used to initiate a payment. Yorlet supports Payment Initiation using [Plaid](https://plaid.com/docs/payment-initiation/), you will need to launch the Payment Initiation flow in Plaid Link with the token returned by this endpoint. # Create a payment method session Source: https://docs.yorlet.com/api/payments/payment-method-sessions/create openapi-payments.json POST /v1/payment_method_sessions Create a new payment method session. # The payment method session object Source: https://docs.yorlet.com/api/payments/payment-method-sessions/object # Retrieve a payment method session Source: https://docs.yorlet.com/api/payments/payment-method-sessions/retrieve openapi-payments.json GET /v1/payment_method_sessions/{id} Retrieve the details about a specific payment method session. # Create a payment method Source: https://docs.yorlet.com/api/payments/payment-methods/create openapi-payments.json POST /v1/payment_methods Creates a new payment method. # Simulate a bank transfer Source: https://docs.yorlet.com/api/payments/payment-methods/fund-bank-transfer openapi-payments.json POST /v1/payment_methods/{id}/fund_bank_transfer Simulates an external bank transfer and adds funds to the payment method's balance. This method can only be called in test mode. # List all payment methods Source: https://docs.yorlet.com/api/payments/payment-methods/list openapi-payments.json GET /v1/payment_methods Returns a list of payment methods. # The payment method object Source: https://docs.yorlet.com/api/payments/payment-methods/object # Retrieve a payment method Source: https://docs.yorlet.com/api/payments/payment-methods/retrieve openapi-payments.json GET /v1/payment_methods/{id} Retrieves a payment method with the given ID. # Set up a payment method Source: https://docs.yorlet.com/api/payments/payment-methods/setup openapi-payments.json POST /v1/payment_methods/setup Creates a setup intent for collecting payment method details. # Cancel a payment session Source: https://docs.yorlet.com/api/payments/payment-sessions/cancel openapi-payments.json POST /v1/payment_sessions/{id}/cancel Cancels the payment session with the given ID. # Create a payment session Source: https://docs.yorlet.com/api/payments/payment-sessions/create openapi-payments.json POST /v1/payment_sessions Creates a new payment session. # List all payment sessions Source: https://docs.yorlet.com/api/payments/payment-sessions/list openapi-payments.json GET /v1/payment_sessions Returns a list of payment sessions. The payment sessions are returned sorted by creation date, with the most recent payment sessions appearing first. # The payment session object Source: https://docs.yorlet.com/api/payments/payment-sessions/object # Retrieve a payment session Source: https://docs.yorlet.com/api/payments/payment-sessions/retrieve openapi-payments.json GET /v1/payment_sessions/{id} Retrieves the payment session with the given ID. # Create a refund Source: https://docs.yorlet.com/api/payments/refunds/create openapi-payments.json POST /v1/refunds Create a refund for a transaction. # List all refunds Source: https://docs.yorlet.com/api/payments/refunds/list openapi-payments.json GET /v1/refunds List all refunds. # The refund object Source: https://docs.yorlet.com/api/payments/refunds/object # Retrieve a refund Source: https://docs.yorlet.com/api/payments/refunds/retrieve openapi-payments.json GET /v1/refunds/{id} Retrieve a refund by ID. # Cancel a transaction Source: https://docs.yorlet.com/api/payments/transactions/cancel openapi-payments.json POST /v1/transactions/{id}/cancel Cancels the transaction. # Confirm a transaction Source: https://docs.yorlet.com/api/payments/transactions/confirm openapi-payments.json POST /v1/transactions/{id}/confirm Confirms the transaction. # Create a transaction Source: https://docs.yorlet.com/api/payments/transactions/create openapi-payments.json POST /v1/transactions Create a transaction # List all transactions Source: https://docs.yorlet.com/api/payments/transactions/list openapi-payments.json GET /v1/transactions List all transactions # The transaction object Source: https://docs.yorlet.com/api/payments/transactions/object # Resend a receipt for a transaction Source: https://docs.yorlet.com/api/payments/transactions/resend-receipt openapi-payments.json POST /v1/transactions/{id}/resend_receipt Resend a receipt for a transaction # Retrieve a transaction Source: https://docs.yorlet.com/api/payments/transactions/retrieve openapi-payments.json GET /v1/transactions/{id} Retrieve a transaction # Terminal handoff for a transaction Source: https://docs.yorlet.com/api/payments/transactions/terminal-handoff openapi-payments.json POST /v1/transactions/{id}/terminal_handoff Terminal handoff for a transaction # Update a transaction Source: https://docs.yorlet.com/api/payments/transactions/update openapi-payments.json POST /v1/transactions/{id} Update a transaction # Create a terminal location Source: https://docs.yorlet.com/api/terminal/terminal-locations/create openapi-terminal.json POST /v1/terminal/locations Create a terminal location. # List all terminal locations Source: https://docs.yorlet.com/api/terminal/terminal-locations/list openapi-terminal.json GET /v1/terminal/locations List all terminal locations. # The terminal.location object Source: https://docs.yorlet.com/api/terminal/terminal-locations/object # Retrieve a terminal location Source: https://docs.yorlet.com/api/terminal/terminal-locations/retrieve openapi-terminal.json GET /v1/terminal/locations/{id} Retrieve a terminal location. # Update a terminal location Source: https://docs.yorlet.com/api/terminal/terminal-locations/update openapi-terminal.json POST /v1/terminal/locations/{id} Update a terminal location. # Create a terminal offer Source: https://docs.yorlet.com/api/terminal/terminal-offers/create openapi-terminal.json POST /v1/terminal/offers Create a terminal offer. # List all terminal offers Source: https://docs.yorlet.com/api/terminal/terminal-offers/list openapi-terminal.json GET /v1/terminal/offers List all terminal offers. # The terminal.offer object Source: https://docs.yorlet.com/api/terminal/terminal-offers/object # Retrieve a terminal offer Source: https://docs.yorlet.com/api/terminal/terminal-offers/retrieve openapi-terminal.json GET /v1/terminal/offers/{id} Retrieve a terminal offer. # Cancel the action of a terminal reader Source: https://docs.yorlet.com/api/terminal/terminal-readers/cancel-action openapi-terminal.json POST /v1/terminal/readers/{id}/cancel_action Cancel the action of a terminal reader. # Create a terminal reader Source: https://docs.yorlet.com/api/terminal/terminal-readers/create openapi-terminal.json POST /v1/terminal/readers Create a terminal reader. # List all terminal readers Source: https://docs.yorlet.com/api/terminal/terminal-readers/list openapi-terminal.json GET /v1/terminal/readers List all terminal readers. # Simulate an inbound email Source: https://docs.yorlet.com/api/test-helpers/test-helpers/email-simulate-inbound openapi-test_helpers.json POST /v1/test_helpers/emails/inbound Creates an inbound email as if it were received at a provisioned address. Only available in sandbox. If the recipient is the agent address, the email agent may draft a reply. # Simulate the outcome of a reference Source: https://docs.yorlet.com/api/test-helpers/test-helpers/reference-simulate-outcome openapi-test_helpers.json POST /v1/test_helpers/references/{id}/simulate_outcome # Simulate the progression of a subscription Source: https://docs.yorlet.com/api/test-helpers/test-helpers/subscription-simulate-progress openapi-test_helpers.json POST /v1/test_helpers/subscriptions/{id}/simulate_progress Advances a subscription to its next billing period, even if the due date is in the future. Only available in sandbox. # Yorlet Balance Source: https://docs.yorlet.com/balance Hold client funds, move money, and pay owners automatically from your balance. Yorlet Balance gives you a single view of the funds held on your account. Alongside your payments balance, you can open financial accounts to hold client funds, add and move money, and pay owners automatically without leaving Yorlet. Financial accounts and automatic owner payouts are part of the Balance plan. You can add the plan from your [plans settings](https://dashboard.yorlet.com/settings/plans). ## Get started Open financial accounts to hold client funds, add money, and move it out Review recent activity across your payments balance and financial accounts Pay out your available payments balance to your own bank account Pay owners automatically using the funds held in your balance # Automatic owner payouts Source: https://docs.yorlet.com/balance/automatic-owner-payouts Pay owners automatically using the funds held in your balance. When you approve an owner payout, you choose a **Payout method**. Choosing **Automatic** pays the owner from the client funds held in your balance, so you do not have to move money yourself. Choosing **Manual** means you pay the owner outside Yorlet and record the outcome. Automatic owner payouts are part of the Balance plan. Without the plan, only the **Manual** method is available. You can add the plan from your [plans settings](https://dashboard.yorlet.com/settings/plans/balance). ## Pay an owner automatically To pay an owner automatically, follow these steps: 1. Open a `draft` owner payout and click **Approve payout**. 2. Set the **Payout method** to **Automatic**. 3. Approve the payout, which moves it to `pending`. 4. Click **Pay payout** to send the funds from your balance to the owner's bank account. You can also approve payouts automatically in bulk, and include them in a [payment run](/owners/payment-runs) to pay many owners at once. ## Requirements * You must have the Balance plan. * The owner must have a valid destination bank account. See [owner payouts](/owners/owner-payouts) for how to add one. * You must have enough available funds in your balance to cover the payouts. # Financial accounts Source: https://docs.yorlet.com/balance/financial-accounts Open financial accounts to hold client funds and move money on Yorlet. Financial accounts let you hold client funds on Yorlet and move money in and out. You can view your financial accounts alongside your payments balance on the [Balances page](https://dashboard.yorlet.com/balance). Financial accounts are part of the Balance plan. If you do not have the plan yet, you can add it from your [plans settings](https://dashboard.yorlet.com/settings/plans/balance). ## Open a financial account To open a financial account, follow these steps: 1. Navigate to the [Balances page](https://dashboard.yorlet.com/balance). 2. Click the add (+) button next to your accounts. 3. Enter a **Name** for the account. 4. Confirm to open the account. ## Add funds To add funds to a financial account, follow these steps: 1. On the [Balances page](https://dashboard.yorlet.com/balance), open the account you want to add funds to. 2. Open the **Actions** menu and select **Add funds**. 3. Use the bank details shown to transfer money into the account. ## Move funds out To pay funds out of a financial account to your own bank account, follow these steps: 1. On the [Balances page](https://dashboard.yorlet.com/balance), open the account you want to move funds from. 2. Open the **Actions** menu and select **Pay out**. 3. Enter the amount and confirm the payout. ## Edit an account Open the **Actions** menu on a financial account and select **Edit** to update its details. # Payouts Source: https://docs.yorlet.com/balance/payouts Pay out your available payments balance to your own bank account. Payouts move your available payments balance to your own bank account. You can review them on the [Payouts page](https://dashboard.yorlet.com/payouts). These payouts move your own payments balance to your bank account. They are separate from [owner payouts](/owners/owner-payouts), which pay your owners, and from [automatic owner payouts](/balance/automatic-owner-payouts), which pay owners from the funds held in your balance. The **Payouts** page and your payments balance are always available, whether or not you have the Balance plan. # Activity Source: https://docs.yorlet.com/balance/transactions Review recent activity across your payments balance and financial accounts. The **Recent activity** section on the [Balances page](https://dashboard.yorlet.com/balance) shows money moving in and out of your account. Activity is split across two tabs. ## Payments balance The **Payments balance** tab lists transactions on your payments balance, such as collected payments, refunds, and payouts to your bank account. This tab is always available. ## Financial accounts The **Financial accounts** tab lists transactions on your financial accounts, such as funds you add, transfers, and automatic owner payouts paid from your balance. The **Financial accounts** tab is shown when you have the Balance plan. You can add the plan from your [plans settings](https://dashboard.yorlet.com/settings/plans/balance). # Yorlet Billing Source: https://docs.yorlet.com/billing Collect rent, manage invoices, and recover arrears. Yorlet Billing is how you collect rent and other recurring charges. Create subscriptions, generate invoices, watch arrears in real time, and escalate debt that is more than 28 days overdue with Recover. ## Get started Learn how to manage subscriptions on Yorlet Learn how to manage invoices on Yorlet Recover failed and overdue payments automatically Escalate debt more than 28 days overdue, with a success fee only on what is collected Build a reusable catalogue of products and prices Offer discounts on your customers' subscriptions Apply tax consistently across your charges Apply credit to a customer’s account # Arrears management Source: https://docs.yorlet.com/billing/arrears Learn how to manage arrears on Yorlet. With Yorlet, 97% of invoices payments succeed on the first try, and for the few that do fail our automated recovery tools re-collect 82% of payments without any human interaction. Invoices that are still unpaid after 28 days can be sent to [Recover](/billing/recovery) for an escalated sequence and self-serve instalment plans. ## Failed payments Yorlet will automatically send failed payment emails to customers, which include a link to a Hosted Invoice the customer can use to try the payment again. You can customise the [branding](/account/branding) of those emails in the Dashboard. ## Automatic reminders You can enable automatic reminders for failed payments in the [Dashboard](https://dashboard.yorlet.com/settings/subscriptions). When enabled, Yorlet will automatically send reminder emails to customers with failed payments. You can customise the frequency and content of these emails in the Dashboard. ### Arrears emails for past due invoices You can configure up to 4 arrears emails to be sent to customers with past due invoices. You can customise the frequency and content of these emails in the Dashboard. Once an invoice is more than 28 days past due, send it to [Recover](/billing/recovery). Recover continues contact with a firmer email sequence and a hosted page where the customer can pay in full or set up an instalment plan. ### Arrears notifications to owners for past due invoices You can configure up to 4 arrears notification emails to be sent to owners with past due invoices. You can customise the frequency and content of these emails in the Dashboard. ## 3D Secure Some payments require additional authentication to complete. When an invoice collection attempt requires action, Yorlet will send an automated email to the customer including a Yorlet-hosted page where they can complete the additional authentication. # Coupons Source: https://docs.yorlet.com/billing/coupons Create coupons to apply discounts to your customers' subscriptions. Coupons let you offer a discount to a customer, either as a percentage or a fixed amount off. Once created, a coupon can be applied to a subscription so the discount is reflected on the invoices it generates. ## Create a coupon To create a coupon, follow these steps: 1. Navigate to the [Coupons page](https://dashboard.yorlet.com/coupons) in the Dashboard. 2. Click **Create coupon**, or press N on your keyboard. 3. Enter a **Name**. This appears on your customers' receipts and invoices. 4. Choose the **Type** of discount: * **Percent off**: a percentage discount. Enter the **Percent off**. * **Amount off**: a fixed amount discount. Enter the **Amount off**. 5. Optionally turn on **Apply to specific invoice items** to restrict the discount to certain item types: **Rent**, **Charge** or **Product**. Leave it off to apply the coupon to all items. 6. Choose the **Duration**: * **Once**: applies to the first invoice only. * **Forever**: applies to every invoice for as long as the subscription runs. * **Repeating**: applies for a set **Number of months**. 7. Optionally set **Limitations**: * **Limit the number of times this coupon can be redeemed** to cap total redemptions. * **Limit the date this coupon can be redeemed** to set a date after which the coupon can no longer be applied. 8. Click **Create**. ## Apply a coupon to a subscription You apply a coupon when [creating a subscription](/billing/subscriptions/create-a-subscription). In the create panel, use the **Coupon** field to select a coupon for the customer. The discount is then applied to the invoices the subscription generates, according to the coupon's duration. ## View and manage coupons Select a coupon from the [Coupons page](https://dashboard.yorlet.com/coupons) to see its details, including: * **Usage**: the number of times the coupon has been redeemed. * **Details**: the discount, **Duration**, **Max redemptions** and **Redeem by** date. * **Active redemptions**: the subscriptions currently using the coupon. A coupon shows as `Valid` while it can still be redeemed, or `Invalid` once it has reached its redemption limit or redeem-by date. ## Delete a coupon Deleting a coupon stops it from being applied to any new subscriptions. Subscriptions already using the coupon keep their discount. To delete a coupon, follow these steps: 1. Navigate to the coupon you want to delete. 2. Click **Delete**. # Credit grants Source: https://docs.yorlet.com/billing/credit-grants Give a customer credit that is automatically applied to their invoices. A credit grant gives a customer a balance of credit that is automatically applied to their future invoices. This is useful for goodwill gestures, account credit or compensation. Credit grants are managed from the customer's record. ## Create a credit grant To create a credit grant, follow these steps: 1. Navigate to the customer you want to credit. 2. In the **Credit grants** section, click **New**. 3. Enter a **Name**. This is displayed to the customer. 4. Enter the **Amount** and select the **Currency**. 5. Optionally expand **Advanced options** to restrict how the credit can be used: * **Restrict to invoice item type**: limit the credit to a specific item type, such as **Rent**. * **Max credit per invoice item**: cap the amount of credit that can be applied to any single invoice item. 6. Click **Create**. ## How credit grants are applied Once created, an active credit grant is applied automatically to the customer's invoices, reducing the amount they owe, until the credit is used up or the grant is voided. Any restrictions you set control which invoice items the credit can be applied to. When you [issue a credit note](/billing/invoices/credit-notes) on a paid invoice, you can return the amount to the customer as a credit grant. ## Rename a credit grant To rename a credit grant, follow these steps: 1. Navigate to the customer's **Credit grants** section. 2. Use the credit grant's and select **Update**. 3. Change the **Name** and save your changes. ## Void a credit grant Voiding a credit grant removes its remaining credit so it is no longer applied to invoices. You can only void a grant while it is active. To void a credit grant, follow these steps: 1. Navigate to the customer's **Credit grants** section. 2. Use the credit grant's and select **Void**. # Invoices Source: https://docs.yorlet.com/billing/invoices Learn how to manage invoices on Yorlet. Subscriptions automatically generate invoices for each billing cycle. Learn more about the [invoice lifecycle for subscriptions](/billing/subscriptions#subscription-lifecycle). ## Invoice lifecycle Invoices are generated by subscriptions and are used to collect payments from your customers. The invoice lifecycle is as follows: The status of the invoice is `draft`. The invoice is finalised and the status is `open`. You can no longer edit the invoice. Yorlet will wait for the customer to pay the invoice manually or automatically attempt to pay it using the customer’s default payment method. * If the payment is successful, the status of the invoice is `paid`. * If the payment is processing, the status of the invoice is `pending` and `pending_transaction=true`. * If the payment fails, the status of the invoice is `open`. If the customer does not pay the invoice by the due date, the status of the invoice is `past due`. Optionally, you can change the status of an unpaid invoice to `uncollectible` or `void`. ## Invoice statuses Invoices can have one of the following statuses: | Status | Description | | :-------------- | :----------------------------------------------------- | | `draft` | The invoice is being created and is not yet finalised. | | `open` | The invoice is finalised and is ready to be paid. | | `paid` | The invoice has been paid. | | `uncollectible` | The invoice is uncollectible. | | `void` | The invoice is void. | ### Dashboard statuses Additionally, invoices can have the following statuses in the dashboard, these are cosmetic and do not affect the invoice lifecycle: | Status | Description | | :--------- | :------------------------------------------------------ | | `pending` | The invoice is waiting for the payment to be processed. | | `past due` | The invoice is overdue. | #### Finalising When an invoice is ready to be paid it must be finalised. This will set `status=open` on the invoice. After an invoice is finalised it can no longer be edited or deleted. Subscriptions automatically create invoices when they are due, and automatically finalise approximately 1-2 hours later. #### Paying an invoice When a successful payment occurs the invoice is moved into the `paid` status. If an invoice's collection method is set to charge automatically a payment will be automatically attempted. If the invoice was paid outside Yorlet you can mark the invoice as paid by changing the invoice's status, you can also add some context like a bank transfer reference. #### Asynchronous payments Some payment methods can take up to several days to confirm success, when an invoice is paid using one of these methods the invoice will be flagged as `pending_transaction=true` or `pending` in the Dashboard, and you will have to wait for the outcome of the charge. ### Change an invoice status You can change the status of an invoice to `uncollectible` or `void` from the Dashboard. To change the status of an invoice, follow these steps: 1. Navigate to the invoice you want to change the status of. 2. Click the menu and select **Change invoice status**. 3. Select the new status for the invoice. 4. Optionally, add a **Note** to the invoice. 5. Click **Change status** to change the status of the invoice. #### Mark as uncollectible Sometimes you may have customers that cannot pay their outstanding invoices. When an invoice is open you can decide to mark the invoice as unlikely to be paid by changing the invoice status to `uncollectible`. This allows you to track all amounts owed as part of your bad debt process. #### Voiding an invoice Voiding is like deleting an invoice when in draft, but it instead of removing it you can maintain a record of the invoice for reporting purposes. You can only void an invoice when it is either `open` or `uncollectible`. #### Off-platform payments If you receive a payment outside of Yorlet, you can manually mark the invoice as paid. This will update the invoice status to `paid`. ## Invoice actions From an invoice's you can take a number of actions on an open invoice: * **Charge invoice**: collect the outstanding amount using a selected payment method. * **Send invoice**: email the customer a link to the [hosted invoice](/billing/invoices/hosted-invoices). If the invoice is still a draft, sending it also finalises it. * **Attach payment**: link an existing payment to the invoice, for example when reconciling a payment that was taken separately. You can also adjust an invoice without collecting the full balance: * [Issue a credit note](/billing/invoices/credit-notes) to reduce the amount owed. * [Create a part payment](/billing/invoices/part-payments) to collect part of the balance. # Automatic transfer reconciliation Source: https://docs.yorlet.com/billing/invoices/automatic-reconciliation Allow customers to pay invoices by transferring funds to a bank account. Yorlet allows customers to pay invoices by transferring funds to a bank account using the [Bank Transfer payment method](/payments/payment-methods/bank-transfers). Upon receiving an inbound bank transfer, Yorlet uses the transfer’s reference code, amount, and date when determining the invoices for automatic reconciliation. ### Reference codes When a customer transfers funds to your bank account, they can include a reference code to help you identify the payment. Reference codes can be used to reconcile transfers to invoices. ### Oldest payable invoice If Yorlet cannot match a reference code Yorlet progressively pays open invoices by date until the bank balance runs out or until no invoices remain to pay. ### Reconciliation failures When funds transferred into Yorlet aren’t reconciled automatically, the funds are placed in the customer balance and you can manually reconcile the funds to the correct invoice. You can also refund the customer if the funds are not intended for Yorlet. You can view all customers with unallocated funds in the [Dashboard](https://dashboard.yorlet.com/customers/balances). # Create an invoice Source: https://docs.yorlet.com/billing/invoices/create-an-invoice Learn how to create an invoice on Yorlet. Learn how to create and send invoices to your customers on Yorlet. Invoices provide a detailed breakdown of the charges and services provided to your customers. You can create invoices for one-time charges or use [subscriptions to charge for recurring services](/billing/subscriptions). ## Create an invoice To create an invoice, follow these steps: You can also create an invoice from the customer’s profile page by clicking on the **Actions** menu and selecting **Create invoice**. 1. Navigate to the [Invoices page](https://dashboard.yorlet.com/invoices) in the Dashboard. 2. Click on the **New invoice** button, or press N on your keyboard. 3. Select a customer to create an invoice for. You can search for a customer by name or email address. 4. You can optionally associate the invoice with an active tenancy if the customer has one. 5. Select the **Currency** you’d like to use. 6. Add a **Memo** to the invoice to provide additional information to the customer, it will be displayed on the invoice. 7. Optionally set the period for the invoice, including the **Start date** and **End date**. 8. Configure the **Collection method** for the invoice. 9. Click **Create invoice**. 10. The invoice will be created and you can now start adding line items to the invoice using the **Add item** button. 11. Once you’ve added all the line items, click **Review draft** to review the invoice before sending it to the customer. 12. Click **Send** to send the invoice to the customer. You can also untoggle **Send invoice to customer** to just finalise the invoice and send it later. Invoices cannot be deleted or edited once they have been finalised. If you need to make changes to an invoice, you can create a [new draft revision](/billing/invoices/edit-invoices) of the invoice and make the necessary changes. If you need to delete an invoice, you can mark it as `void`. ### Adding line items When adding line items to an invoice, you can specify the following details for each line item: * **Type**: The type of the line item. * **Unit**: You can associate the line item with a unit. This is useful if you want to transfer the value of the line item to the owner of the unit. You must have a unit associated when the item type is **Rent**. * **Description**: A short description of the line item. * **Unit price**: The price of a single unit of the line item. * **Tax rate**: The tax rate for the line item. * **Transfer behaviour**: Determines how the value of the line item is transferred to an owner, if at all. You can customise the transfer behaviour for each line item you add. You must have a unit associated with the line item to use the **Auto** transfer behaviour. * **Auto**: transfers the value of the line item to the owner of the unit based on the unit’s [ownership structure](/owners/unit-ownership). The line item must have an associated unit. * **Owner**: transfers the value of the line item to a specified owner. * **None**: will not initiate any transfers. ### Advanced options We also support some advanced options when creating an invoice. Add custom fields to the invoice to add additional information to the generated PDF. # Credit notes Source: https://docs.yorlet.com/billing/invoices/credit-notes Learn how to manage credit notes on Yorlet. Credit notes are a way to adjust the amount owed by a customer. You can create a credit note for an invoice to adjust the amount owed by a customer. ## Create a credit note To create a credit note, follow these steps: 1. Navigate to the invoice for which you want to create a credit note. 2. Use the and select **Issue credit note**. 3. Select the **Reason** for the credit note. You can choose from **Duplicate**, **Fraudulent**, **Order change**, **Product unsatisfactory** or **Other**. 4. Use the **Credit amount** field to adjust the amount of credit to apply to each line item. The **Amount remaining** field shows the remaining amount that can be credited. 5. The **Total amount to credit** field shows the total amount of credit that will be applied to the invoice. 6. Optionally, add a **Memo** to the credit note. It will be visible to the customer. 7. Click **Create** to issue the credit note. If the invoice has already been paid, you can choose how the credited amount is returned: as a payment made outside of Yorlet, or as a [credit grant](/billing/credit-grants) on the customer's balance. ## View and manage credit notes You can view and manage credit notes from the **Credit notes** tab on the invoice page. The credit notes are listed with the following details: * **Credit note number**: The unique identifier for the credit note. * **Reason**: The reason for the credit note. * **Credit amount**: The amount credited. ### Edit a credit note memo To update the customer-visible memo on a credit note, follow these steps: 1. Navigate to the credit note you want to edit. 2. Use the and select **Edit memo**. 3. Update the **Memo** and save your changes. ### Void a credit note You can only void a credit note that was issued against an unpaid invoice. A credit note that returned credit to the customer cannot be voided. To void a credit note, follow these steps: 1. Navigate to the credit note you want to void. 2. Click the **Void** button. # Edit invoices Source: https://docs.yorlet.com/billing/invoices/edit-invoices Learn how to edit invoices after finalisation. Learn how to edit invoices after they have been finalised on Yorlet. You can edit invoices to add or remove line items, change the currency, or update the memo. Yorlet lets you revise a finalised invoice in the `open` status. You can’t revise an invoice in `uncollectible`, `void`, or `paid` status. ## Edit an invoice To edit an invoice, follow these steps: 1. Navigate to the [Invoices page](https://dashboard.yorlet.com/invoices) in the Dashboard. 2. Click on the invoice you’d like to edit. 3. Click on the **Edit invoice** button. 4. A new draft revision of the invoice will be created. You can now make changes to the invoice. 5. Once you’ve made the changes, click **Review draft** to review the changes before finalising the invoice. 6. Click **Send** to send the invoice to the customer. You can also untoggle **Send invoice to customer** to just finalise the invoice and send it later. 7. The previous version of the invoice will be marked as `void` and the new version will be marked as `open`. # Hosted Invoices Source: https://docs.yorlet.com/billing/invoices/hosted-invoices Use Hosted Invoices to securely collect payment from your customers. Hosted invoices ## Invoice URLs When you create an invoice, Yorlet generates a unique URL for the invoice. You can share this URL with your customers to securely collect payment from them. You can retrieve the URL for an invoice from the invoice details page in the Yorlet Dashboard. ``` https://pay.yorlet.com/invoice/v0MJ9imOCrPrBwm0bQkOIeinh3nnm9GW ``` ## Customise branding You can customise the look and feel of the payment session page in the Yorlet Dashboard. Go to your [branding settings](https://dashboard.yorlet.com/settings/branding) to: * Upload an icon * Customise your brand colour Learn more about [branding](/account/branding). # Part payments Source: https://docs.yorlet.com/billing/invoices/part-payments Learn how to collect a partial payment against an invoice in Yorlet. Part payments let you collect part of an open invoice rather than the full amount. You choose how much to pay against each line item, and Yorlet keeps the invoice open until the remaining balance is settled. This is useful when a customer can only pay some of what they owe, or when you receive a payment towards an invoice outside of Yorlet. You can only create a part payment for an invoice that is `open`. An invoice can have one pending part payment at a time, so you must complete or void the current part payment before creating another. ## Create a part payment To create a part payment, follow these steps: 1. Navigate to the invoice you want to collect a part payment for. 2. Use the and select **Create part payment**. 3. Under **Line items**, enter a **Part payment** amount against each line item you want to pay. Each amount is capped at the amount still owed on that line. 4. Review the totals. **Part payment due** shows the total you are collecting, alongside the **Invoice amount remaining**. 5. Optionally add a **Description** to record context for the part payment. 6. Tick **Payment outside of Yorlet** if the customer has already paid you outside of Yorlet (for example, by a manual bank transfer). 7. Click **Create part payment**. If the customer has a bank transfer balance available, a **Bank transfer** card shows the funds on hand and a link to **View balance**. Creating a part payment also creates a partial transfer, based on the transfer behaviour of each invoice line item being part paid. ### How a part payment is created What happens next depends on whether you ticked **Payment outside of Yorlet**: * If you left it unticked, the part payment is created with the status `unpaid` and a payment is prepared so you can collect it through Yorlet. Use **Charge part payment** to take the payment. * If you ticked it, the part payment is created with the status `unpaid` and marked as paid outside of Yorlet. Use **Mark as paid** to record that it has been settled. ## View part payments Part payments for an invoice are listed in the **Part payments** section of the invoice page. Select a part payment to open it and see its line items, amount and status, and to charge, mark as paid, void or edit it. ## Charge a part payment You can charge a part payment that has the status `unpaid` and was not paid outside of Yorlet. To charge a part payment, follow these steps: 1. Navigate to the part payment you want to charge. 2. Click **Charge part payment**. 3. Select the **Payment method** to charge. 4. Click **Charge** to collect the payment. ## Mark a part payment as paid When a part payment was paid outside of Yorlet, mark it as paid to keep your records up to date. To mark a part payment as paid, follow these steps: 1. Navigate to the part payment you want to update. 2. Click **Mark as paid**. 3. Optionally set the **Payment date**. Leaving it blank uses today's date. 4. Click **Mark as paid**. ## Void a part payment You can only void a part payment while it has the status `unpaid`. Voiding releases the amount back to the invoice so the balance can be collected another way. To void a part payment, follow these steps: 1. Navigate to the part payment you want to void. 2. Click **Void**. ## Edit a part payment description To update the description of a part payment, follow these steps: 1. Navigate to the part payment you want to edit. 2. Use the and select **Edit description**. 3. Update the description and save your changes. # Payment methods for invoices Source: https://docs.yorlet.com/billing/invoices/payment-methods Learn how to manage payment methods for invoices on Yorlet. By default, Yorlet uses the customer’s default payment method to pay invoices depending on the collection method used. You can define which payment methods you’d like to enable with invoices in your [payment method settings](https://dashboard.yorlet.com/settings/payment_methods). ## Enable card payments on certain invoices If you’ve disabled card payments in your payment method settings, you can still enable card payments for individual invoices. This is useful if you want to allow card payments for a specific invoice but not for all invoices. To enable card payments for an invoice, follow these steps: 1. Navigate to the invoice you’d like to enable card payments for. 2. Click the and select **Enable card payments**. # Products and prices Source: https://docs.yorlet.com/billing/products Build a catalogue of products and prices to reuse across invoices and subscriptions. Products describe the goods or services you charge for, and prices set how much a product costs and how often it is billed. A product can have several prices, for example a monthly and a yearly rate. Once you have a catalogue, you can quickly add products to invoice and subscription line items instead of entering the details each time. ## Create a product To create a product, follow these steps: 1. Navigate to the [Products page](https://dashboard.yorlet.com/products) in the Dashboard. 2. Click **Create product**, or press N on your keyboard. 3. Enter a **Name**. This appears on your customers' receipts and invoices. 4. Optionally add a **Description**, which is visible to customers. 5. Optionally click **Add default price** to set a price now (see [Add a price](#add-a-price)). 6. Click **Create**. ## Add a price A product can have multiple prices. To add a price to a product, follow these steps: 1. Open the product. 2. In the **Prices** section, click **Add price**. 3. Enter the **Amount**. 4. Choose the **Type**: * **Recurring**: billed on a repeating schedule. Choose the **Billing period** (**Weekly**, **Monthly**, **Every 3 months**, **Every 6 months** or **Custom**). * **One time**: billed once. 5. Optionally add a **Description**. This is hidden from customers. 6. Optionally select a **Tax rate** to apply by default. Learn more about [tax rates](/billing/tax-rates). 7. Set the **Transfer behavior**: * **None**: the value is not transferred to an owner. * **Owner**: the value is transferred to a specified owner. Select the **Transfer destination**. 8. Click **Create**. ## Use products and prices When you add a line item to an [invoice](/billing/invoices/create-an-invoice) or a [subscription](/billing/subscriptions/create-a-subscription), you can select a product so its price, tax rate and transfer behaviour are filled in for you. You can still adjust the details on the line item before saving. ## Update a product or price To update a product, open it, use the and select **Update** to change its **Name** or **Description**. To update a price, open its product, use the price's and select **Update**. You can change the price's description, tax rate and transfer destination. ## Archive a product or price Archiving keeps the record for reporting but stops it being used on new line items. * To archive a product, open it, use the and select **Archive**. Select **Activate** to restore it. * To archive a price, open its product, use the price's and select **Archive**. Select **Activate** to restore it. # Recover Source: https://docs.yorlet.com/billing/recovery Escalate invoices more than 28 days overdue into a recovery case, with instalment plans and a success fee only on what is collected. Recover picks up where [automatic arrears reminders](/billing/arrears) stop. From the [Arrears page](https://dashboard.yorlet.com/billing/arrears), you send a customer's invoices that are more than 28 days past due into a **recovery case**. The customer then receives an escalated email sequence and a hosted page where they can pay in full or set up an [instalment plan](/billing/recovery/payment-plans) that collects itself. You only pay a success fee on what Recover collects. There is nothing to pay up front, and if nothing is recovered you pay nothing. ## Enable Recover To enable Recover, follow these steps: 1. Go to [Your plans](https://dashboard.yorlet.com/settings/plans). 2. Find **Recover** and click **Get started**. 3. Review the success-fee pricing and click **Enable Recover**. Once enabled, a **Recovery** item appears under **Billing** in the sidebar, and a **Send to recovery** action appears on qualifying rows in [Arrears](https://dashboard.yorlet.com/billing/arrears) and [Invoices](https://dashboard.yorlet.com/invoices). Recover only enrols invoices that are more than 28 days past due. Younger overdue invoices stay on the standard arrears reminder sequence, so the success fee never applies to payments those reminders would have collected. ## Recover triage When the organisation has a [Standard or Premium](/business-automation/ai/plans) AI seat, Recover triage reviews aged arrears each day. It reads any [Inbox threads](/business-automation/inbox/overview) with that customer, then may propose enrolment, a send from the [agent address](/business-automation/inbox/agents), or an internal note. Those proposals appear in [Approvals](/business-automation/ai/approvals) and follow your [agent policy](/business-automation/ai/policy) — enrolment and emails wait for a teammate by default. ## Send invoices to recovery To send a customer's overdue invoices to recovery, follow these steps: 1. Go to the [Arrears page](https://dashboard.yorlet.com/billing/arrears). 2. Find a customer whose oldest invoice is more than 28 days past due. 3. Open the row's and select **Send to recovery**. 4. Review the invoices that will be enrolled. Untick any you do not want to include. **Total to enrol** shows the amount outstanding across the selected invoices. 5. Click **Send to recovery**. Yorlet opens a recovery case for that customer, emails them immediately, and takes you to the case. You can also open existing cases from the [Recovery page](https://dashboard.yorlet.com/billing/recovery). ### Send several at once Select the customers or invoices you want to enrol, then click **Send to recovery**. * On [Arrears](https://dashboard.yorlet.com/billing/arrears), select customers whose oldest invoice is more than 28 days past due. Each customer’s eligible invoices are enrolled together. * On [Invoices](https://dashboard.yorlet.com/invoices), select open invoices that are more than 28 days past due. Invoices for the same customer are grouped into one case. If the customer already has an open recovery case, the invoices are added to it. You cannot add invoices while a payment plan is active. ### Add invoices to a case To add further eligible invoices to an open case, follow these steps: 1. Open the case from the [Recovery page](https://dashboard.yorlet.com/billing/recovery). 2. Use the and select **Add invoices**. 3. Tick the invoices to enrol and click **Add invoices**. ## What your customer receives As soon as you enrol a case, the customer is emailed a link to a hosted recovery page. On that page they can: * See the overdue invoices and the amount outstanding. * Pay the balance in full. * Set up an [instalment plan](/billing/recovery/payment-plans) of 2, 3, 6 or 12 monthly payments, collected automatically from a payment method they add. If they do not pay or set up a plan, Recover continues the email sequence on days 3, 7, 14, 21 and 28 after enrolment. The sequence stops if they accept a plan, clear the balance, or you cancel the case. You can click **Copy recovery link** on the case, or open **View recovery page** from the . ## Recovery case statuses A recovery case can have one of the following statuses: | Status | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `open` | The case is chasing the outstanding balance. Escalated emails continue until the customer pays, sets up a plan, or you cancel. | | `plan_active` | The customer has accepted an instalment plan. Remaining emails stop, and instalments are collected automatically. | | `recovered` | Every enrolled invoice has been paid in full. | | `canceled` | You stopped the case. The invoices stay outstanding, and no further recovery fee is charged. | The case moves to `recovered` automatically once the enrolled invoices are fully paid, whether the customer paid in full, through a plan, or by another payment in Yorlet. ## View a recovery case The [Recovery page](https://dashboard.yorlet.com/billing/recovery) lists every case, with tabs for **Open**, **Plan active**, **Recovered** and **Canceled**. Charts at the top of the page show recovered revenue over the selected period and the amount still outstanding on open and plan-active cases. The same Recover charts also appear on the [Billing overview](https://dashboard.yorlet.com/billing), and you can pin them to your home dashboard. Open a case to see: * The amount enrolled, recovered and still outstanding. * The recovery fee charged so far, and the percentage applied. * When the case was enrolled, when the customer was last contacted, and how many emails have been sent. * The [instalment plan](/billing/recovery/payment-plans), if the customer has accepted one. * The enrolled invoices. ## Cancel a recovery case Cancelling stops the escalated emails, closes the hosted recovery page, and cancels any active instalment plan. The invoices remain outstanding and no further recovery fee is charged. You can only cancel a case while it is `open` or `plan_active`. To cancel a recovery case, follow these steps: 1. Navigate to the case you want to cancel. 2. Use the and select **Cancel case**. 3. Click **Cancel case** to confirm. ## Success fee Recover charges a success fee of 5% on each payment collected against an enrolled invoice. The fee is deducted from the payment alongside your usual payment fees, and is shown on the case as **Recovery fee**. * The fee only applies to payments against invoices enrolled in a recovery case. * If you cancel the case, later payments on those invoices do not carry the fee. * There is no monthly charge and nothing to pay if nothing is recovered. Use Recover for debt the standard reminder sequence has already had a chance to collect. That keeps the success fee on aged arrears, rather than on rent you would have collected anyway. # Instalment plans Source: https://docs.yorlet.com/billing/recovery/payment-plans Let a customer spread a recovery case across monthly instalments that collect automatically. When a customer cannot pay a [recovery case](/billing/recovery) in full, they can set up an instalment plan on the hosted recovery page. Yorlet then collects each instalment automatically from the payment method they add, until the enrolled invoices are paid or the plan is cancelled or defaults. You do not create the plan from the Dashboard. The customer chooses the terms and accepts the plan themselves. ## How a plan is set up On the hosted recovery page, the customer can: 1. Choose to set up a plan instead of paying in full. 2. Pick 2, 3, 6 or 12 monthly instalments. 3. Add a payment method. 4. Accept the plan. The first instalment is collected immediately if it is already due. Remaining instalments are collected automatically on their due dates. Once the plan is accepted, the recovery case moves to `plan_active` and the escalated email sequence stops. ## View a plan Open the [recovery case](/billing/recovery) to see the instalment plan. Each instalment shows its due date, amount and status: | Status | Description | | ---------- | --------------------------------------------------------------------------------------------------------- | | `pending` | The instalment is scheduled and has not been collected yet. | | `paid` | The instalment was collected. | | `failed` | The most recent collection attempt failed. Yorlet retries on following days. | | `canceled` | The instalment will not be collected, because the debt was settled another way or the plan was cancelled. | The plan itself can be: | Status | Description | | ----------- | ----------------------------------------------------------------------------------------------- | | `proposed` | The customer has started a plan but has not accepted it yet. | | `active` | Instalments are being collected. | | `completed` | The enrolled invoices are settled. Remaining scheduled instalments are canceled. | | `defaulted` | Collection failed repeatedly, the plan was torn down, and the recovery case returned to `open`. | | `canceled` | You or a full settlement cancelled the plan. | If an instalment fails, Yorlet retries collection for up to three days. After that the plan defaults, the recovery case returns to `open`, and escalated emails can resume. ## Paying the balance in full A customer with an active plan can still pay the remaining balance in full from the hosted recovery page. That settles the enrolled invoices, completes the recovery case, and cancels the rest of the plan. ## Cancel a plan Cancelling a [recovery case](/billing/recovery) also cancels its active instalment plan. Future instalments are not collected. The invoices remain outstanding and the case is marked `canceled`. Amounts already paid stay applied to the enrolled invoices. # Subscriptions Source: https://docs.yorlet.com/billing/subscriptions Learn how to manage subscriptions on Yorlet. Subscriptions is a recurring billing engine within the Yorlet platform for collecting rent. It generates Invoices. The Billing engine then automatically collects Payments on those Invoices, and moves on to the next one. Invoices left unpaid after their due date are visible from the Billing dashboard so you can easily track arrears. A subscription will always generate the first invoice on the first day (or move in day) of a tenancy. After that, all Invoices are created at the end of the billing interval, which is set during the creation of an application. Subscriptions are automatically generated when an application is completed. Learn more about [applications](/leasing/applications). ## Subscription lifecycle The subscription is created when an application is completed or is created manually. The status of the subscription will be either `active` or `scheduled` depending on the start date. If the subscription is `scheduled`, it will become `active` on the start date. The subscription will generate the first invoice on the start date. The first invoice is created on the first day of the tenancy or the start date of the subscription. Subsequent invoices are created at the end of the billing interval. The status of the invoice is `open`. The customer pays the invoice using the payment method set on the subscription. The status of the invoice is `paid`. The subscription generates the next invoice at the end of the billing interval. The status of the invoice is `open`. If the customer does not pay the invoice by the due date, the status of the invoice is `past due`. The subscription will continue to generate invoices at the end of the billing period. The subscription lifecycle continues until the end date of the subscription is reached or the subscription is cancelled. The status of the subscription will be `complete` when the end date is reached or `canceled` if the subscription is terminated early. ## Manage a subscription Open a subscription from the [Subscriptions page](https://dashboard.yorlet.com/subscriptions) to see its current period, items, upcoming invoice, and revision history. From there you can: * [Update the subscription](/billing/subscriptions/update-a-subscription) to change items, the billing day, prorations, or how payment is collected. * [Cancel](/billing/subscriptions/update-a-subscription#cancel-a-subscription) immediately or on a future date, or stop a scheduled cancellation. * Collect a new payment method, or add a one-off item to the next invoice. When you change the billing day or a period is shorter than usual, Yorlet can [prorate](/billing/subscriptions/prorations) the charge so the customer only pays for those days. ## Collection methods You can determine the method by which an invoice is paid by setting the subscription collection method to either `Charge automatically` or `Send invoice`. Initially this is decided when creating an application, but it can be edited while the subscription is active. * **Charge automatically**: Collect a payment method from your customers during the application process, this becomes the subscriptions default payment method and invoice payments are automatically charged. * **Send invoice**: An email is sent to your customer with a link to a hosted invoice. If you select this method whilst creating an application your customer will not be asked to provide a payment method. ## Optimised collection Some payment methods can take several days to complete so Yorlet Billing automatically applies optimisations to make sure you’re being paid when a subscription invoice becomes due. ### Without optimised collection Without optimisation the payment would settle 3 days after the subscription due date. For example, Bacs Direct Debit payments take two to three business days to succeed: | Timing | Description | | :----- | :------------------------------------------------------------------ | | T+0 | Invoice is generated, payment initiated and debit request submitted | | T+1 | Debtor’s bank receives request and prepares to debit funds | | T+2 | Customer is debited funds | | T+3 | Funds received and payment succeeds | In this example, the payment would settle 3 days after the subscription due date. ### With optimised collection Yorlet Billing will apply optimisations and initiate some payments early to avoid late settlement: | Timing | Description | | :----- | :------------------------------------------------------------------ | | T-2 | Invoice is generated, payment initiated and debit request submitted | | T+0 | Customer is debited funds | | T+1 | Funds received and payment succeeds | This optimisation means that the customer will be debited on subscription due date. # Create a subscription Source: https://docs.yorlet.com/billing/subscriptions/create-a-subscription Learn how to create a subscription on Yorlet. Subscriptions generate invoices on a repeating schedule. You can create one from a completed [application](/leasing/applications), or add one yourself from the Dashboard. ## Using Yorlet Leasing When you create a tenancy application, a subscription is automatically created for each customer based on the tenancy information. The subscription generates invoices based on the billing interval you set during the application process. ## Create a subscription manually To create a subscription, follow these steps: 1. Navigate to the [Subscriptions page](https://dashboard.yorlet.com/subscriptions) and click **Create subscription**. You can also open a customer and select **Create subscription** from the **Actions** menu. 2. Select the **Customer**. This is filled in for you if you started from the customer. 3. Select the **Currency**. 4. Set the **Schedule**, including the billing interval, **Start date**, **End date**, and an optional **Billing anchor**. 5. Click **Add item** to add recurring line items. 6. Optionally apply a [coupon](/billing/coupons). 7. Configure **Payment collection**. 8. Click **Create subscription**. ### Schedule Click **Edit** on the schedule to set how often the subscription bills and when it runs. #### Billing interval In the Dashboard you can select: * **Weekly**: bills the customer every week. * **Every 4 weeks**: bills the customer every 4 weeks. * **Monthly**: bills the customer every month. * **Every 3 months**: bills the customer every 3 months. * **Every 6 months**: bills the customer every 6 months. * **Custom**: a custom schedule, typically set when the subscription is created from a tenancy application. #### Start and end dates The **Start date** can activate the subscription on a future date or backdate it. A future start date creates the subscription as `scheduled` until that date. The **End date** stops the subscription creating invoices after that date. When the end date passes, the status becomes `complete`. If you leave the end date as **Never**, the subscription bills indefinitely until you [cancel](/billing/subscriptions/update-a-subscription#cancel-a-subscription) it. #### Billing anchor For weekly and monthly subscriptions, optionally set a **Billing anchor** if you want to charge on a different day from the start date. For example, a tenancy that starts on the 3rd can still bill on the 1st of each month. Only set a billing anchor when the billing day should differ from the start date. After the subscription exists, you can change the billing day again when you [update the subscription](/billing/subscriptions/update-a-subscription#billing-anchor). ### Items Each item is a recurring charge on the invoices the subscription generates. Click **Add item**, then set: * **Type**: **Rent**, **Charge**, or **Product**. Use **Rent** for rent and attach a unit so Yorlet can report on it. Use **Product** to reuse a [product](/billing/products) with a recurring price. * **Unit**: the unit the item relates to. Required for **Rent**. Selecting a unit for rent fills in the description and the unit’s default rent. * **Description**: the label that appears on the invoice. * **Price**: the amount to bill each period. * **Item tax**: the tax percentage. Use **Use tax rate** to apply a [tax rate](/billing/tax-rates). * **Transfer behaviour**: how the value is transferred to an owner. See [Transfer behaviour](#transfer-behaviour). * **Create prorations**: when on, this item can be [prorated](/billing/subscriptions/prorations) if a period is shorter than a full interval. ### Payment collection * **Charge automatically**: use a saved payment method such as [Bacs Direct Debit](/payments/payment-methods/bacs-debit) to charge the customer when the subscription is due. * **Send invoice**: email the customer a [hosted invoice](/billing/invoices/hosted-invoices) they can pay themselves. Choose which payment methods they can use. If the customer has no payment method on file, only **Send invoice** is available. ### Custom invoice fields Under **Additional options**, add custom fields to include extra information, such as a purchase order number, in the header of the generated invoice PDF. You can add up to four fields. ## Transfer behaviour The transfer behaviour determines how the value of the line item is transferred to an owner, if at all. You can set this on each item. * **Automatic**: transfers the value to the owner of the unit based on the unit’s [ownership structure](/owners/unit-ownership). The item must have a unit. Rent items always use **Automatic**. * **Owner**: transfers the value to a specified owner. * **None**: does not initiate any transfers. # Pausing subscriptions Source: https://docs.yorlet.com/billing/subscriptions/pausing-subscriptions Learn how to pause payment collection on subscriptions. Pausing a subscription stops Yorlet collecting payment, while invoices can still be generated. Use this to offer a period for free, or to stop collection if you cannot provide the service. You choose what happens to invoices created while the subscription is paused. | Use case | What happens to invoices | | ------------------------------------------------- | ----------------------------------- | | Offer services for free | Invoices are marked `uncollectible` | | Offer services for free and collect payment later | Invoices are left as `draft` | | Unable to provide services | Invoices are `void` | While collection is paused, the subscription timeline shows that collection is paused and, if you set one, the date it will resume. # Prorations Source: https://docs.yorlet.com/billing/subscriptions/prorations How Yorlet adjusts charges when a billing period is shorter than a full interval. When a subscription period is shorter than a full billing interval, Yorlet can prorate the charge so the customer only pays for the days they are billed for. You control this when you [update a subscription](/billing/subscriptions/update-a-subscription), and you can see the result in the invoice **Preview** before you save. ## When prorations apply Prorations apply when the invoice period is shorter than the subscription’s usual interval. Common cases include: * You change the **Billing anchor** so the next invoice covers only part of a period. * A subscription starts mid-period. * A subscription ends or is cancelled before the period would normally finish. * The final period before an end date is shorter than a full interval. Prorations do not apply to: * One-off invoice items * Items where **Create prorations** is turned off * Periods that are a full interval (or longer) * Differences of a single day, which are ignored to avoid tiny adjustments ## Control prorations when you update There are two controls, and they work together. ### Create prorations on an item When you add or edit a subscription item, **Create prorations** is on by default. Leave it on if this item should be adjusted on a short period. Turn it off to always charge the full amount for that item, even when the period is shorter than usual. ### Prorate changes on the subscription When you set a **Billing anchor**, **Prorate changes** appears under **Billing cycle settings**. It is on by default. * **On**: the next invoice is prorated, so the customer pays for the days in that period. * **Off**: the next invoice charges the full item amounts, even if the period is shorter. Turning **Prorate changes** off applies to the next invoice as a whole. After that invoice is generated, later invoices return to creating prorations unless you change the setting again. Review the **Preview** on the update page before you click **Update**. Prorated lines are labelled **(Prorated)** and show the original amount struck through next to the adjusted amount. ## Reset billing cycle **Reset billing cycle** changes the dates of the next invoice. It does not turn prorations on or off — use **Prorate changes** for that. * **Off**: only the end of the next period moves to the billing anchor. The next invoice is shorter, so **Prorate changes** will usually reduce the amount. * **On**: the next invoice starts on the billing anchor and covers a full interval. A full period is not prorated. For example, a £1,000 monthly subscription that bills on the 1st. You set the billing anchor to the 15th: | Reset billing cycle | Prorate changes | Next invoice | | ------------------- | --------------- | -------------------------------------------------------------- | | Off | On | Shorter period ending on the 15th, charged only for those days | | Off | Off | Shorter period ending on the 15th, charged the full £1,000 | | On | On or off | Full month starting on the 15th, charged the full £1,000 | ## How the amount is calculated Yorlet works out a daily rate from the full interval, then charges for the days in the actual period. 1. Count the days in a full interval from the period start (for example, 1 June to 1 July is 30 days). 2. Divide the item amount by those days to get a daily rate. 3. Charge the daily rate for each day in the actual period. The unused days are taken off the line item. The reduction cannot be more than the original amount. ### Example A £1,000 monthly item bills from 15 January to 15 February 2024 — 31 days. The daily rate is £1,000 ÷ 31 = £32.26. If that invoice is shortened to end on 30 January (15 days): * Unused days: 31 − 15 = 16 * Amount taken off: £32.26 × 16 = £516.16 * Amount charged: £483.84 If it instead ends on 5 February (21 days): * Unused days: 10 * Amount taken off: £322.60 * Amount charged: £677.40 For monthly subscriptions, the daily rate changes with the length of the period. A 31-day month and a 28-day month produce slightly different daily rates for the same rent. That is expected: the customer is charged for the actual days in that period. ## Cancellation When you [cancel a subscription](/billing/subscriptions/update-a-subscription#cancel-a-subscription), you can issue a credit note for unused time on the latest invoice. That credit uses the same daily-rate calculation as invoice prorations. Choose **No credit note** if you do not want to credit the unused portion. # Update a subscription Source: https://docs.yorlet.com/billing/subscriptions/update-a-subscription Change items, billing, and collection on an existing subscription. You can change what a subscription bills, when it bills, and how payment is collected. The **Preview** on the right shows the next invoice as you edit, including any [prorations](/billing/subscriptions/prorations). You can update a subscription while it is `active` or `scheduled`. ## Update a subscription To update a subscription, follow these steps: 1. Navigate to the [Subscriptions page](https://dashboard.yorlet.com/subscriptions) and open the subscription. 2. Click **Update**. 3. Change the items, billing, or collection settings you need. 4. Review the **Preview**, then click **Update**. ### Items The **Items** section lists the recurring charges on the subscription. Changes are staged until you click **Update**, so you can review several edits together. New items are marked **New**, edits are marked **Change**, and removals are marked **Remove**. You can undo a removal before you save. To add an item, click **Add item**. To edit or remove an existing item, use the buttons on that row. Each item can have: * **Type**: **Rent**, **Charge**, or **Product**. Use **Rent** for rent so you can attach a unit for reporting. Use **Product** to reuse a [product](/billing/products) with a recurring price. * **Unit**: the unit the item relates to. Required for **Rent**. Selecting a unit for rent fills in the description and the unit’s default rent. * **Description**: the label that appears on the invoice. For a **Product**, this is taken from the product name. * **Price**: the amount to bill each period. For a **Product**, this comes from the selected price. * **Item tax**: the tax percentage. Use **Use tax rate** to apply a [tax rate](/billing/tax-rates). * **Transfer behaviour**: how the value is transferred to an owner. See [Transfer behaviour](/billing/subscriptions/create-a-subscription#transfer-behaviour). * **Create prorations**: when on, this item can be [prorated](/billing/subscriptions/prorations) if the next period is shorter than a full interval. Turn it off to always charge the full amount for this item. ### Billing anchor For weekly and monthly subscriptions, you can set a **Billing anchor** to charge on a different day from the current period date. Pick a date within the current period. Once you set a billing anchor, **Billing cycle settings** appear. ### Billing cycle settings These options appear after you set a **Billing anchor**. * **Prorate changes**: when on (the default), the next invoice is adjusted so the customer only pays for the days in that period. When off, they are charged the full item amounts even if the period is shorter. Learn more about [prorations](/billing/subscriptions/prorations). * **Reset billing cycle**: when on, the next invoice starts on the billing anchor and covers a full billing interval from that date. When off, only the end of the next period moves to the new day, so the next invoice covers a shorter period. For example, a monthly subscription that bills on the 1st. You set the billing anchor to the 15th: | Reset billing cycle | What happens to the next invoice | With prorate changes on | | ------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------- | | Off | The period ends on the 15th, so the invoice covers a shorter period | The customer is charged only for the days in that shorter period | | On | The period starts on the 15th and covers a full month | The customer is charged for a full month starting on the 15th | Leave **Reset billing cycle** off when you want to finish the current cycle on the new day, then continue from there. Turn it on when you want the new day to start a fresh full period immediately. ### Payment collection In **Payment collection**, choose how invoices are paid: * **Charge automatically**: charge a payment method already on file. Select the **Payment method** to use. * **Send invoice**: email the customer a [hosted invoice](/billing/invoices/hosted-invoices) to pay. Choose which payment methods they can use. Switching to **Send invoice** clears the default payment method, because invoices are no longer charged automatically. If the customer has no payment method on file, only **Send invoice** is available. ### Custom fields Add custom fields to include extra information, such as a purchase order number, in the header of the generated invoice PDF. You can add up to four fields. ### Preview The **Preview** shows the upcoming invoice for the period your changes will bill, including line items, tax, and any prorated amounts. Prorated lines are labelled **(Prorated)** and show the adjusted amount. The preview updates as you change items, the billing anchor, **Prorate changes**, or **Reset billing cycle**. It may also include pending one-off invoice items already on the subscription. ## Add a one-off invoice item You can add a one-off charge that will be included on the subscription’s next invoice, without changing the recurring items. 1. Navigate to the subscription. 2. In **Pending invoice items**, click **Add invoice item**. 3. Set the **Type** (**Rent**, **Charge**, or **Product**), then enter the unit, description, price, tax, and transfer behaviour. 4. Click **Create**. The item appears on the next invoice the subscription generates. ## Collect a new payment method You can collect a new payment method from a customer for their subscription at any time. 1. Navigate to the subscription. 2. Click the and select **Collect new payment method**. 3. Choose the **Payment methods** you would like to allow. 4. Optionally turn on **Send email to customer** to email them the link. 5. Click **Create**. The new payment method becomes the subscription’s default, and collection is set to charge automatically. ## Cancel a subscription You can cancel a subscription immediately, or schedule it to cancel on a future date. 1. Navigate to the subscription. 2. Click the and select **Cancel subscription**. 3. Choose **Immediately** or **Future date**. For a future date, set the **Cancellation date** (at least one day from today). 4. Choose how to handle unused time on the latest invoice: * **No credit note**: do not credit the customer. * **Credit outside of Yorlet**: record a credit note as handled outside Yorlet. * **Credit to customer balance**: apply the credit to the customer’s balance for future invoices. * **Refund original payment**: return the credited amount to the original payment method. 5. Click **Cancel subscription** or **Schedule cancellation**. A scheduled cancellation keeps the subscription `active` until that date. You can stop it before then. ### Stop a scheduled cancellation 1. Navigate to the subscription. 2. Click the and select **Stop cancellation**. 3. Confirm to keep the subscription running. # Tax rates Source: https://docs.yorlet.com/billing/tax-rates Create reusable tax rates to apply to invoices, subscriptions and prices. Tax rates let you apply tax consistently across your charges. Once you have created a tax rate, you can apply it to invoice and subscription line items and to [prices](/billing/products), and it will be shown on the customer's invoice. ## Create a tax rate To create a tax rate, follow these steps: 1. Navigate to the [Tax rates page](https://dashboard.yorlet.com/tax-rates) in the Dashboard. 2. Click **Create tax rate**, or press N on your keyboard. 3. Choose the **Type**: **VAT**, **GST**, **Sales tax** or **Custom**. If you choose **Custom**, enter a **Name** to show on customers' receipts and invoices. 4. Select the **Country** the tax rate applies to. 5. Enter the **Rate** as a percentage, and choose whether it is **Exclusive** or **Inclusive**. 6. Optionally add a **Description**. 7. Click **Create**. ### Inclusive and exclusive tax * **Exclusive**: the tax is added on top of the line item amount. * **Inclusive**: the line item amount already includes the tax. ## Apply a tax rate When you add a line item to an [invoice](/billing/invoices/create-an-invoice) or a [subscription](/billing/subscriptions/create-a-subscription), use **Use tax rate** to select a tax rate for that item. You can also set a default tax rate on a [price](/billing/products) so it is applied automatically whenever the price is used. ## Archive a tax rate Archiving keeps the tax rate for reporting but stops it being applied to new line items and prices. To archive a tax rate, follow these steps: 1. Open the tax rate. 2. Use the and select **Archive**. Select **Activate** to restore it. # External agents Source: https://docs.yorlet.com/business-automation/ai/agent-keys Create an agent key so ChatGPT desktop or another MCP client can authenticate to Yorlet. An agent key lets a tool outside the Dashboard talk to Yorlet as an agent. It can look up records and propose writes. Writes still go through [agent policy](/business-automation/ai/policy) and land in [Approvals](/business-automation/ai/approvals) when they need a person. Create and revoke keys from [API keys](https://dashboard.yorlet.com/developers). To connect Claude or ChatGPT, see [MCP](/business-automation/ai/mcp). Treat an agent key like a password. It is shown once. Anyone with it can look up your records and propose writes. If you think it has leaked, remove it and create a new one. ## Claude and ChatGPT Claude and ChatGPT on the web do not need you to create a key first. When you [connect Yorlet](/business-automation/ai/mcp), Yorlet creates an agent key named **Claude** or **ChatGPT** on the account you choose. Events and Approvals use that name. To disconnect Claude or ChatGPT, remove the matching key from [API keys](https://dashboard.yorlet.com/developers). ## Create an agent key Create a key when you are connecting the ChatGPT desktop app or another MCP client that asks for a token. To create an agent key, follow these steps: 1. Go to the [API keys](https://dashboard.yorlet.com/developers) page. 2. Under **Agent keys**, click **Create agent key**. 3. Enter a **Name**. This is how the agent appears in events and the Approvals inbox — for example `ChatGPT`. 4. Optionally enter a **Note** for where the key is used. 5. Click **Create**. 6. Copy the key and store it somewhere safe. You cannot view it again. You need access to Developers to create a key. The reveal step tells you to use the key as a Bearer token against `POST /v1/mcp`. That is the [MCP](/business-automation/ai/mcp) endpoint you paste into the ChatGPT desktop app. Keys look like `agk_live_…` in production and `agk_test_…` in sandbox. Agent keys are not a substitute for secret or restricted API keys. Use a [secret or restricted key](/development/api-keys) when your own systems call the Yorlet API as an integration, not as an agent. ## Remove an agent key To remove an agent key, follow these steps: 1. Go to the [API keys](https://dashboard.yorlet.com/developers) page. 2. Under **Agent keys**, open the for the key. 3. Click **Remove**. Removing the **Claude** or **ChatGPT** key also disconnects that client’s OAuth access for the account. # Approvals Source: https://docs.yorlet.com/business-automation/ai/approvals Review writes proposed by the assistant and background agents, then approve or deny them. Approvals is the inbox for agent writes that need a person. The [assistant](/business-automation/ai/assistant), the [email agent](/business-automation/inbox/agents), Recover triage, and [Claude or ChatGPT](/business-automation/ai/mcp) can all create them. You can review every approval from the [Approvals page](https://dashboard.yorlet.com/approvals). Approving an action needs the Operations plus or Admin role. Other teammates can still open Approvals and read the queue. ## Approval statuses Every approval has a status: | Status | Description | | ---------- | --------------------------------------------------------------------------------------- | | `pending` | Waiting for someone to approve or deny. The write has not run. | | `executed` | Someone approved it (or policy auto-ran it) and the write succeeded. | | `denied` | Someone denied it, or policy blocked it. Nothing was created. | | `failed` | Approval was given, but the write did not complete. Open the approval to see the error. | | `canceled` | The approval was cancelled and will not run. | The Approvals page has tabs for **Pending**, **Executed**, **Denied**, and **Failed**. Use the split view to read an approval beside the list, or switch to the table view. ## Review an approval Open an approval to see: * The **Action** — for example Create note, Send email, Enrol in Recover, Create task, Progress application, Update viewing, or Create maintenance issue. * The **Agent** that proposed it — for example Yorlet assistant, Email agent, or Recover triage. * **Reasoning** — why the agent thinks the write should happen. * **Policy** — whether this action was set to auto-run, require approval, or deny. * The arguments. For **Send email**, this is the recipient, subject, and body rather than raw fields. ## Approve an action Approving runs the write immediately — sends the email, attaches the note, opens the recovery case, or completes the other action. To approve an approval, follow these steps: 1. Go to the [Approvals page](https://dashboard.yorlet.com/approvals). 2. Open the **Pending** tab. 3. Find the row and click **Approve**, or open the approval and click **Approve**. You can also click **Approve** on the card in the assistant chat. On a pending email from a thread, the chat card also has **Use in reply**. That puts the draft in the Inbox reply box so you can edit it there, and closes the approval without sending. ## Deny an action Denying stops the write. The agent does not retry it. To deny an approval, follow these steps: 1. Go to the [Approvals page](https://dashboard.yorlet.com/approvals). 2. Open the **Pending** tab. 3. Click **Deny** on the row, or open the approval and click **Deny**. 4. Optionally enter a **Reason** for the audit trail. 5. Click **Deny**. ## What creates an approval An approval appears when policy is **Require approval**, or when an auto-run is above an amount cap you set for Recover. Typical sources: * You asked the [assistant](/business-automation/ai/assistant) to send an email, add a note, create a task, enrol in Recover, progress an application, update a viewing, or raise a repair. * Someone emailed the [agent address](/business-automation/inbox/agents) and the email agent drafted a reply. * [Recover triage](/billing/recovery) proposed enrolment, a send, or a note on aged arrears. * [Claude or ChatGPT](/business-automation/ai/mcp) called the same tools. Change which of these wait for you in [Agent policy](/business-automation/ai/policy). # Assistant Source: https://docs.yorlet.com/business-automation/ai/assistant Ask Yorlet AI about your portfolio, then let it draft emails, notes, tasks, and other writes under your policy. The assistant is a chat that knows your customers, owners, invoices, applications, tenancies, viewings, repairs, and [reports](https://dashboard.yorlet.com/reports). Ask it to look something up, run a report, brief you on a record, or propose the next step. Lookups run immediately. Writes follow [agent policy](/business-automation/ai/policy) and wait in [Approvals](/business-automation/ai/approvals) when they need a person. Every team member starts on [Free](/business-automation/ai/plans), with an individual monthly message allowance. Open it from [Home](https://dashboard.yorlet.com/dashboard), or from the side panel on any other page. ## Open the assistant There are two places to chat: * **Home** — a full-page chat at [Home](https://dashboard.yorlet.com/dashboard). Use this for a morning briefing or anything that is not about the page you are already on. * **Side panel** — a chat that slides in from the right. Use this when you have a customer, owner, invoice, application, subscription, tenancy, or Inbox thread open, so the assistant can use that record as context. To open the side panel, follow these steps: 1. Make sure Yorlet AI is available on the account. If you do not see **Assistant** in the sidebar footer, go to [Yorlet AI](https://dashboard.yorlet.com/settings/plans/ai). 2. Click **Assistant** in the sidebar footer, or press **⌘ /** (Control / on Windows). Click the maximize control to widen the panel, or press **Esc** to close it. On Home the side panel stays closed, because the page is already the chat. Press **⌘ /** from any other page when you want the assistant to see the record in front of you. If Yorlet AI is not on the account, Home and the panel explain the product and link to [Yorlet AI](https://dashboard.yorlet.com/settings/plans/ai). ## Ask a question Type in **Ask me anything...** and send. On an empty chat, suggested prompts appear — for example **Who is in arrears?**, **Which applications are stuck on a waitpoint?**, or **Who is viewing today?**. Click a suggestion to put it in the composer, then send. When you have a record open, the panel shows that it is **Using this customer as context** (or owner, invoice, application, subscription, tenancy, or thread). The suggestions then match that page, such as **What's going on with this tenant?** or **Draft a reply to this thread**. After a reply, the assistant may offer follow-up suggestions. Click one to continue in the same chat. The composer shows how many messages you have left this month. Each send counts as one message against your [plan](/business-automation/ai/plans). Ask the assistant to look something up before it writes. For a name, email, or address, it searches first and confirms the right record if there is more than one match. ## Start or switch chats Each conversation keeps its own history. The first reply in a new chat becomes its title. To start a new chat, click **New chat**. To go back to an earlier conversation, follow these steps: 1. Click **History**. 2. Optionally search in **Search conversations…**. 3. Click the conversation you want. On Home, a saved chat is also in the URL as `?chat=…`, so you can bookmark or share a link with yourself. ## What the assistant can look up The assistant searches your account and shows results as cards next to its answer. It can: | Ask for | What you get | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Search** | Find a customer, owner, unit, building, application, tenancy, or invoice by name, email, address, or keyword. | | **Customer briefing** | What is going on with a tenant: current tenancy and unit, open invoices, payment method, open repairs, last note, and last email. | | **Unit briefing** | What is going on with a flat: occupancy, current tenancy, availability, open repairs, and compliance dates that are expired or soon due. | | **Thread briefing** | An [Inbox](/business-automation/inbox/overview) conversation and its message history. Use this before drafting a reply. | | **List arrears** | Past-due open invoices grouped by customer. See [Arrears](/billing/arrears). | | **List stuck applications** | Open [applications](/leasing/applications/manage-an-application) waiting on a step — especially a waitpoint. | | **List upcoming viewings** | Today’s and upcoming [viewings](/leads/viewings). | | **List open repairs** | Open [maintenance](/maintenance/manage-issues) issues, optionally SLA-breached only. | | **List open tasks** | Open staff tasks, oldest due date first. | | **Reports** | Portfolio numbers as a table: rent roll, occupancy, arrears totals, payment volume, owner payouts, deposits, lets agreed, and renewals. Ask for a period or building when you need a slice. | | **Product docs** | How Yorlet itself works. The assistant searches these docs and cites the page it used. | It can also look up a specific customer, owner, invoice, subscription, payment, application, or tenancy when it already has an ID. ## What the assistant can do When you ask it to change something, it proposes the write instead of calling the API behind your back. Default [policy](/business-automation/ai/policy): | Action | What it does | Default policy | | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | **Create note** | Attach an internal note to a customer, invoice, tenancy, or other record. | Auto-execute | | **Create task** / **Complete task** | Create a staff follow-up, or mark one done. Due date defaults to tomorrow if omitted. | Auto-execute | | **Send email** | Email one customer or owner from the [agent address](/business-automation/inbox/agents). New outbound uses your [account branding](/account/branding); a reply on an Inbox thread stays plain text. | Require approval | | **Enrol in Recover** | Send eligible overdue invoices into a [recovery case](/billing/recovery). | Require approval | | **Progress application** | Advance an application past the current step, including a staff waitpoint. | Require approval | | **Update viewing** | Record an outcome or confirm a request: Scheduled, Completed, No show, or Canceled. | Require approval | | **Create maintenance issue** / **Update maintenance issue** | Raise a repair on a unit, or triage status, priority, assignee, or hold. | Require approval | If a write is waiting, the assistant will tell you. Do not assume the action has already happened. The assistant sends one email at a time. If you ask it to email a group, it will ask who first. The assistant cannot approve an owner payout, void an invoice, mark an invoice paid, cancel a tenancy, or complete an application. ## When the assistant wants to write Policy decides what happens next: * **Auto-execute** — the write runs immediately. The chat shows the result. * **Require approval** — an approval appears in the chat and on the [Approvals page](https://dashboard.yorlet.com/approvals). The write has not happened yet. * **Deny** — policy blocks the action. Nothing is created. On a pending email, the card shows the recipient, subject, and body: * **Approve** — send it from the agent address and write the message to the [thread](/business-automation/inbox/overview) in Inbox. * **Deny** — stop the send. * **Use in reply** — put the draft in the Inbox reply box so you can edit it there. This closes the pending approval without sending. * **Details** — open the full approval. If the assistant says an approval is waiting, check [Approvals](/business-automation/ai/approvals). Do not tell a customer that an email has gone out until the status is `executed`. ## Examples These are prompts you can type as-is, or adapt. The assistant looks the records up first. ### Start the morning Open [Home](https://dashboard.yorlet.com/dashboard) and ask: * Who is in arrears? * Which applications are stuck on a waitpoint? * Who is viewing today? * What repairs are open, and which have breached SLA? * What tasks are due? * What’s our rent roll? Ask a follow-up on the same chat, for example **Draft a chase email for the most overdue customer** or **Create a task to review the waitpoint on the oldest application**. ### Look someone up * What’s going on with Sarah Smith? * What’s going on with 12 High Street? * Find the customer with email [alex@example.com](mailto:alex@example.com) * Show invoices for this tenancy If several people match a name, the assistant lists them and asks which one you meant. ### Chase arrears Open a customer who is behind, then in the side panel: * What’s going on with this tenant? * What do they currently owe? * Draft a chase email * Enrol their eligible invoices in Recover * Leave a note that we spoke today and they will pay on Friday Or from Home: **Who is more than 14 days overdue, and does anyone already have Recover open?** ### Reply to Inbox Open a [thread](https://dashboard.yorlet.com/inbox), then: * Who is this and what’s going on? * Draft a reply to this thread * Create a follow-up task Review the email card, then click **Approve** to send, or **Use in reply** to edit it in Inbox first. ### Unblock an application Open the application, or ask from Home: * What’s outstanding on this application? * Catch me up on this applicant * Have they applied with us before? * Progress this waitpoint — referencing is complete Progressing an application waits for approval by default. ### Record a viewing * Who is viewing today? * Mark the 10am viewing at 12 High Street as completed * The 2pm viewing was a no show ### Raise or triage a repair * List open repairs * Raise a leaking radiator at 12 High Street, high priority * Assign this repair to Sam and put it on hold until we have access ### Ask about reports Ask in plain English. The assistant runs the [report](/reporting/dashboard-reports) and shows a table next to its answer. Click **Open in Reports** on the card to see the same report in the [Dashboard](https://dashboard.yorlet.com/reports). * What’s our rent roll? * How many units are vacant? * How much rent did we collect last month? * What’s the arrears total by days overdue? * Show pending owner payouts * How many lets agreed this quarter? * What’s our balance this month? Use **Who is in arrears?** when you want the customers who are behind. Use a report when you want totals, trends, or a snapshot across the portfolio. ### Ask how Yorlet works The assistant can search these docs: * How do I set up Recover? * What is a waitpoint? * How do agent approvals work? It cites the page it used. For a walkthrough you can keep reading, open the cited doc. ## Message allowance Each person has their own monthly allowance: 30 messages on Free, 200 on Standard, and 1,000 on Premium. It resets on the 1st of each month. When you run out, the chat explains that this month’s allowance is used and lets you [request a higher plan](/business-automation/ai/plans). An admin must approve the request before billing starts. Use Home for the questions you repeat every morning, and the side panel when you are already on a record. That keeps chats short and uses fewer messages. # MCP Source: https://docs.yorlet.com/business-automation/ai/mcp Connect Claude or ChatGPT to Yorlet so they can look people up, pull work queues, and propose writes under the same policy as the assistant. You can connect [Claude](https://claude.ai) or [ChatGPT](https://chatgpt.com) to Yorlet. They can then search your account, brief a customer or unit, pull the queues you would open in the morning, run a [report](/reporting/dashboard-reports), and propose follow-up — a note, an email, a task, Recover, or the write that closes the loop. Lookups run immediately. Writes still follow [agent policy](/business-automation/ai/policy) and wait in [Approvals](/business-automation/ai/approvals) when they need a person. MCP is included with [Standard and Premium](/business-automation/ai/plans). One paid seat unlocks it for the organisation, the same as Recover triage and the email agent. The [assistant](/business-automation/ai/assistant) in the Dashboard stays available on Free. This is not a replacement for the [assistant](/business-automation/ai/assistant) in the Dashboard. Use Claude or ChatGPT when you want the same work from a scheduled chat or another app. Use the assistant on [Home](https://dashboard.yorlet.com/dashboard), or in the side panel when you are already on a record in Yorlet. | Environment | MCP URL | | ----------- | ------------------------------- | | Sandbox | `https://api.yorlet.io/v1/mcp` | | Production | `https://api.yorlet.com/v1/mcp` | Once connected, try “Who is in arrears?”, “What’s our rent roll?”, or “Which applications are stuck on a waitpoint?”. You no longer need to paste IDs into the chat. ## Claude Add Yorlet as a **custom connector**. Claude talks to Yorlet over the internet, so the same connector works in [claude.ai](https://claude.ai), Claude Desktop, Cowork, and the Claude mobile app. To add Yorlet in Claude, follow these steps: 1. In Claude, go to **Customize → Connectors**. On a Team or Enterprise plan, an owner must add the connector first under **Organization settings → Connectors**. 2. Click **Add custom connector**. If Claude asks for a type, choose **Web**. 3. Name it **Yorlet**. 4. Paste the MCP URL from the table above. 5. Click **Add**, then **Connect**. Sign in to Yorlet and choose the account Claude may use. 6. In a chat, click **+ → Connectors** and turn **Yorlet** on for that conversation. Connecting Claude creates an [agent key](/business-automation/ai/agent-keys) named **Claude** on that account. Events and Approvals show that name. To disconnect Claude, remove that key on [API keys](https://dashboard.yorlet.com/developers). You do not paste an agent key into Claude. Claude signs in with OAuth. If Claude asks for a request header or an API key, cancel and connect again using only the MCP URL. On Team and Enterprise plans, only an owner can add the connector. Each teammate then clicks **Connect** under **Customize → Connectors** and signs in with their own Yorlet user. If you want Claude to send email, provision an address and set **Agent email** first. See [Agents and Inbox](/business-automation/inbox/agents). ## ChatGPT Yorlet is a remote MCP server. In ChatGPT you add it as a custom app (web) or as an MCP server (desktop). You need ChatGPT Plus, Pro, Business, Enterprise, or Edu — custom connectors are not on the free plan. ### ChatGPT on the web To add Yorlet in ChatGPT on the web, follow these steps: 1. In ChatGPT, open **Settings → Security and login** (on some accounts, **Settings → Apps → Advanced settings**) and turn on **Developer mode**. 2. Open **Settings → Apps**. Click the plus button and create a custom app for a remote MCP server. 3. Name it **Yorlet**. 4. Paste the MCP URL from the table above. 5. If ChatGPT asks how to authenticate, choose **OAuth**. Do not paste an agent key. 6. Save the app, then **Connect**. Sign in to Yorlet and choose the account ChatGPT may use. 7. Start a chat, open the tools menu, choose **Developer mode**, and enable **Yorlet**. Connecting ChatGPT creates an [agent key](/business-automation/ai/agent-keys) named **ChatGPT** on that account. Events and Approvals show that name. To disconnect ChatGPT, remove that key on [API keys](https://dashboard.yorlet.com/developers). You do not paste an agent key into ChatGPT on the web. ChatGPT signs in with OAuth. If ChatGPT asks for a Token or API key, choose OAuth instead, or connect again using only the MCP URL. On Business, Enterprise, or Edu, a workspace admin may need to allow developer mode and custom MCP connectors before these settings appear. If you want ChatGPT to send email, provision an address and set **Agent email** first. See [Agents and Inbox](/business-automation/inbox/agents). ### ChatGPT desktop The ChatGPT desktop app can send a bearer token directly. Create an [agent key](/business-automation/ai/agent-keys) first. To add Yorlet there, follow these steps: 1. Create an [agent key](/business-automation/ai/agent-keys). 2. Open **Settings → MCP servers**. 3. Click **Add server**. 4. Name it **Yorlet**, choose **Streamable HTTP**, and paste the MCP URL from the table above. 5. Enter the agent key as the bearer token. 6. Save, then **Restart**. 7. In the composer, type `/mcp` to confirm Yorlet is connected. Treat the agent key like a password. Anyone with it can look up your records and propose writes on your account. If you think it has leaked, [remove it](/business-automation/ai/agent-keys) and create a new one. A production key will not work against the sandbox URL, and the other way around. Agent keys look like `agk_live_…` in production and `agk_test_…` in sandbox. Other MCP clients that ask for a URL and a bearer token — for example Cursor — use the same MCP URL and the same agent key. ## Look someone up Lookups do not create an [Approvals](/business-automation/ai/approvals) row. They return a short summary: who or what it is, the status and money or dates that matter, and a link to the record in the Dashboard. | Ask for | What you get | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | **Search** | Find a customer, owner, unit, building, application, tenancy, or invoice by name, email, address, or keyword. Use this when you do not have an ID. | | **Customer briefing** | What is going on with a tenant: current tenancy and unit, open invoices, payment method, open repairs, last note, and last email. | | **Thread briefing** | An Inbox conversation and its message history. Use this before drafting a reply. | | **Unit briefing** | What is going on with a flat: occupancy, current tenancy, availability, open repairs, and compliance dates that are expired or soon due. | ## Work queues Named queues are the lists you would open yourself in the morning. Each one is capped, so ask again if you need the next page. | Queue | What it lists | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **List arrears** | Past-due open invoices grouped by customer: amount, days overdue, whether [Recover](/billing/recovery) is already open, and whether a payment method is on file. See [Arrears](/billing/arrears). | | **List stuck applications** | Open [applications](/leasing/applications/manage-an-application) waiting on a step — especially a waitpoint — with the current step, days in step, unit, and applicants. | | **List upcoming viewings** | Today’s and upcoming [viewings](/leads/viewings): unit, lead, start time, and status. | | **List open repairs** | Open [maintenance](/maintenance/manage-issues) issues with priority, SLA state, unit, and reporter. You can ask for SLA-breached work only. | | **List open tasks** | Open staff tasks, oldest due date first. | ## Reports Ask for portfolio numbers the same way you would in the [assistant](/business-automation/ai/assistant). Claude and ChatGPT run the report and return a table of rows — rent roll, occupancy, arrears totals, payment volume, owner payouts, deposits, lets agreed, and renewals. Ask for a period or building when you need a slice. Use a work queue when you want the individual records (who is in arrears). Use a report when you want totals, trends, or a snapshot across the portfolio. ## Propose a write A proposed write is not finished until policy says so. If policy is **Require approval**, open [Approvals](/business-automation/ai/approvals) in Yorlet and approve it there. Do not tell a customer that an email has gone out until the approval status is **Executed**. | Action | What it does | Default policy | | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------- | | **Create note** | Attach an internal note to a customer, invoice, tenancy, or other record. | Auto-execute | | **Create task** / **Complete task** | Create a staff follow-up, or mark one done. Due date defaults to tomorrow if omitted. | Auto-execute | | **Send email** | Send one email from the account’s [agent address](/business-automation/inbox/agents) onto an [Inbox](/business-automation/inbox/overview) thread. New outbound uses your [account branding](/account/branding); a thread reply stays plain text. | Require approval | | **Enrol in Recover** | Enrol eligible overdue invoices in [Recover](/billing/recovery). | Require approval | | **Progress application** | Advance an application past the current step, including a staff [waitpoint](/leasing/applications/manage-an-application). | Require approval | | **Update viewing** | Record an outcome or confirm a request: Scheduled, Completed, No show, or Canceled. | Require approval | | **Create maintenance issue** / **Update maintenance issue** | Raise a repair on a unit, or triage status, priority, assignee, or hold. | Require approval | Sending email from Claude or ChatGPT still emails a real recipient once you approve it. Review the To, subject, and body in Approvals before you click **Approve**. Keep **Send email** and **Enrol in Recover** on **Require approval**. Do not switch those to **Auto-execute** so a scheduled chat can email customers without someone looking first. ## Start from a prompt Claude and ChatGPT also receive named prompts they can start from: * **Morning briefing** — summarise arrears, stuck applications, upcoming viewings, and open repairs. * **Chase arrears** — find overdue rent (14 days by default) and propose who to chase, or a single chase email / Recover enrolment for approval. * **Unblock waitpoint applications** — find applications waiting on staff and propose the next action. Those prompts look work up and draft writes. They do not send email or enrol Recover unless you ask, and those writes still wait in Approvals. Like the assistant, they send one email at a time — if you ask them to email a group, they will ask who first. ## What they cannot do Claude and ChatGPT cannot approve an owner payout, void an invoice, mark an invoice paid, cancel a tenancy, or complete an application. They also cannot search Yorlet’s product docs — use the [assistant](/business-automation/ai/assistant) in the Dashboard for that. ## Troubleshooting * **Claude or ChatGPT asks you to sign in.** That is expected on the web. Complete the Yorlet sign-in and choose an account. Do not add an Authorization request header. * **401 on ChatGPT desktop, or after pasting a key.** The agent key is missing, has extra spaces, or belongs to the other environment. Fix the token and try again. * **403, or a message about Standard or Premium.** The account needs a [paid AI seat](/business-automation/ai/plans). Request Standard or Premium, then connect again. * **The connector adds but no tools appear.** Turn the connector on in that chat (**+ → Connectors** in Claude, **Developer mode** in ChatGPT). * **Lookups fail, or you only see notes, email, and Recover.** You connected before search and work queues were available. In Claude or ChatGPT on the web, click **Connect** again and sign in — Yorlet updates the existing **Claude** or **ChatGPT** key. If you created an agent key yourself, [create a new one](/business-automation/ai/agent-keys) and paste it into the client. * **A send, enrolment, progress, or viewing update did not happen.** Open [Approvals](/business-automation/ai/approvals). Those actions wait for a person by default. * **Send email fails.** Provision an address and set it as the agent address. See [Agents and Inbox](/business-automation/inbox/agents). Agent keys are not a substitute for secret or restricted API keys. Use a [secret or restricted key](/development/api-keys) when your own systems call the Yorlet API as an integration, not as an agent in Claude or ChatGPT. # Yorlet AI Source: https://docs.yorlet.com/business-automation/ai/overview An assistant for every team member, with paid seats for Recover triage, an email agent, and Claude or ChatGPT — and you still in control of what runs. Yorlet AI is an assistant that knows your customers, owners, invoices, applications, tenancies, and reports. Every team member starts on Free. Ask it to look things up, run a report, draft emails, attach notes, create tasks, and propose sending aged arrears to [Recover](/billing/recovery). Anything that changes data follows your [agent policy](/business-automation/ai/policy): it may run on its own, wait in [Approvals](/business-automation/ai/approvals), or be blocked. Open the assistant from [Home](https://dashboard.yorlet.com/dashboard), or press **⌘ /** (Control / on Windows) from any other page. ## Plans Every team member starts on **Free**, with 30 assistant messages each calendar month. Mix **Standard** and **Premium** seats when someone needs more messages, or when you want Recover triage, the email agent, and Claude or ChatGPT for the organisation. Manage seats from [Yorlet AI](https://dashboard.yorlet.com/settings/plans/ai). Team members request an upgrade; an admin approves before anything is billed. See [Plans](/business-automation/ai/plans). If you do not see **Assistant** in the sidebar, Yorlet AI is not available on this account yet. Open [Yorlet AI](https://dashboard.yorlet.com/settings/plans/ai) or talk to your account manager. ## How it works Yorlet AI has three parts you will use every day: * **Assistant** — a chat on Home and in a side panel. Ask a question, or ask it to do something. * **Approvals** — a queue of proposed writes. Approve to run them, or deny to stop them. * **Agent policy** — the rules that decide whether an action auto-runs, waits, or is blocked. Two background agents can also propose work without you opening the chat. They run when the organisation has at least one Standard or Premium seat: * **Email agent** — when someone replies to the agent's address, it drafts a reply for you to approve. See [Agents and Inbox](/business-automation/inbox/agents). * **Recover triage** — when Recover is enabled as well, it reviews aged arrears, reads that customer's [Inbox threads](/business-automation/inbox/overview), and may propose enrolment, a send, or a note. See [Recover](/billing/recovery). The same paid seat lets you connect [Claude or ChatGPT](/business-automation/ai/mcp). ## What the assistant can do The assistant can search your account, brief you on a customer, unit, or thread, pull the queues you would open in the morning — arrears, stuck applications, upcoming viewings, open repairs, and open tasks — and answer questions about [reports](/reporting/dashboard-reports) such as rent roll, occupancy, and payment volume. When you ask, it can also propose these writes: * **Create note** and **Create task** / **Complete task** — these auto-run unless you change policy. * **Send email**, **Enrol in Recover**, **Progress application**, **Update viewing**, and **Create** or **Update maintenance issue** — these wait for approval by default. If a write is waiting, the assistant will tell you it is in Approvals. Do not assume the action has already happened. ## Get started Open the chat, ask questions, and start a new conversation Free, Standard, and Premium seats, message allowances, and upgrades Review proposed writes and approve or deny them Choose which actions auto-run, wait, or are blocked Review threads in Inbox, set up the email channel, and let agents send Connect Claude or ChatGPT so they can propose writes in Yorlet # Plans Source: https://docs.yorlet.com/business-automation/ai/plans Every team member starts on Free. Mix Standard and Premium seats when you need more messages, Recover triage, the email agent, or Claude and ChatGPT. Yorlet AI is billed per seat, not as a single plan for the whole account. Every team member starts on **Free**. You can mix Free, Standard, and Premium seats in one organisation. Manage your seat from [Yorlet AI](https://dashboard.yorlet.com/settings/plans/ai), or open [Your plans](https://dashboard.yorlet.com/settings/plans) and find **Yorlet AI**. ## What each plan includes | Plan | Free | Standard | Premium | | ---------------------------------------------------------------------------------------- | --------- | ---------------------------------- | -------------------------------------------------------------- | | Price | No charge | £20 / seat / month, or £192 / year | £100 / seat / month, or £960 / year | | Assistant messages / month | 30 | 200 | 1,000 | | [Assistant](/business-automation/ai/assistant) | Yes | Yes | Yes | | [Claude or ChatGPT](/business-automation/ai/mcp) | No | Yes, for the organisation | Yes, for the organisation | | [Recover triage](/billing/recovery) and [email agent](/business-automation/inbox/agents) | No | Yes, for the organisation | Yes, for the organisation, with higher Recover triage capacity | Annual billing is 20% off. Paid prices are plus VAT. Message allowances are individual and reset on the 1st of each month. One paid seat — Standard or Premium — unlocks Recover triage, the email agent, and [Claude or ChatGPT](/business-automation/ai/mcp) for the whole organisation. Assistant message allowances stay per person. Paid seats can be billed by another account in your organisation. If they are, the Yorlet AI page tells you which account an admin needs to approve your upgrade on. ## Request an upgrade Anyone can request a higher plan. Billing does not start until an admin approves it. To request an upgrade, follow these steps: 1. Go to [Yorlet AI](https://dashboard.yorlet.com/settings/plans/ai). 2. Under **Choose your plan**, pick **Monthly** or **Annual**. 3. On **Standard** or **Premium**, click **Request Standard**, **Request Premium**, or **Request annual billing**. You can also request from the assistant when you have used this month’s allowance. A pending request shows on **Your plan**. Click **Cancel request** if you want to choose a different plan instead. You can only have one pending request at a time. To move to a lower plan, ask an admin to change your seat under **Team members**. ## Assign seats Admins assign a plan to each person. Changes apply immediately. Paid plan changes may include a prorated billing adjustment, and may continue to checkout if payment setup is needed. To change someone’s plan, follow these steps: 1. Go to [Yorlet AI](https://dashboard.yorlet.com/settings/plans/ai). 2. Under **Team members**, find the person. You can search by name or email. 3. Click **Edit plan**. 4. Choose a **Plan** — Free, Standard, or Premium. 5. For a paid plan, choose **Billing** — **Monthly** or **Annual · save 20%**. 6. Click **Save changes**. Saving a change also clears that person’s pending upgrade request. The same page shows how many seats you have on each plan, and the monthly and annual totals. ## Approve an upgrade request When a teammate requests a higher plan, it appears under **Upgrade requests**. To approve or decline a request, follow these steps: 1. Go to [Yorlet AI](https://dashboard.yorlet.com/settings/plans/ai). 2. Under **Upgrade requests**, find the person. 3. Click **Approve upgrade**, or **Decline**. Approving may continue to checkout if the organisation does not yet have a payment method for that billing interval. ## Message allowance The **Your plan** section shows how many messages you have used this month, how many are left, and that the allowance resets on the 1st of each month. Each send in the [assistant](/business-automation/ai/assistant) counts as one message. When you reach the cap, the chat stops sending until next month, unless you move to a higher plan. # Agent policy Source: https://docs.yorlet.com/business-automation/ai/policy Decide which agent actions run on their own, which wait in Approvals, and which are blocked. Agent policy is the rulebook for every write the assistant or a background agent proposes. Change it from [Settings → Agents](https://dashboard.yorlet.com/settings/agents). You need the admin role to change agent policy. ## Modes Each action uses one of three modes: * **Require approval** — the write appears in [Approvals](/business-automation/ai/approvals) and waits for a teammate. * **Auto-execute** — the write runs as soon as it is proposed. * **Deny** — the write is blocked. An approval is still recorded as denied, so you can see what was attempted. **Default** applies to any action that does not have its own row. Out of the box, the default is **Require approval**. ## Default settings Yorlet ships with these action rules: * **Create note** — **Auto-execute**. Internal notes are treated as low risk. * **Create task, Complete task** — **Auto-execute**. Staff follow-ups are treated as low risk. * **Send email** — **Require approval**. Customer-facing mail waits for a person. * **Enrol in Recover** — **Require approval**. Opening a recovery case waits for a person. * **Progress application** — **Require approval**. Moving an applicant forward waits for a person. * **Update viewing** — **Require approval**. Recording an outcome waits for a person. * **Create maintenance issue, Update maintenance issue** — **Require approval**. Raising or triaging a repair waits for a person. You can change any of these. Sending email yourself, with an API key, or from a [workflow](/business-automation/workflows/actions#send-email) is not affected — policy only applies to agents. ## Change a rule To change agent policy, follow these steps: 1. Go to [Settings → Agents](https://dashboard.yorlet.com/settings/agents). 2. Set **Default** if you want a new fallback for actions without their own row. 3. Under **Actions**, set the mode for each write. 4. Click **Save**. Click **Cancel** to discard unsaved changes. ## Amount caps for Recover **Enrol in Recover** can also use an amount cap. The field appears when the mode is not **Deny**. * If the mode is **Auto-execute**, **Require approval above** sends larger enrolments to Approvals and auto-runs smaller ones. * If the mode is **Require approval**, **Auto-run up to** auto-runs smaller enrolments and still waits on larger ones. Leave the amount empty if every Recover enrolment should follow the mode on its own. ## Agent email The **Agent email** setting on the same page chooses which provisioned address the email agent, Recover triage, the assistant, and [Claude or ChatGPT](/business-automation/ai/mcp) send from. If you have not provisioned one yet, click **Provision one** to open [Settings → Emails](https://dashboard.yorlet.com/settings/emails). See [Agents and Inbox](/business-automation/inbox/agents). # Bank reconciliation Source: https://docs.yorlet.com/business-automation/client-accounting/bank-reconciliation Learn how to reconcile your Yorlet and owner payouts with cash in your bank. The bank reconciliation report enables you to reconcile payouts paid to you by Yorlet and owner payouts you’ve made to third parties with the cash in your bank account, helping you track the cash from your business as it moves from Yorlet to your bank and your bank to owners. ## How bank reconciliation works To enable the reconciliation, link your bank account on Yorlet and approve access for reconciliation. After you provide access to your bank account, Yorlet automatically reconciles the Yorlet payouts with the corresponding deposit in your bank account to determine the amount received and any outstanding balance. You can then access the details of each Yorlet payout, the bank deposit, and the corresponding reconciliation statuses from the Dashboard. ### Link bank account To link your bank account, follow these steps: 1. **Initiate the process**: Click the **Link bank account** button on the [linked accounts page](https://dashboard.yorlet.com/settings/linked_accounts). 2. **Select your bank**: Review the linked account terms, and make sure you select the bank where your Yorlet payouts are being deposited. 3. **Select the account**: Select the account where your Yorlet payouts are being deposited. 4. **Confirmation**: You’ll see a success message when the link is successful. This might take a few minutes to complete. Yorlet will now automatically reconcile the Yorlet payouts with the corresponding deposit in your bank account. Please note that the reconciliation process might take a few hours to complete, we will email you once the reconciliation is complete. # Customer credit balances Source: https://docs.yorlet.com/business-automation/client-accounting/customer-credit-balances Learn how to view the credit balances of your customers. The customer credit balances report enables you to view the total balances of your customers, helping you track the cash from your business is holding on behalf of your customers. ## How customer credit balances work To view the cash balances of your owners, navigate to the report and click the **Owner cash balances** tab on the [Reports page](https://dashboard.yorlet.com/reports/hub). The customer credit balances report includes multiple types of reports: * **Summary**: This provides a high-level overview of the total cash balance of your owners. * **Itemized**: This provides an itemized list of the cash balances of each owner. ### Customer credit balances summary To view the summary report, navigate to the report and click the **Summary** tab. | Column | Description | | ----------------- | ----------------------------------- | | **Currency** | The currency for the balance. | | **Total balance** | The total balance of all customers. | ### Customer credit balances itemized To view the itemized report, navigate to the report and click the **Itemized** tab. | Column | Description | | ------------ | ---------------------------- | | **Customer** | The customer name. | | **Balance** | The balance of the customer. | # Deposit balances Source: https://docs.yorlet.com/business-automation/client-accounting/deposit-balances Learn how to view the deposit balances of your clients. The deposit balances report enables you to view the total balance of deposits held on behalf of your customers. ## How deposit balances work To view the deposit balances of your customers, navigate to the report and click the **Deposit balances** tab on the [Reports page](https://dashboard.yorlet.com/reports/hub). # Client Accounting Source: https://docs.yorlet.com/business-automation/client-accounting/overview Learn how to manage client accounting with Yorlet. Client accounting is the process of managing financial transactions between you and your clients. Yorlet provides tools to help you manage your client accounting, including bank reconciliation and financial reporting. Automate the process of comparing financial records to close your books View the total balances of your customers View the total balance of deposits held on behalf of your customers View the cash balances of your owners # Owner cash balances Source: https://docs.yorlet.com/business-automation/client-accounting/owner-cash-balances Learn how to view the cash balances of your owners. The owner cash balances report enables you to view the cash balances of your owners, helping you track the cash from your business as it moves from Yorlet to your owners. ## How owner cash balances work To view the cash balances of your owners, navigate to the report and click the **Owner cash balances** tab on the [Reports page](https://dashboard.yorlet.com/reports/hub). You can then see a summary of the total cash balance of your owners, to view an itemised list of the cash balances of each owner, change the **Report type** to **Itemized**. # Agents and Inbox Source: https://docs.yorlet.com/business-automation/inbox/agents How the assistant, email agent, Recover triage, Claude, and ChatGPT use Inbox threads. Agents do not have a separate mailbox. They read and write the same [threads](/business-automation/inbox/overview) you see in Inbox. On the email channel they send from a [provisioned address](/business-automation/inbox/email) on your account. The email agent and Recover triage run when the organisation has at least one [Standard or Premium](/business-automation/ai/plans) seat. The same paid seat unlocks [Claude or ChatGPT](/business-automation/ai/mcp). The [assistant](/business-automation/ai/assistant) is available on Free. Set the address they send from in [Settings → Agents](https://dashboard.yorlet.com/settings/agents), under **Agent email**. You can change it at any time. If you delete that address, pick another provisioned one before agents send again. The first address you provision is marked as the agent address automatically. Later addresses stay available for people to send from; they are not the agent address unless you select them here. ## How agents send Every agent send on email — from the [assistant](/business-automation/ai/assistant), the email agent, [Recover triage](/billing/recovery), or [Claude or ChatGPT](/business-automation/ai/mcp) — creates a **Send email** [approval](/business-automation/ai/approvals) when [policy](/business-automation/ai/policy) is **Require approval**. That is the default for sending on the email channel. The approval shows the **To**, **From**, **Subject**, and body. Approving it sends the message and writes it to the thread in [Inbox](/business-automation/inbox/overview). Denying it leaves the thread as it was. People sending from the Dashboard or [API](/development/api-keys) with the **Send email** permission do not go through Approvals. That path is a human send, not an agent action. A [workflow](/business-automation/workflows/actions#send-email) send is the same: it goes out when the step runs. ## Email agent When someone emails the **agent address**, Yorlet: 1. Matches the sender to a customer or owner when it can. 2. Adds the message to a [thread](/business-automation/inbox/overview) in Inbox. 3. Skips automatic mail such as out-of-office replies. 4. Drafts a reply and creates a **Send email** approval. Approve the draft from [Approvals](/business-automation/ai/approvals) or from the card in the assistant. On a pending email, the chat card also has **Use in reply**, which puts the draft in the Inbox reply box so you can edit it there. If the situation needs a person — hardship, a complaint, or missing context — the agent proposes an internal note instead of a reply. Mail to addresses that are not the agent address is still stored in Inbox. The agent does not draft a reply for those. Point customers at the agent address when you want inbound mail to produce a draft on that thread. Yorlet will not keep auto-replying in a loop. Automated mail is ignored, and a thread has a daily cap on outbound messages. ## Recover triage [Recover](/billing/recovery) can read a customer's existing Inbox threads before it proposes the next step. If a conversation is already underway, it can propose a **Send email** on that thread instead of opening a new recovery case. Those sends use the same agent address and the same Approvals queue. ## Assistant, Claude, and ChatGPT The [assistant](/business-automation/ai/assistant) can send on a thread when you ask it to, using the agent address and optionally an existing conversation in Inbox. [Claude and ChatGPT](/business-automation/ai/mcp) that connect over MCP can look records up and propose writes — including **Send email**. Calling that tool still creates an approval. Give them an [agent key](/business-automation/ai/agent-keys), not a secret API key. See [MCP](/business-automation/ai/mcp) for how to add Yorlet as a connector. Do not switch **Send email** to **Auto-execute** until you have watched a run of drafts. The default **Require approval** mode is there so a bad recipient or body cannot leave the account without someone looking at it. # Email Source: https://docs.yorlet.com/business-automation/inbox/email Email is the channel Inbox uses today. Provision sending addresses, bring a custom domain, and send from Yorlet. Email is how most [Inbox](/business-automation/inbox/overview) threads start today. Provision an address, optionally on a domain you already own, then send from the Dashboard, the API, or an [agent](/business-automation/inbox/agents). Replies land on the same thread in Inbox. Manage addresses from [Settings → Emails](https://dashboard.yorlet.com/settings/emails). Open conversations from the [Inbox](https://dashboard.yorlet.com/inbox). ## Provision an address You can provision more than one address. The first one on the account is marked as the agent address. Names such as `support`, `noreply`, and `admin` are reserved. To provision an address, follow these steps: 1. Go to [Settings → Emails](https://dashboard.yorlet.com/settings/emails). 2. Under **New address**, enter a **Local part** — for example `vita` for [vita@yorlet.email](mailto:vita@yorlet.email). 3. Choose a **Domain**. **Yorlet-managed** uses yorlet.email in production, and sandbox.yorlet.email in the [sandbox](/api/environments). A verified custom domain appears in the list once it is live. 4. Optionally enter a **Display name** for the From header. 5. Choose **Matching** — **Customers first** or **Owners first**. When an inbound sender matches both a customer and an owner, Yorlet uses this type. Defaults to customers. 6. Wait for availability to confirm the address is free, then click **Provision**. Delete an address from its row if you no longer need it. If you delete the agent address, pick another one in [Settings → Agents](https://dashboard.yorlet.com/settings/agents). Set which address agents send from in [Settings → Agents](https://dashboard.yorlet.com/settings/agents), under **Agent email**. See [Agents](/business-automation/inbox/agents). ## Custom domains Bring your own domain if you want customers to see mail from an address you already own. Add a subdomain such as `mail.acme.com` so Yorlet’s receiving records do not clash with your existing mailbox. To add a custom domain, follow these steps: 1. Go to [Settings → Emails](https://dashboard.yorlet.com/settings/emails). 2. Under **Add domain**, enter the domain and click **Add**. 3. Copy the **Type**, **Name**, and **Value** records to your DNS provider. 4. Click **Verify**. The status badge moves from **pending** to **verified** once the records check out, or to **failed** if they do not. You can click **Verify** again after you have fixed DNS. Delete a domain if you no longer want it on the account. Once a domain is **verified**, it appears in the address **Domain** list. Deleting a custom domain stops Yorlet from sending and receiving on it. Addresses that still use that domain will not be able to send until you provision them on another verified domain. ## Send on a thread Anyone with the **Send email** permission can send from a provisioned address. That includes Dashboard users and [API keys](/development/api-keys). Agent sends — from the assistant, the email agent, Recover triage, or [Claude or ChatGPT](/business-automation/ai/mcp) — still follow [agent policy](/business-automation/ai/policy) and wait in [Approvals](/business-automation/ai/approvals) by default. A [workflow](/business-automation/workflows/actions#send-email) can also send when its trigger fires; that path does not wait in Approvals. You can send to a customer, an owner, or a raw email address, optionally on an existing [thread](/business-automation/inbox/overview). The send is stored as an outbound message on that thread’s timeline in Inbox. A send can be **plain text**, or **branded** so the body is wrapped in your [account branding](/account/branding) — logo, colours, and support details. Workflows default to branded. The assistant and Claude or ChatGPT use branded for new outbound, and plain text when they reply on a thread. To send from the Dashboard, click **New conversation** on [Inbox](https://dashboard.yorlet.com/inbox), or on a customer or owner page. See [Inbox](/business-automation/inbox/overview). ## Test inbound mail In the [sandbox](/api/environments), you can simulate an inbound email without sending a real message. This creates a received message on a thread, the same way a customer or owner emailing a provisioned address would. To simulate inbound mail, follow these steps: 1. Go to [Inbox](https://dashboard.yorlet.com/inbox). 2. Click **Simulate inbound**. 3. Choose who the mail is from — a customer, an owner, or a raw email address — and which provisioned address it is to. Leave **To** as the agent address if you want the [email agent](/business-automation/inbox/agents) to draft a reply. 4. Enter a **Subject** and **Body**, then click **Simulate**. You can also simulate a reply from an open thread. The new message is added to that conversation. # Inbox Source: https://docs.yorlet.com/business-automation/inbox/overview Review conversations with customers and owners as threads. Email is the channel Inbox uses today. Inbox is where conversations live. Each conversation is a **thread** — one ongoing exchange with a customer or owner, on a channel. **Email** is the channel you have today. Later channels would use the same Inbox, with their own channel badge. Open Inbox from the sidebar, or from the [Inbox](https://dashboard.yorlet.com/inbox) page. Provision addresses, bring a domain, and send on the email channel How the assistant, email agent, and Recover triage use Inbox threads ## Threads A thread groups messages between your account and one other party on a channel. On email, that is one of your [provisioned addresses](/business-automation/inbox/email) and one other mailbox. Yorlet matches a new message to an existing thread when it can — using the message headers if this is a reply, otherwise the address plus subject. Each row shows: * The **subject**, or the other party’s address if there is no subject * The **channel** — `email` today * Whether the thread is **Open** or **Closed** * When the last message was sent or received Tabs filter **Open** and **Closed** threads. Open a thread to read its **timeline**. That list is paginated and includes more than messages: inbound and outbound mail, plus status and assignee changes. **Inbound** is what you received; **outbound** is what you sent. Yorlet tries to attach the other party to a [customer](/customers) or [owner](/owners) when their address matches a record on the account. Threads are channel-neutral. Email is the only channel today; a later channel such as SMS would appear in the same Inbox with its own channel badge. ## Start a conversation You can email a customer or owner from Inbox, or from their page. You need a [provisioned address](/business-automation/inbox/email) first. To start a conversation from Inbox, follow these steps: 1. Open [Inbox](https://dashboard.yorlet.com/inbox). 2. Click **New conversation**. 3. Choose **Customer** or **Owner**, then pick who to email. 4. Optionally choose the **From** address. It defaults to the agent address. 5. Enter a **Subject** and **Message**, then click **Send**. The send opens as a thread in Inbox. To start a conversation from a customer or owner, follow these steps: 1. Open the [customer](https://dashboard.yorlet.com/customers) or [owner](https://dashboard.yorlet.com/owners). 2. Click **New** on the **Inbox** section, or open **Actions** and click **New conversation**. 3. Enter a **Subject** and **Message**, then click **Send**. The customer or owner must have an email address on their record. ## How a conversation starts When someone emails a [provisioned address](/business-automation/inbox/email): 1. Yorlet matches the recipient to that address. 2. It matches the sender to a customer or owner when it can. 3. It adds the message to a thread in Inbox — creating one if needed. 4. Automated mail such as out-of-office replies is stored, but the [email agent](/business-automation/inbox/agents) does not draft a reply. Mail to any provisioned address is stored in Inbox, not only the agent address. ## Agents [Agents](/business-automation/inbox/agents) read and write the same threads you see in Inbox: * The **email agent** drafts a reply on a thread when someone emails the agent address, if the organisation has a [paid AI seat](/business-automation/ai/plans). * **Recover triage** reads a customer’s threads before it proposes enrolment or a send, on the same paid seats. * The [assistant](/business-automation/ai/assistant) and [Claude or ChatGPT](/business-automation/ai/mcp) can send on a thread when you ask them to. Those sends still follow [agent policy](/business-automation/ai/policy). Approve them from [Approvals](/business-automation/ai/approvals). A [workflow](/business-automation/workflows/actions#send-email) can also send when its trigger fires. That send is stored on a thread in Inbox, but it does not wait in Approvals. # Actions Source: https://docs.yorlet.com/business-automation/workflows/actions Use workflow steps to create tasks, notes, invoices, emails, letters, and more. Actions are the steps that do work. Click **Add step** on the canvas to open **Add a step**, then search or browse by area and pick an action. Select the step and fill in its fields in the side panel. Most text and number fields accept [variables](/business-automation/workflows/variables), so you can pull in the trigger record or the output of an earlier step. Actions are grouped the same way as in **Add a step**. **Send letter**, **Grant loyalty points**, and **Create maintenance issue** only appear if that product is enabled on your account. ## Core ### Create task Create a task assigned to a teammate. * **Title** and **Description** — what the task is. You can insert variables into both. * **Due date** — when the task is due. Choose **When the action runs**, **After the action runs** (minutes, hours, days, or weeks), or a custom value. For example, due one day after the run is `{{ now + 1d }}`. * **Priority** — **Low**, **Medium**, **High**, or **Urgent**. * **Status** — **To do**, **In progress**, or **Done**. * **Assignee** — the teammate who should pick it up. ### Create note Attach a note to a record. * **Text** — the note body. * **Parent type** — the kind of record to attach to, such as `customer`, `invoice`, `tenancy`, `unit`, `application`, or `maintenance.issue`. * **Parent ID** — the record ID. For a database event, this is often `{{ trigger.object.id }}`. ### Send email Send an email to a customer, owner, or address. The email is sent as soon as the step runs, from your [agent address](/business-automation/inbox/agents) unless you set **From**. The send is stored as an outbound message in [Inbox](/business-automation/inbox/overview). You need a [provisioned address](/business-automation/inbox/email) first. * **Recipient type** — **Customer**, **Owner**, or **Email address**. * **Recipient** — the customer ID, owner ID, or email address, matching the recipient type. Defaults to `{{ trigger.object.customer }}` when the trigger has a customer. Inside a loop, use `{{ loop.item.id }}`. * **Subject** — the email subject. You can insert variables. * **Body** — the plain-text message. Do not start with "Subject:" — that belongs in **Subject**. You can insert variables, for example `Hi {{ trigger.object.customer_name }}`. * **Template** — **Branded** or **Plain text**. **Branded** wraps the body in your [account branding](/account/branding) — logo, colours, and support details. **Plain text** sends the body as-is, which is better for a reply on an existing thread. Defaults to **Branded**. * **From** — optional. A provisioned sending address. Leave blank to use the account’s agent address. * **Thread** — optional. An Inbox thread to reply on. Leave blank to start a new conversation. The recipient needs an email address on their record when you send to a customer or owner. Unlike the [assistant](/business-automation/ai/assistant), a workflow send does not wait in [Approvals](/business-automation/ai/approvals). Only publish a workflow when you are happy with the recipient, subject, and body. ### Update unit fees Set the percentage management fee on a unit, and optionally the tax. * **Unit ID** — the unit to update. Defaults to `{{ trigger.object.unit }}` when the trigger has a unit. * **Management fee** — the percentage charged to the landlord, for example `8` for 8%. * **Tax** — the VAT rate applied to the fee, for example `20`. Leave blank to keep the current rate. ## Billing ### Create invoice Create an invoice with a single line item for a customer. See [Invoices](/billing/invoices). * **Customer** — the customer ID. Defaults to `{{ trigger.object.customer }}` when the trigger has a customer. * **Amount** — the line item amount in the smallest currency unit, such as pence. * **Description** — the line item description, for example a late payment fee. * **Collection method** — **Send invoice** or **Charge automatically**. * **Finalize now** — turn this on to finalise the invoice immediately so it can be sent or charged. This is on by default. Amounts are stored in pence. If you later print the amount in a letter, insert the field and choose **Currency** from **Format**. See [Variables](/business-automation/workflows/variables). ## Letters ### Send letter Print and post a letter from a template. The letter is sent as soon as the step runs — it does not stay as a draft. See [Send a letter](/letters/send-a-letter). * **Template** — the letter template to copy content from. * **Recipient type** — **Customer** or **Owner**. * **Recipient** — the customer or owner ID, matching the recipient type. * **Delivery** — **Standard** or **Premium**. * **Name** — optional. Defaults to the template name if you leave it blank. If the template has variables, fill in each one. You can insert a field from the trigger. The recipient needs a name and address, and your account needs a return address, the same as when you send a letter yourself. ## Loyalty ### Grant loyalty points Grant points from a loyalty programme to a customer, resident, or email. * **Loyalty programme** — the programme to grant points from. * **Recipient type** — **Customer**, **Email**, or **Resident**. * **Recipient** — the customer ID, resident ID, or email, matching the recipient type. Inside a loop, use `{{ loop.item.id }}`. * **Points** — optional override of the programme's default points. Leave blank to use the programme reward. * **Spend amount** — required for earn-rate programmes. The spend amount in the smallest currency unit, such as pence. * **Statement descriptor** — optional text that appears on the customer's statement. * **Expires at** — optional. When the granted points expire. ## Maintenance ### Create maintenance issue Raise a maintenance issue, optionally against a unit or application. See [Manage issues](/maintenance/manage-issues). * **Name** and **Description** — what needs fixing. * **Type** — **Internal**, **Planned**, or **Customer request**. * **Priority** — **Low**, **Medium**, **High**, **Urgent**, or **Critical**. * **Unit ID** — optional. Defaults to `{{ trigger.object.unit }}` when the trigger has a unit. * **Application ID** — optional. Unlike creating an issue from the Dashboard, a unit is optional here so you can raise work from triggers that do not have one. # Conditions and loops Source: https://docs.yorlet.com/business-automation/workflows/conditions-and-loops Branch a workflow with If / else, or repeat steps for every item in a list with For each. Logic steps sit alongside actions on the canvas. Click **Add step**, then in **Add a step** choose **Logic**, or search for **If / else** or **For each**. ## If / else **If / else** branches the workflow. Steps on the **Yes** path run when the conditions pass. Steps on the **No** path run when they do not. To add a condition, follow these steps: 1. Click **Add step** and choose **If / else**. 2. Select the step. In the side panel, set **Match**: * **All conditions must pass** — every row must be true (and). * **Any condition can pass** — one true row is enough (or). 3. Click **Add** to create a condition row. 4. Enter the left value, choose an operator, and enter the right value when the operator needs one. Both sides can be a literal or a `{{ }}` expression. 5. Click **Add step** on the **Yes** or **No** branch to add the steps that should run on that path. If you add no conditions, the workflow always follows the **Yes** branch. ### Operators | Operator | When it passes | | ------------------------- | ------------------------------------------------------------- | | **Equals** | The two values are the same. | | **Does not equal** | The two values are different. | | **Greater than** | The left value is greater than the right. | | **Greater than or equal** | The left value is greater than or equal to the right. | | **Less than** | The left value is less than the right. | | **Less than or equal** | The left value is less than or equal to the right. | | **Contains** | The left value includes the right value. | | **Does not contain** | The left value does not include the right value. | | **Is empty** | The left value is missing or blank. No right value is needed. | | **Is not empty** | The left value has a value. No right value is needed. | A typical pattern is a **Database event** trigger for `invoice.paid`, then an **If / else** that checks `{{ trigger.object.total }}` is **Greater than** a threshold, with a **Create task** on the **Yes** branch. ## For each **For each** repeats the steps on its **Each item** branch once per item in an array, then continues along the **Then** branch. To add a loop, follow these steps: 1. Click **Add step** and choose **For each**. 2. Select the step and set **Array** to an expression that resolves to a list, for example `{{ trigger.object.customers }}`. 3. Click **Add step** on the **Each item** branch and configure the steps to run for every item. 4. Optionally add steps on the **Then** branch to run after the loop finishes. Inside the **Each item** branch you can insert: * `{{ loop.item }}` — the current item * `{{ loop.item.id }}` — the current item's ID, when the item is a record * `{{ loop.index }}` — the current item's position, starting at 0 A loop can run for at most 50 items. If the array is longer, the run fails. Use **For each** when a trigger has a list of people — for example sending an email or granting loyalty points to every customer on a tenancy, with **Recipient** set to `{{ loop.item.id }}`. # Create a workflow Source: https://docs.yorlet.com/business-automation/workflows/create-a-workflow Name a workflow, choose a trigger, add steps, and publish it so it can run. Build workflows on a visual canvas. You pick a trigger, add steps, and configure each one in the side panel. You can save a draft while you work, then publish when you are ready for it to run. ## Create a workflow To create a workflow, follow these steps: 1. Go to the [Workflows page](https://dashboard.yorlet.com/workflows). 2. Click **New workflow**. 3. Click **Workflow name** at the top and enter a name. You cannot save until the workflow has a name. 4. Select the **Trigger** on the canvas, then choose a **Trigger type** and complete its settings. See [Triggers](/business-automation/workflows/triggers). 5. Click **Add step** on the canvas. In **Add a step**, search or browse by area, then choose an action, **If / else**, or **For each**. 6. Select the step and fill in its fields in the side panel. Use **Insert variable** to pull in values from the trigger or earlier steps. See [Variables](/business-automation/workflows/variables). 7. Click **Save draft** to keep working, or **Publish** to make the workflow **Active**. You can also click **Create your first workflow** from the empty state if you do not have any workflows yet. You need both a name and a trigger before **Save draft** and **Publish** become available. ## Add and remove steps Click **Add step** (the plus control on the canvas) to insert a step. **Add a step** opens so you can search or browse by area: * **All** — every step. * **Logic** — **If / else** and **For each**. See [Conditions and loops](/business-automation/workflows/conditions-and-loops). * **Core**, **Billing**, **Letters**, **Loyalty**, and **Maintenance** — the actions for that area. See [Actions](/business-automation/workflows/actions). Type in **Search steps...** to filter by name. If an area has no matches, click **Search all areas**. Select a step or the trigger to configure it in the side panel. If nothing is selected, the panel shows **Nothing selected**. To remove a step, hover it and click **Remove step**. If later steps still refer to it, Yorlet warns you and asks **Remove it anyway?** ## Save and publish * **Save draft** stores the workflow with status **Draft**. It will not run. * **Publish** stores the workflow with status **Active**. It runs the next time the trigger fires. If any fields have broken expressions, Yorlet lists them and asks **Publish anyway?** before it publishes. Fix the references if you can — a broken expression can cause the run to fail. See [Variables](/business-automation/workflows/variables). Publishing makes the workflow live immediately. Only publish when you are happy with the trigger and every step. ## Activate and deactivate Open a workflow from the [Workflows page](https://dashboard.yorlet.com/workflows) to see its **Trigger**, **Steps**, and **Recent runs**. From there you can: * Click **Edit workflow** to return to the canvas. * Click **Activate** to start an **Inactive** or **Draft** workflow. * Click **Deactivate** to stop an **Active** workflow without deleting it. Only **Active** workflows run. Deactivating is the safest way to pause a workflow you still want to keep. ## Edit a workflow To change a published workflow, follow these steps: 1. Open the workflow. 2. Click **Edit workflow**. 3. Update the name, trigger, or steps. 4. Click **Publish** to apply the changes and keep the workflow **Active**. **Save draft** sets the workflow to **Draft**, so it will stop running until you publish or activate it again. # Workflows Source: https://docs.yorlet.com/business-automation/workflows/overview Automate your operations by reacting to events and running steps automatically. Workflows is a no-code automation engine built into Yorlet. You choose what starts a workflow, then add the steps Yorlet should run — create a task, attach a note, send an email, send a letter, raise a maintenance issue, and more — without leaving the Dashboard. You can view and manage every workflow from the [Workflows page](https://dashboard.yorlet.com/workflows). Workflows is billed on a pay-as-you-go basis. You are charged for each action step that succeeds. See [list pricing](https://www.yorlet.com/pricing#workflows). ## Enable Workflows Workflows is a pay-as-you-go add-on. To enable it, follow these steps: 1. Go to [Your plans](https://dashboard.yorlet.com/settings/plans). 2. Find **Workflows** and click **Get started**. 3. Complete checkout. Once enabled, you can create workflows from the [Workflows page](https://dashboard.yorlet.com/workflows). ## How a workflow works Every workflow has three parts: * **Trigger** — what starts the workflow. For example, a tenancy being activated, an invoice becoming past due, or a request from your own systems. * **Steps** — what happens next. Steps can be actions (create a task, send an email, send a letter), **If / else** branches, or **For each** loops. * **Runs** — each time the trigger fires, Yorlet records a run so you can see what happened. Only **Active** workflows run. A workflow can be: * **Draft** — saved but not live. Use this while you are still building. * **Active** — published and running whenever the trigger fires. * **Inactive** — kept in your list, but it will not run until you click **Activate**. ## Get started Name a workflow, choose a trigger, add steps, and publish it Choose what starts a workflow — events, invoices, tenancies, or the API Create tasks, notes, invoices, emails, letters, and more Branch with If / else, or repeat steps with For each Insert values from the trigger, earlier steps, and the time the workflow ran See what a workflow did and troubleshoot failed steps # Runs Source: https://docs.yorlet.com/business-automation/workflows/runs See what a workflow did each time it ran, and troubleshoot failed steps. Each time a trigger fires, Yorlet records a **workflow run**. Use runs to confirm a workflow is doing what you expect, and to see why a step failed. ## View recent runs Open a workflow from the [Workflows page](https://dashboard.yorlet.com/workflows). The **Recent runs** section lists every run for that workflow. The table shows: * **Status** — **Running**, **Succeeded**, or **Failed**. * **Run** — the run ID. * **Steps** — how many steps ran. If any failed, the count includes how many failed. * **Created** — when the run started. A workflow that is **Draft** or **Inactive** will not create new runs. Publish or click **Activate** first. See [Create a workflow](/business-automation/workflows/create-a-workflow). ## Open a run Click a run to open its detail page. The page is titled **Workflow run** and has three sections: * **Overview** — **Status**, **Started**, and **Steps**. * **Trigger payload** — the data that started the run, such as the event and the record, or the API input. * **Steps** — each step that ran, in order. If the run failed, a **Run failed** banner appears at the top. ## Step results Each step shows the action name, or **Condition** / **For each** for logic steps, and a status: * `succeeded` — the step completed. * `failed` — the step stopped with an error. * `skipped` — the step did not run, for example because the workflow took the other branch. Condition steps also show a `true branch` or `false branch` badge for the path they took. Loop items show an `Item {n}` badge for each iteration. When a step succeeded, expand **Output** to see what it created or returned — for example the task or invoice ID. If no steps ran, the page shows **No steps were executed.** That usually means the workflow has no steps after the trigger. ## Troubleshoot a failed run When a run is **Failed**, open it and find the first step with status `failed`. The step shows an error explaining why. Typical causes: * A required field was empty, or a [variable](/business-automation/workflows/variables) did not resolve — for example `{{ trigger.object.customer }}` when the trigger record has no customer. * A broken reference, shown as a chip in the builder after you removed an earlier step. * A **For each** array longer than 50 items. * A **Send letter** step where the recipient is missing a name or address, or your account is missing a return address. * An action for a product that is no longer enabled, such as Letters or Maintenance. To fix it, follow these steps: 1. Open the workflow and click **Edit workflow**. 2. Correct the step — fill in the missing field, repair the variable, or add an [If / else](/business-automation/workflows/conditions-and-loops) so the action only runs when the data is present. 3. Click **Publish**. The failed run is not replayed. The workflow will use your changes the next time the trigger fires. # Triggers Source: https://docs.yorlet.com/business-automation/workflows/triggers Choose what starts a workflow — a database event, an API request, an invoice past due, or a tenancy milestone. The trigger is the first node on the canvas. Select it, then choose a **Trigger type**. Only **Active** workflows run when the trigger fires. ## Trigger types | Trigger type | When it runs | | --------------------- | ------------------------------------------------------------------------------------------------- | | **Database event** | Whenever the event you choose occurs — for example a tenancy is activated or an invoice is paid. | | **API request** | When your systems call the workflow through the API. | | **Invoice past due** | Once, on the morning an open invoice reaches the number of days you set past its due date. | | **Tenancy milestone** | Once, on the morning an active tenancy reaches the number of months you set after its start date. | ## Database event Use **Database event** when something happening in Yorlet should start the workflow. To configure it, follow these steps: 1. Set **Trigger type** to **Database event**. 2. Choose an **Event** from the list. Events are grouped by record type, such as invoice, tenancy, application, and maintenance. The workflow runs whenever that event occurs. Common examples: * `tenancy.activated` — a tenancy becomes active * `invoice.paid` — an invoice is paid * `application.accepted` — an application is accepted * `maintenance.issue.created` — a maintenance issue is raised * `contract.completed` — a contract is signed The record that caused the event is available to later steps as the trigger object. Use **Insert variable** to add fields such as the record ID or a related customer. See [Variables](/business-automation/workflows/variables). Use an [If / else](/business-automation/workflows/conditions-and-loops) step after the trigger if you only want the workflow to continue for some records — for example, only invoices above a certain amount. ## API request Use **API request** when you want to start the workflow from your own systems, rather than from something happening in Yorlet. There is no **Run** or **Test** button in the Dashboard. A teammate with an [API key](/development/api-keys) triggers the workflow by sending a request to it. You can add **Input parameters** so the request can pass values in. Click **Add** for each parameter, then set: * A **key** — the name you will send, and the name you reference later as `{{ trigger.input. }}` * A type — **String**, **Number**, or **Boolean** * **Required** — turn this on if the request must include the parameter Developers trigger the workflow with `POST /v1/workflows/:id/trigger` and an optional `input` object keyed by the parameter names you defined. ## Invoice past due Use **Invoice past due** to run a workflow once an open invoice has gone unpaid for a set number of days. Set **Days past due** to a value from 1 to 30. The workflow runs once when an open invoice is that many days past its due date. Yorlet checks each morning and only includes invoices that are still open and unpaid. It skips invoices that are already being collected, invoices created as a late fee, and invoices that have been sent to [Recover](/billing/arrears). A typical use is a **Create task** or **Send letter** step when rent is 7 days overdue. Combine it with an [If / else](/business-automation/workflows/conditions-and-loops) step if you only want to act on certain customers or amounts. The invoice is available to later steps as the trigger object, so you can insert the customer, amount, or invoice ID. ## Tenancy milestone Use **Tenancy milestone** to run a workflow once an active tenancy reaches a set number of months after its start date — for example a two-month check-in or a twelve-month renewal reminder. Set **Months after tenancy start** to a value from 1 to 120. The workflow runs once when an active tenancy reaches that many months after it started. Yorlet checks each morning and only includes tenancies that are still active. The tenancy is available to later steps as the trigger object, so you can insert the tenants, unit, or start date. # Variables Source: https://docs.yorlet.com/business-automation/workflows/variables Insert values from the trigger, earlier steps, and the time the workflow ran. Variables let a step use data from the trigger, from a previous step, or from the time the workflow ran. They are written as `{{ }}` expressions — for example `{{ trigger.object.id }}`. You do not need to type them by hand. Click **Insert variable** in a field, or type `{{` to open the picker. ## Insert a variable To insert a variable, follow these steps: 1. Select a step and click the field you want to fill. 2. Click **Insert variable**, or type `{{`. 3. Search if you need to, then choose a variable. The picker groups variables so you can find them quickly: * **Time** — the time the workflow ran (`Run time (now)`), plus offsets such as one day later. * **Trigger** — the event or input that started the workflow. * **Trigger · ** — fields on the record that caused the trigger, such as an invoice or tenancy. * **Loop** — **Current item**, **Current item ID**, and **Current index**, when the step is inside a **For each**. * **Step · ** — fields returned by an earlier action, such as the title of a task you just created. A chip in the field shows the variable. Hover it to see the full `{{ }}` path. If a step you referenced has been removed, the chip is marked as a broken reference. Only earlier steps on the same path appear. A step on the **No** branch of an **If / else** cannot use the output of a step on the **Yes** branch. ## Time and due dates Timestamp fields such as a task **Due date** have three modes: * **When the action runs** — stores `{{ now }}`. * **After the action runs** — stores an offset such as `{{ now + 1d }}`. Choose **Minutes**, **Hours**, **Days**, or **Weeks**. * **Custom value or expression** — enter your own value or insert a variable. Offsets use `m` (minutes), `h` (hours), `d` (days), and `w` (weeks). `{{ now + 1d }}` is one day after the run. ## Format numbers and dates Some values are stored in a raw form that is not what you want to print. * Invoice amounts are in pence. Insert the field, then choose **Currency** from **Format** so `10000` becomes £100.00. You can also type `| currency` after the path, for example `{{ trigger.object.total | currency }}`. * Dates are stored as a Unix timestamp. Choose **Date** from **Format**, or type `| date`, so the value becomes a readable date such as 25 August 2026. ## What you can reference What the trigger provides depends on how the workflow started: * **Database event** — the event name and the record, plus any previous attributes when the record was updated. * **API request** — the input parameters you defined, as `{{ trigger.input. }}`. * **Invoice past due** — the invoice, and how many days past due you configured. * **Tenancy milestone** — the tenancy, and how many months after the start you configured. After an action succeeds, later steps can use its output — for example the ID of a task or invoice the workflow just created, or the thread a **Send email** step wrote to. # Product updates Source: https://docs.yorlet.com/changelog/overview Keep track of new features and improvements in Yorlet. This changelog lists product updates as they ship in the Dashboard. Use it to see what changed, when it became available, and where to find it in Yorlet. ## Reports in the assistant You can now ask the [assistant](/business-automation/ai/assistant) questions about [reports](https://dashboard.yorlet.com/reports) — rent roll, occupancy, arrears totals, payment volume, owner payouts, and more. It runs the report and shows a table next to its answer, with a link to open the same report in the Dashboard. [Claude and ChatGPT](/business-automation/ai/mcp) can run the same reports. * Ask for the rent roll, vacant units, last month’s collected rent, or pending owner payouts * Narrow by building or period when you need a slice * Click **Open in Reports** on the card to see the full report ## Assistant [Home](https://dashboard.yorlet.com/dashboard) is now a full-page [assistant](/business-automation/ai/assistant) chat. The previous dashboard view is at [Overview](https://dashboard.yorlet.com/dashboard/overview). Every team member starts on [Free](/business-automation/ai/plans), with 30 messages a month. Mix Standard and Premium seats for more messages, Recover triage, and the email agent. * Open a full-page chat from **Home**, or the side panel with **⌘ /** when you are on a record * Switch earlier conversations from **History**, or click **New chat** * Ask who is in arrears, which applications are stuck, who is viewing today, or what’s going on with a tenant or unit * Propose a note, task, email, Recover enrolment, application progress, viewing update, or repair — under [agent policy](/business-automation/ai/policy) * Request a higher plan from [Yorlet AI](https://dashboard.yorlet.com/settings/plans/ai); an admin approves before billing starts ## MCP [Claude and ChatGPT](/business-automation/ai/mcp) can now look people and properties up, then pull the queues you would open in the morning — [arrears](/billing/arrears), stuck [applications](/leasing/applications/manage-an-application), upcoming [viewings](/leads/viewings), and open [repairs](/maintenance/manage-issues). They can also run [reports](/reporting/dashboard-reports). Lookups run immediately. Writes still follow [agent policy](/business-automation/ai/policy) and wait in [Approvals](/business-automation/ai/approvals) when they need a person. * Search by name, email, address, or keyword, then open a customer or unit briefing * Named work queues for arrears, stuck applications, upcoming viewings, open repairs, and open tasks * Ask for a rent roll, occupancy, arrears totals, or other portfolio report * Propose a task, progress an application, update a viewing, or raise and triage a repair — alongside notes, email, and Recover * Start from **Morning briefing**, **Chase arrears**, or **Unblock waitpoint applications** ## Send email in workflows [Workflows](/business-automation/workflows/overview) can now send an email as a step, so you can email a customer, owner, or address when a trigger fires — for example a rent reminder when an invoice is past due. The send is stored as an outbound message in [Inbox](/business-automation/inbox/overview). See [Send email](/business-automation/workflows/actions#send-email). * Send to a customer, owner, or email address, with [variables](/business-automation/workflows/variables) in the subject and body * Choose **Branded** to wrap the message in your [account branding](/account/branding), or **Plain text** for a thread reply * Optionally send from a specific provisioned address, or reply on an existing Inbox thread * Adding a step now opens **Add a step**: search by name, or browse **Logic**, **Core**, **Billing**, **Letters**, **Loyalty**, and **Maintenance** ## Recover **Recover** escalates invoices that are more than 28 days overdue. From [Arrears](/billing/arrears), send a customer's aged invoices into a recovery case. They receive a firmer email sequence and a hosted page where they can pay in full or set up an instalment plan that collects itself. You only pay a success fee on what is recovered — nothing up front, and nothing if nothing is collected. * Enable Recover from [Your plans](https://dashboard.yorlet.com/settings/plans) * Send qualifying arrears to recovery in one click * Self-serve instalment plans of 2, 3, 6 or 12 months * A recovery case list and detail view under **Billing**, with charts for recovered revenue and outstanding balances ## Maintenance **Maintenance** is now available in the Dashboard, so you can manage repairs from the first report through to resolution. Tenants report issues with photos and, if they'd like to be there for the visit, pick from the times your team is available. Please contact your account manager to enable this feature. * A board, table, and split view for issues, with your preferred view remembered * Status tabs, filters, and assignees so you can see who is handling what * Weekly availability in **Settings**, so tenants only choose visit times your maintenance team can attend ## Notifications Added a notification centre to the Dashboard, so the things that need your attention come to you. You'll be notified when a payment is disputed, a customer cancels their direct debit mandate, an owner fails an identity check, an integration is paused, a rolling tenancy needs reviewing, or a webhook endpoint starts failing. Every notification links straight to the record. ## Webhook monitoring Webhooks now come with delivery reporting so you can see how your endpoints are performing. Each endpoint shows success and failure rates, response times, and a history of every attempt with its request and response body, and you can resend an attempt that didn't get through. Endpoints that fail repeatedly are disabled automatically, and we'll notify you when that happens. ## Help and support You can now reach our support team without leaving the Dashboard. Open **Help**, choose **Get in touch**, and ask a question, report a bug, or share feedback, along with the topic and the record you're looking at. ### Improvements & fixes * Added a **Rent roll** report covering every active, pending, and completed tenancy with its unit, tenants, rent, and lease dates * Added a **Remaining balances** view for payment methods with a balance that hasn't been charged yet * Added disputes to payment records, so you can see when a payment is being disputed * Added the ability to stop a scheduled cancellation on a subscription or tenancy, with a clearer cancellation flow and credit note options * Added the ability to edit the description on a transaction * Added owner balances by unit, along with unit filtering on transactions and warnings when payout grouping needs to be per unit * Added document uploads to owners, and an invoice document when creating a collection * Added tabs to the units table for available, under offer, occupied, maintenance, offline, and unmanaged units * Added the option to reserve move-in credits for a specific application * Added an assignee to more records, including deposits, disputes, invoices, owners, renewals, and units * Added the option to charge the rent review fee when notice is served, and tracking for when Form 4 is emailed to the tenant * Rent reviews are now withdrawn automatically when a tenancy ends * Added a draft PDF preview so you can see a contract before it's signed * Added the ability to resend compliance documents from a tenancy * Added billing periods to invoice imports, with dates respecting your account's timezone * Introduced API version `2026-07-20`, which adds a liability field to disputes ## Compliance A new **Compliance** product helps you stay on top of regulatory changes that affect your portfolio. Subscribe to the councils and topics that matter to you, and we'll surface relevant updates as tasks and deadlines. * A compliance **Inbox** for reviewing incoming regulatory changes, with **Deadlines**, **Tasks**, and an **Archive** for items you've actioned * Configurable alerts by priority (critical, important, and watchlist), delivered immediately or as a weekly digest ## Workflows Introduced **Workflows**, a new automation product for building your own custom processes in Yorlet. Create a workflow from a trigger, then add steps using a visual flow editor, with support for conditional expressions between steps. You can track every run from the workflow's history. ## Disputes Added a dedicated **Disputes** page to the Dashboard for managing payment disputes, including an evidence sheet and a timeline of dispute activity. ### Improvements & fixes * Added owner statements, balance adjustments, and an arrears view to the Owners workspace * Added balances to the customer record, along with new customer balance management actions * Added CSV import for customers, invoices, and units, with support for larger file-backed bulk actions * Added signing secrets and an improved management UI for webhooks * Added the ability to change unit ownership directly from a unit's ownership record * Moved tax filing processing to the background and expanded the owner details included in tax forms * Added the ability to revert an application to a previous step * Added the ability to void a contract for reporting purposes * Added an owner table to tenancies for a clearer view of ownership ## Yorlet AI assistant Meet your new AI assistant, built right into the Dashboard. Ask questions about your customers, invoices, and payments in plain English and get instant answers, without digging through reports. You can enable and configure the assistant from your **Yorlet AI** settings. ## Owners workspace We've rebuilt how you manage owners and their money end to end. You can now onboard owners, track account balances and reserves, run collections, and pay owners out, all from one place. * Owner onboarding and account management * Owner payouts, with mark as paid and mark as failed actions * Owner reserves, collections, and balance tracking * Tax forms and tax filings for owners ## Deposits Creating and protecting deposits is now far simpler. Deposits can be registered automatically with your chosen protection scheme, and you can raise and manage deposit charges directly from the Dashboard. * Automatic deposit registration with supported schemes * Deposit charges and dispute handling * Edit deposits with a redesigned deposit sheet ### Improvements & fixes * Added Tax IDs to customers for accurate tax handling * Added Documents and Notes to more records * Introduced unit groups for organising your portfolio * Added the ability to schedule a subscription to cancel on a future date * Added flexibility around serving notice, including the option to serve notice before the recommended date * Added new revenue and recovery charts to the Dashboard * Added webhook endpoints for developers building on Yorlet * Improved reliability with better error handling across the Dashboard ## Guarantor management Managing guarantors is now built into the application flow. You can add, remove, and manually enter guarantors, including company guarantors, and choose to skip guarantor details where they aren't needed. ## Credit grants You can now create and update credit grants from the Dashboard, making it easier to apply credit to a customer's account. ### Improvements & fixes * Added Metadata and Events to customer and subscription pages * Added the ability to exclude specific payment methods on an invoice * Made the Dashboard editable so you can arrange it to suit your workflow, with your layout saved between visits * Improved rent review and rent increase handling, including Section 13 and Form 4 support * Added payment timings information for Bacs Direct Debit * Strengthened sign-in security with additional verification checks * Added a refunds view for tracking refunded payments ## Income verification and affordability checks We've added income verification and affordability checks to the application process, so you can confirm an applicant can afford the rent before they move in. Please contact your account manager to enable this feature. ## Microsoft single sign-on You can now sign in to Yorlet using your Microsoft account, alongside existing sign-in options. ### Improvements & fixes * Added an account activity log so you can audit changes across your account * Added disputes and refunds management for payments * Redesigned the renewals experience, including a tenancy review step * Added the ability to invite a team member to multiple accounts at once * Added a Dashboard-wide search to help you find records faster * Added coupons to exports ## Application configurations and pre-qualification You can now build reusable application configurations with their own steps and pre-qualification questions, helping you screen applicants earlier and create applications more consistently. ## Advance Rent and Right to Rent We've integrated Advance Rent referencing and Right to Rent document checks into the application flow for a smoother, more compliant onboarding. ### Improvements & fixes * Added mentions and a redesigned notes experience for better collaboration * Added filters by unit and building on the renewal intents page * Added pre-qualification information to applications and tenancies * Added sorting on created and due date columns * Improved how dates are handled to respect each account's timezone * Introduced dated API versions for developers ## Lead management We've introduced lead management to help you capture and qualify enquiries before they become applications. New enquiries are scored automatically, and you can set up qualification rules to prioritise the best leads. * Automatic, AI-powered lead scoring * Qualification configurations to rank and route enquiries * A dedicated enquiries view with details and a split-screen layout ## Billing workspace We've started rolling out a redesigned billing experience, making it easier to manage subscriptions, invoices, and pricing in one place. * Create and manage subscriptions and invoice items * Coupon management * Credit notes ### Improvements & fixes * Added loyalty tiers, with priority and redemption limits for loyalty programs * Added support for restricted API keys for read-only access * Added references management to the Dashboard * Added a rent collected chart to track income at a glance * Added the ability to save your table and view preferences ## Two-factor authentication and passkeys You can now secure your account with two-factor authentication and passkeys. Manage your sign-in security, register passkeys with custom names, and turn two-factor authentication on or off from your profile settings. ## Invoice editing You can now edit invoices before they're finalised, with a clearer editing screen and a finalisation step that shows exactly what your customer will receive. ## Global owner payouts Owner payouts now support currency conversion, so you can collect and pay out across currencies for owners based overseas. ### Improvements & fixes * Redesigned buildings and units management in the Dashboard * Added marketing locations and offers for in-person payments * Added loyalty points redemption * Added API logs and webhook activity to the Dashboard for developers * Added a compliance certificate column to sent emails ## In-person payments and hardware support Enhanced payment processing capabilities with terminal payment support, enabling in-person payment collection and expanding payment method options. * Terminal hardware support * In-person payment processing ## Application workflow improvements Improved the application process with better pre-qualification visibility and expanded renewal tracking options. * Pre-qualification information display on applicant screen * Expanded renewal decision reasons and tracking ## Improvements & fixes * Migrated maintenance system to new service architecture * Investigated and resolved deposit transfer issues ## Reporting enhancements Enhanced reporting capabilities with new export options and improved data tracking for financial operations. * Off-platform invoices and part payment report * Balance adjustments line-by-line report * Invoice prefix support for payout reconciliation reports * Invoice prefix support for customer balance reports ### Improvements & fixes * Fixed urgent checkout session release date issue * Added verification session table for improved compliance tracking ### Improvements & fixes * Enabled bank transfer reconciliation for incomplete transactions * Fixed acceptance text line breaks display bug * Fixed notes attribution bug * Added option to skip verification stage for applicants ## Right to Rent compliance Enhanced visa verification capabilities with support for ETA (Electronic Travel Authorization) visas, expanding compliance coverage for international tenants. ### Improvements & fixes * Implemented customer address auto-update on application completion * Enhanced customer balance reporting across organizations * Fixed invoice charging behavior on renewals * Added failed credit note notifications ## Organisations We've added the ability to create and manage organisations in Yorlet. This allows you to group accounts together into a single entity. ## Organisation sharing for exports Exports can now be shared across organisations, making it easier to collaborate and share financial data between different teams and entities. ### Improvements & fixes * Added tax rate support to invoice line items * Fixed invoice item transfer calculation rounding issues * Added memo field to credit note PDFs * Updated contract display to show partial upfront amounts ex VAT * Added owner payout column to exports * Fixed organisation exports functionality * Improved database export performance and reliability * Expanded application templates with customer balance credit toggle * Fixed billing anchor bug on lease revisions * Fixed navigation from customer records * Fixed OTP authentication bug on tenant portal ## New export for credit notes You can now export credit notes data for better financial tracking and reporting capabilities. ## Counter-signature functionality Enhanced contract signing process with improved counter-signature capabilities for more streamlined agreement workflows. ### Improvements & fixes * References status updates now properly handle tenancy cancellations for better application workflow management. * Billing anchor now remains unchanged unless manually modified, providing more predictable billing cycles. * Added tax rate configuration on individual rent items for more granular tax management. * Setting to disable 'special requests' feature in the application portal for simplified application processes. * Preview functionality when creating applications for better visibility before finalisation. * Total contract value now displayed on tenancy pages for improved financial transparency. * Arrays in CSV exports are now converted to flat columns for better data analysis and integration. ## Application portal redesign We've redesigned the application portal to make it easier to use and more intuitive for applicants. ## Identity verification and Right to Rent checks We've added a new identity verification and Right to Rent check process to the application portal. This ensures that all applicants are who they say they are and have the right to rent in the UK. Please contact your account manager to enable this feature. ## Invoice transfer improvements We've added new statuses to invoices to help to track the status of invoices that have been transferred to owners. ### Improvements & fixes * Fixed an issue relating to editing notes. ## Recurring collections for owners You can now set up recurring collections for owners. This allows you to automatically collect expenses, fees, service charges, and more from owners on a regular basis. ## Set default tax rate and transfer destination on Prices You can now set the default tax rate and transfer destination on prices. This makes it easier to manage your prices and ensures that the correct tax rate is applied to invoices. ### Improvements & fixes * Added a new Deal Assignee field to applications to help differentiate between the deal owner and the application owner. * Fixed an issue with search in the Dashboard. * Added Ground Rent as an expense type. * Fixed an issue with the owner reserve balance report. * Fixed an issue that meant numbered lists were not correctly rendered on a contract PDF. * Added document reference to all pages of a contract PDF. * Fixed a bug that meant notes could not be edited. ## Application templates Added ability to save application templates with custom options for different contract agreements. These allow you to save time when creating new applications with predefined values. For example, you could implement specific template settings for students (manual invoicing) and non-students (automatic charges). ### Improvements & fixes * Improved handling of rolling tenancies during renewals, including rent review tracking and rent increase management. * Fixed issue with deposits not showing registration details. * Resolved an issue future dated lease changes. * Added payment method transactions export feature. ## Enhanced CRM and validation features * We've integrated with more CRM providers, enabling better data synchronisation and management. * Phone number validation is now more accurate, reducing errors during data entry. ### Improvements & fixes * You can now set an application status to "Pending Contract Generation". This helps streamline application management and improves visibility into progress. * Performance and reliability improvements across multiple areas. * Updated systems to ensure seamless functionality and a better user experience. ## "Lets Agreed" report A new report type, "lets agreed", is now available in the reporting service. This report can be generated and viewed seamlessly through the updated interface. ## Improved payment method support We've added new payment methods for greater flexibility and improved reliability and performance in handling payments, ensuring a smoother experience. ## Application status updates You can now set an application status to Pending Contract Generation. This helps streamline application management and improves visibility into progress. ### Improvements & fixes * Performance and reliability improvements across multiple areas. * Updated systems to ensure seamless functionality and a better user experience. * These updates bring enhanced flexibility, improved reliability, and powerful new features to support your workflows. ## Enhanced notes and logging system We've improved the notes system with better components and optimised queries, while adding humanised timestamps to logs for better readability. ## Dynamic table system A new dynamic table system has been introduced, allowing you to toggle columns, sort them in any order, and pin columns to the left or right for better customisation. ## Owner communication improvements Owners now receive detailed termination notification emails, including termination dates, reasons, and descriptions. ## Financial reporting enhancements * Added customer availability in human-readable format to export files * Rent roll reports now display move-in and move-out dates * Introduced a new owner reserve balances report * Added hover effects on invoice tables to show credit note applications ### Improvements & fixes * Enhanced error message display for better troubleshooting * Improved self-managed expansion panels for past-due invoice emails * Added tenancy filtering by start date * Enhanced sorting functionality with conditional options * Upgraded table schemas with robust sorting capabilities * General improvements to user interfaces and data handling * Enhanced flexibility and readability in reports, logs, and tables ## Change of tenant process Through the lease changes section of the dashboard, you can now add or remove applicants from an ongoing tenancy. This will create new subscriptions for the new applicants and cancel the old ones. ### Improvements & fixes * Owner payout reserves can now be created directly on an owner payout. * Renewals now use the source application pricing, not default pricing. * When creating an application from a renewal intent, the system will default to using the pricing details of the source application instead of the unit default pricing. * Settings for controlling multiple subscriptions per customer. * A new report shows how many owners are in negative balance. * VAT invoice for account collections. * Setting on an owner payouts settings to stop all payout receipt emails. * When marking payouts as paid, there is now a toggle to specify whether you want to send payout receipts to the owner. ## New reports for client accounting We've added some new reports to Client Accounting, including customer credit balances and owner cash balances. You can use these tools to understand the cash position in your client's bank account. ## Automatic deposit registration When creating a new application, once you have indicated that you would like a deposit record created, you can specify whether you want the deposit to be registered automatically. You will be prompted to select from deposit protection schemes that you have set up with the appropriate data in the settings area of Yorlet. ## Let-only application improvements Let-only applications will now create an invoice for move-in payments by default. ## Joint owner payout receipts On owner payout PDF documents, in the case of joint ownership of a property, we will be displaying the names of all the owners. ## Applicant audit system On the application page, we will now be displaying a log of certain applicant actions for auditing purposes. For example, if a tenant opens the provided EPC document on the application portal link they receive from an agent, it will show up on the application page for the agent to see. ## Renewal KPIs We have added two new reports on the dashboard, one for viewing the time taken to complete a renewal and another report for recording the amount of late renewals in a specific period. ### Improvements & fixes * You can now see the deposit records for a property on an individual unit * Added a new report showing average rent collected in a specific period * Optionally hide arrears on statements when downloading an owner statement * Added flexibility when creating subscriptions with active tenancies - you can now toggle to use the future billing date ## Yorlet Customer Portal We've begun rolling out access to a new customer portal that your active tenants can sign into and view their tenancy information, upcoming rental payments, past invoices, and compliance documentation. Please reach out if you're interested in getting early access. ### Improvements & fixes * Improved calendar selectors so you can easily select dates far in the past * Set account collections to become available on a future date * Added ability to add and remove photos from maintenance issues * Added setting to block on applications with no fees set * Changed the Maintenance Types API to Maintenance Categories API ## Metadata improvements We heard from feedback that users wanted more customised data in certain exports so we revamped Metadata on all data models in Yorlet. You can now select previously used fields and we include metadata on more exports. ### Improvements & fixes * Added new dashboard reports for move-ins and new lets * Added support for editing permitted occupiers * Landlord and supplier payment runs can now be separated * Added ability to download compliance docs * Added a setting for making account collection destination mandatory * Added export restrictions for non-admins * Added ability to archive and unarchive owners and units ## New year bug fixes We spent the first month of 2024 working on some improvements and fixes that had been high on customers' wish lists. ### Improvements & fixes * Added ability to add unique invoices and purchase order numbers for collections * Added destination display on the deposit charges table * Added default platform fee option for suppliers * Added ability to filter deposits by assigned user * Added ability to update advance rent once an application was sent out ## Yorlet Maintenance Beta We've started work on Yorlet Maintenance, a new product that will allow customers to report and manage maintenance in the Yorlet platform. ### Improvements & fixes * Added unit name display for collections on owner statements * Added unit ID requirement for owner releases * Removed warning for Bank Transfers when customers attempt payments after payee approval * Added ability to set up deposit providers as suppliers * Added ability to create unique invoice numbers and purchase order numbers for collections * Added ability to assign users to units ## New reconciliation tools Part payments have been streamlined with new reconciliation tools to help you manage under and over-payments. ### Improvements & fixes * Added arrears display on owner records for their units * Added 'paid at' date display on the payments table * Added Bacs debit processing timings display on payment records * Improved customer record management * Enhanced contract service functionality * Added automatic deposit charge initiation for sending money to landlord owner records * Improved deposit movement process for sending funds to suppliers * Added setting for sending arrears emails to landlord owners * Added ability to download NRL tax-paid certificates from owner payouts ## Negative payouts to owners Negative payouts enable customers to collect negative balances from owners. ### Improvements & fixes * Added ability to set default days before due for invoices * Added tenant statements feature * Added user email preferences for holding deposit payments * Added automatic contract sending to landlord after signing * Added configurable application stages * Improved owner payout statement descriptors * Made owner fees mandatory for application creation * Added fee change email notifications * Added Alan Boswell email integration ## Duplicate invoices Customers can now duplicate invoices in the Dashboard or through the API. ### Improvements & fixes * Added new web pay service * Added ability to change billing anchors and reset billing cycles * Added new application settings * Added ability to cherry-pick items for owner payouts ## Owner fee reductions You can now add temporary fee discounts to units to offer incentives to owners on management fees, as well as customising tenant find and renewal fees when creating a new application. ### Improvements & fixes * Added future-dated invoice items * Added paid at filter on payments * Added allocate part payment screen * Added ability to mark an owner payout as paid without sending a statement * Added ability to reveal external account details * Added pending invoice items to upcoming invoices * Added ability for a landlord to countersign a contract # Customers Source: https://docs.yorlet.com/customers Learn how to create and use customers in Yorlet. The Customer record is a fundamental resource in Yorlet. You can use it to store profile, legal, and billing information. These records are essential for creating Applications, Subscriptions, Invoices, Payments, and other related resources. ## Manage customers Create a customer for every new user that you want to use within Yorlet, at a minimum we recommend supplying an email address so we can send application links and billing information. You can create and manage customers from the [Customers page](https://dashboard.yorlet.com/customers). ### Create a customer To create a customer, follow these steps: 1. Click **Add customer** in the top right of the [Customers page](https://dashboard.yorlet.com/customers). 2. Enter your customer’s **Email** and any other information you have to hand. 3. Click **Create**. ### Edit a customer To edit a customer, follow these steps: 1. Navigate to the customer record you want to modify. 2. Use the **Actions** menu and select **Edit information**. 3. Make the changes you want. 4. Click **Update**. ### Delete a customer To delete a customer, follow these steps: 1. Navigate to the customer record you want to delete. 2. Use the **Actions** menu and select **Delete account**. 3. Confirm you want to delete the record by clicking **Delete**. This will permanently remove the customer and immediately cancel any current applications, tenancies and subscriptions. Past payments or invoices associated with the customer will still remain. This action cannot be undone. ## Customer records The Customer record has many useful properties for storing customer data and providing an overview of the customer’s interactions with your business. Each record also allows you to see other resources associated with this customer: ### Applications section This section shows the associated Application records for which the customer is an applicant. You can also create a new application for the customer by clicking on **New**. ### Tenancies section This section shows the associated Tenancy records for which the customer is a resident. ### Balance section This section shows the current and historical balance of the customer. When you accept holding deposits or advance rent payments during an application, they will show up here as credits. Any credits and debits on the balance can be applied to future invoices. You can make adjustments to the balance by clicking on **Adjust balance**. By default, a credit is applied to the customer's next eligible invoice and a debit increases the amount due on it. You can instead reserve a credit or debit for a specific Application so it can only be applied to invoices for that application. To do this when creating an adjustment, use the **Reserve for application** field on the adjustment form; leave it empty to apply the balance to the customer's next invoice. #### Lock a balance to an application You can also reserve an existing balance entry for an application after it has been created. To lock a balance to an application, follow these steps: 1. In the **Balance** section, find the balance entry you want to reserve. 2. Use the and select **Lock to application** (or **Edit application** if it is already reserved). 3. In the **Reserve balance for an application** dialog, choose the **Application** to reserve the balance for. 4. Click **Save**. Reserved entries are marked with a lock icon in the **Reserved** column. That amount can then only be used on an invoice for the same application. To unlock a reserved entry, use the and select **Remove application**. The balance then behaves as an unscoped credit or debit that applies to the customer's next eligible invoice. Balance entries that were generated by the system, such as amounts already applied to or removed from an invoice, cannot be reserved or edited this way. ### Payment methods section This section shows the associated payment methods for the customer. You can collect new payment methods from the customer by clicking **Collect payment method**. Learn more about [Payment Methods](/payments/payment-methods). ### Subscriptions section This section shows the associated Subscription records for the customer. You can create a new subscription for the customer by clicking **New**. Learn more about [Subscriptions](/billing/subscriptions). ### Invoices section This section shows the associated Invoice records for the customer. You can create a new invoice for the customer by clicking **New**. Learn more about [Invoices](/billing/invoices). ### Pending invoice items section This section shows the current pending invoice items for the customer. Pending invoice items will be added to the next invoice created for this customer and are useful for storing ad hoc charges. You can create a pending invoice item by clicking on **New**. ### Payments section This section shows the associated Payment records for the customer. You can create a new payment or payment session for the customer by clicking on the overflow menu (•••) and selecting either option. Learn more about [Payments](/payments) and [Payment Sessions](/payments/payment-sessions). ### References section This section shows the associated Reference records for the customer. You can create a new reference for the customer by clicking **New**. ### Guarantors section This section shows the associated Guarantor records for the customer. You can create a new guarantor for the customer by clicking **New**. ### Viewings section This section shows the associated Viewing records for the customer. You can create a new viewing for the customer by clicking **New**. ### Documents section This section shows the associated Document records for the customer. You can create a new document for the customer by clicking **New**. # Remaining balances Source: https://docs.yorlet.com/customers/remaining-balances Charge unapplied funds on a customer's bank transfer payment method. A **remaining balance** is money that arrived on a customer's [bank transfer](/payments/payment-methods/bank-transfers) payment method but wasn't fully applied to an invoice. This happens when [automatic reconciliation](/billing/invoices/automatic-reconciliation) can't match an incoming transfer to an outstanding invoice — for example when the amount doesn't cover the invoice in full, or when there is no invoice open at the time. You can review every payment method with unapplied funds on the [Remaining balances page](https://dashboard.yorlet.com/customers/balances). Remaining balances only exist on bank transfer payment methods. Card and direct debit payment methods don't hold funds ahead of a charge, so there is nothing to reconcile. ## Charge a remaining balance Make sure you have the customer's permission to charge their payment method. There are three entry points to the **Create payment** sheet — pick the one closest to what you're doing: ### From the Remaining balances page 1. Open the [Remaining balances page](https://dashboard.yorlet.com/customers/balances). 2. Right-click the row for the payment method you want to charge and select **Charge balance**. 3. Review the **Amount**, **Currency** and **Description** — the amount is prefilled to the full remaining balance. 4. Click **Create payment**. ### From the payment method 1. Navigate to the customer, then open the bank transfer payment method that holds the remaining balance. 2. Click **Charge balance** in the header. 3. Review the **Amount**, **Currency** and **Description**. 4. Click **Create payment**. ### From the customer record 1. Navigate to the customer. 2. Open the **Actions** menu and select **Create payment**. 3. Enter the **Amount**, **Currency** and **Description** and select the bank transfer payment method with the remaining balance. 4. Click **Create payment**. ### Advanced options By default, a payment created from a remaining balance settles against the customer's outstanding invoices via [automatic reconciliation](/billing/invoices/automatic-reconciliation). If you'd rather credit the funds to the customer's balance so they can be used against a future invoice, toggle **Apply to customer balance** in the **Create payment** sheet. Choose whether to send the customer an email receipt after the payment succeeds. # API changelog Source: https://docs.yorlet.com/development/api-changelog A list of the changes introduced in each Yorlet API version. Each entry lists the changes introduced in that API version. See [API versioning](/development/versioning) for how to upgrade and roll back. Versions are listed newest first. * **Added `viewing_booking_url` field** — The `viewing_booking_url` field has been added to the building object. It is the public URL a lead can use to book a viewing at the building, once a booking link has been minted. ([`building`](/api/core/buildings/object)) * **Added `viewings_availability` field** — The `viewings_availability` field has been added to the building object. It holds optional weekly viewing hours for the building. `null` inherits the account viewing calendar. ([`building`](/api/core/buildings/object)) * **Added `viewings_require_confirmation` field** — The `viewings_require_confirmation` field has been added to the building object. It overrides whether public building booking links need a team member to confirm them. `null` inherits the account setting. ([`building`](/api/core/buildings/object)) * **Added `pending` viewing status** — The `status` field on the viewing object now includes `pending`, used when a public building booking link is waiting for a team member to confirm it. ([`leads.viewing`](/api/leads/leads-viewings/object)) * **Added `building` field** — The `building` field has been added to the enquiry object. It is set when the enquiry is created from a building viewing booking link. ([`leads.enquiry`](/api/leads/leads-enquiries/object)) * **Added `building` field** — The `building` field has been added to the viewing object. It is the building the viewing is booked against, used for per-building availability and collisions. ([`leads.viewing`](/api/leads/leads-viewings/object)) * **Added `automatic_deposit` and `requires_external_transfer`** — The `automatic_deposit` and `requires_external_transfer` fields have been added to the deposit object. `automatic_deposit` reports whether automatic scheme registration is enabled, the latest provider status, and the last registration error. `requires_external_transfer` is true when a GB custodial deposit still needs to be transferred to a scheme. ([`deposit`](/api/leasing/deposits/object)) * **Added `actor` field** — The `actor` field has been added to the message object, identifying the user, agent, or API key that sent an outbound message. `null` for inbound messages and for messages recorded before actor attribution existed. ([`message`](/api/core/emails/object)) * **Added `unread` field** — The `unread` field has been added to the thread object. It is `true` when the authenticated user has inbound messages they have not seen. Always `false` for API key requests. ([`thread`](/api/core/threads/object)) * **Added `actor` field** — The `actor` field has been added to the timeline entry object, identifying the user, agent, or API key that performed the activity. `null` for entries recorded before actor attribution existed. ([`timeline_entry`](/api/core/threads/object)) * **Added `request.actor` field** — The `request.actor` field has been added to the event object, identifying the user, agent, or API key that caused the event. ([`event`](/api/events)) * **Added `late_fee` billing reason** — The `billing_reason` field on the invoice object now includes `late_fee`, used when an invoice is created to charge a late payment fee. ([`invoice`](/api/billing/invoices/object)) * **Added `variables` field** — The `variables` field has been added to the letter template object, and matching `variables.\` paths are included in `merge_fields`. (`letter_template`) * **Added `variables` field** — The `variables` field has been added to the letter object for custom template values. (`letter`) * **Nested `expense` and `fee`** **(breaking)** — The `expense_code`, `fee_code`, and `fee_discount` fields have been replaced by nested `expense` and `fee` objects. `fee.discount` is `{ end, percent_off }` instead of a percentage number. `expense` and `fee` are omitted when they do not apply to the collection type. ([`account_collection`](/api/owners/account-collections/object)) * **Added `application` field** — The `application` field has been added to the enquiry object. It holds the ID of the application the enquiry was converted into, set when an application is created with `enquiry`. ([`leads.enquiry`](/api/leads/leads-enquiries/object)) * **Added `portal` field** — The `portal` field has been added to the enquiry object. It is present when `source` is `portal` and is polymorphic on `type`. The first supported type is `rightmove`, with portal-specific details under `rightmove`. ([`leads.enquiry`](/api/leads/leads-enquiries/object)) * **Added SLA and on-hold fields** — The `first_responded_at`, `on_hold`, and `sla` fields have been added to the maintenance issue object. `on_hold` is a nested object with `at` and `reason`, or `null` when the issue is not on hold. `sla` is a nested object with `paused_seconds`, `resolution_due_at`, `response_due_at`, and `status`. ([`maintenance.issue`](/api/maintenance/maintenance-issues/object)) * **Nested availability fields** **(breaking)** — The `availability_days`, `availability_every_day`, and `availability_time_slots` fields have been replaced by a nested `availability` object. `availability` is `null` when availability has not been set. ([`maintenance.issue`](/api/maintenance/maintenance-issues/object)) * **Nested triage fields** **(breaking)** — The `triage_enabled`, `triage_portal_completion_session`, and `triage_resolved` fields have been replaced by a nested `triage` object. `triage` is `null` when triage is not enabled. ([`maintenance.issue`](/api/maintenance/maintenance-issues/object)) * **Added `consumer_link` and `source` fields** — The `consumer_link` and `source` fields have been added to the resident object. `consumer_link` is one of `none`, `pending`, `linked`, or `rejected` and reports whether the OneMove user has confirmed they live at the building. `source` is `manual` or `tenancy`. ([`resident`](/api/loyalty/loyalty-residents/object)) * **Added `apply_url`** — The `apply_url` field has been added to the unit object. It contains the public URL an applicant can use to apply for the unit, and is only present while the unit is released to the market and self-serve applications are enabled on the account. ([`unit`](/api/core/units/object)) * **Added `availability` and `active_tenancy_end`** — The `availability` object has been added to the unit object, describing the letting state of the unit (`to_let`, `coming_available`, `held`, `under_offer`, and so on) alongside the release decision behind it. The end date of the occupying tenancy is also now exposed as `active_tenancy_end`. ([`unit`](/api/core/units/object)) * **Added `videos` field** — The `videos` field has been added to the maintenance issue object. ([`maintenance.issue`](/api/maintenance/maintenance-issues/object)) * **Added `liability` field** — The `liability` field has been added to the dispute object. ([`dispute`](/api/payments/disputes/object)) No changes to existing objects. No changes to existing objects. Initial version. # API keys Source: https://docs.yorlet.com/development/api-keys Learn how to create and manage API keys for your Yorlet account. API keys are used to authenticate your requests to the Yorlet API. To create an API key, you need to have a Yorlet account. ## Secret and publishable keys Yorlet uses three types of API keys: * **Secret key**: This key is used to authenticate your requests to the Yorlet API. Keep this key secure and never expose it in public. * **Publishable key**: This key is used to authenticate your requests to the Yorlet API. You can expose this key in public. * **Restricted key**: This key is used to authenticate your requests to the Yorlet API. You can limit the access to specific resources or actions. Secret keys have full access to your account and can perform any action on your behalf. Keep them secure and never expose them in public. If you suspect that a secret key has been compromised, roll the key immediately. ## Roll an API key To roll an API key: 1. Go to the [API keys](https://dashboard.yorlet.com/developers) page. 2. In the row for the key you want to roll, click the , then select Roll key…. 3. Confirm that you want to roll the key. 4. The window displays the new key value. Copy it by clicking it. 5. Save the key value. You can’t retrieve it later. ## Delete an API key You cannot delete a publishable key. You can only delete a secret key. To delete an API key: 1. Go to the [API keys](https://dashboard.yorlet.com/developers) page. 2. In the row for the key you want to delete, click the , then select **Delete key**. 3. Confirm that you want to delete the key. Deleting an API key is irreversible. If you delete an API key, you can’t retrieve it later. ## Create a secret API key To create a secret API key: 1. Go to the [API keys](https://dashboard.yorlet.com/developers) page. 2. Click the **Create secret key** button. 3. Enter a name for the API key and a note (optional). 4. Click **Create**. 5. The window displays the new key value. Copy it by clicking it. 6. Save the key value. You can’t retrieve it later. ## Agent keys Agent keys authenticate Claude or ChatGPT against Yorlet. Writes still go through [agent policy](/business-automation/ai/policy) and the [Approvals](/business-automation/ai/approvals) inbox. To create an agent key: 1. Go to the [API keys](https://dashboard.yorlet.com/developers) page. 2. Under **Agent keys**, click **Create agent key**. 3. Enter a name for the key and a note (optional). 4. Click **Create**. 5. The window displays the new key value. Copy it by clicking it. 6. Save the key value. You can’t retrieve it later. See [External agents](/business-automation/ai/agent-keys) to create a key, then [MCP](/business-automation/ai/mcp) to connect Claude or ChatGPT. ## Restricted keys Restricted keys allow you to limit access to specific resources or actions. This is useful when you want to grant third-party services or team members access to your Yorlet account without giving them full control. When creating a restricted key, you can configure permissions for each resource type: * **None**: No access to the resource * **Read**: Can view the resource but cannot make changes * **Write**: Can view and modify the resource ### Create a restricted key To create a restricted key: 1. Go to the [API keys](https://dashboard.yorlet.com/developers) page. 2. Click the **Create restricted key** button. 3. Enter a name for the API key and a note (optional). 4. Configure the permissions for each resource type. 5. Click **Create**. 6. The window displays the new key value. Copy it by clicking it. 7. Save the key value. You can't retrieve it later. ## Use an API key Include the API key in the `Authorization` header of your requests to the Yorlet API. ```http theme={"theme":"dracula"} Authorization: Bearer {{API_KEY}} ``` Learn more about [API Authentication](https://api-docs.yorlet.com/#authentication). #### Example use cases The following code sample shows a request to list all the applications for your account. ```http theme={"theme":"dracula"} curl https://api.yorlet.com/v1/applications \ -H "Authorization: Bearer {{SECRET_KEY}}" ``` # Yorlet-Context header Source: https://docs.yorlet.com/development/context Learn how to use the Yorlet-Context header to view organisation-wide data. The `Yorlet-Context` header is a way to view organisation-wide data. You can use the header to view data for all accounts in your organisation. ## Retrieve the organisation ID You can retrieve the organisation ID from the [organisation settings](https://dashboard.yorlet.com/org/settings/org) page in the Dashboard. ## Example use case The following code sample shows a request to list all the applications for your organisation. ```http theme={"theme":"dracula"} curl https://api.yorlet.com/v1/applications \ -H "Authorization: Bearer {{SECRET_KEY}}" \ -H "Yorlet-Context: {{ORGANISATION_ID}}" ``` # Dates Source: https://docs.yorlet.com/development/essentials/dates Learn how to work with dates in Yorlet. When working with dates in Yorlet, you should always use UTC. * Consistency: UTC provides a universal time reference, avoiding confusion with different time zones. * Accuracy: Using UTC ensures precise timing for events and transactions across global systems. * API compatibility: Yorlet's API expects and returns unix timestamps in UTC. ## Key considerations * In all API requests and responses, timestamps are in UTC format * Always convert local times to UTC before sending to Yorlet's API * When displaying dates to users, convert from UTC to their local timezone * Use Unix timestamps for date values (e.g., `1704067200` for January 1st, 2024 00:00:00 UTC) ## Working with dynamic timezones Many regions observe daylight saving time, which creates dynamic timezone offsets throughout the year. This is particularly important when working with billing cycles, subscription renewals, and scheduled payments. ### Example: British Summer Time (BST) The United Kingdom observes British Summer Time from late March to late October, creating different UTC offsets: * **Winter (GMT)**: UTC+0 - January 1st 00:00 local time = January 1st 00:00 UTC * **Summer (BST)**: UTC+1 - June 1st 00:00 local time = May 31st 23:00 UTC This means a subscription set to renew at midnight UK time will occur at different UTC times depending on the season. ## Date configuration object If you cannot directly specify a UTC timestamp for a date, you can instead define your desired date using a configuration object. Use the JSON format below to set a start date: ```json theme={"theme":"dracula"} { "start_date_config": { "day": 1, "month": 1, "year": 2025 } } ``` In this example, the start date is January 1st, 2025. Yorlet will automatically convert this configuration into the appropriate UTC timestamp for your account. ### Special cases for end dates When setting end-date configuration parameters (e.g., `end_date_config`), Yorlet automatically adjusts the time to 23:59:59. This ensures that the end date is fully inclusive. # Metadata Source: https://docs.yorlet.com/development/essentials/metadata Store extra information on a record and include it in exports. Metadata is a set of key-value pairs you attach to a record. Use it for references from your own systems, or for extra fields you want in reports and exports. Metadata is not shown to customers unless you choose to display it. ## Configuration ### Data You can add 50 total key-value pairs within these data limits: * **key**: 40 character limit. Square brackets (`[` `]`) can’t be included in keys. * **value**: 500 character limit. If your system requires more space than this, store your data in your external database and use a key-value pair to store the external object’s `ID` in `metadata`. If you want to display a single field to customers, explore using `description`. Metadata isn’t visible to your customers unless you choose to show it. Never store sensitive information, such as bank account information, to metadata. # Events and logs Source: https://docs.yorlet.com/development/events Use events and API logs to see an object's history and who made a change. Whenever something happens in your account — a Customer is updated, an Invoice is paid, a Tenancy is activated — Yorlet records an **event**. Events are the history of your objects. **Logs** are the API requests that caused those changes, including which team member or API key made them. Use them together: events tell you *what* changed, and the linked log tells you *who* did it and *how*. ## What is an event? An event is a snapshot of a record at the moment something happened. Each event has: * A **type**, such as `customer.updated` or `invoice.paid`. See the [full list of event types](/api/events). * The **object** as it was when the event occurred. * **Previous attributes** on update events — the fields that changed and their values before the change. * A **request**, including who caused it and the log ID for the API call. Events are also sent to [webhook endpoints](/development/webhooks) you subscribe, and can start a [workflow](/business-automation/workflows/triggers). ## See an object's history Most records in the Dashboard include an **Events** table at the bottom of the page. This is the history of that object: created, updated, paid, cancelled, and so on. To review a Customer's history, follow these steps: 1. Open the [Customers](https://dashboard.yorlet.com/customers) page and select a Customer. 2. Scroll to **Events**. 3. Click an event to open it. You will see the time, who caused it, the event data, and any previous attributes. The same **Events** table appears on Invoices, Subscriptions, Tenancies, Applications, Units, Buildings, Payments, and other records. Open [Events](https://dashboard.yorlet.com/developers/events) to browse every event in the account. Use the **Object ID** filter to find events that involve a specific record, or the **Type** filter to narrow to a type such as `invoice.paid`. ## See who made a change The event tells you what changed. The linked **log** tells you who made the request, from which IP address, and with which request body. To trace a change back to a person or API key, follow these steps: 1. Open the event — either from the object's **Events** table or from [Events](https://dashboard.yorlet.com/developers/events). 2. Check **Actor**. This is the kind of principal that caused the event: * **Dashboard user** — a team member in the Dashboard. * **API** — a secret or restricted API key. * **Agent** — an [agent key](/business-automation/ai/agent-keys). * **System** — Yorlet itself, for example a subscription generating an invoice. 3. Click **Source** (Dashboard, API, or Customer portal). This opens the log for that request. 4. On the log, read: * **User** — the team member's email, when the request came from the Dashboard. * **Key** — the API key ID, when the request used a key. * **IP address** and **User agent**. * **Request body** — the payload that was sent (for `POST` requests). * **Response body** — what Yorlet returned. The event's `request.id` is the same as the log ID (it starts with `req_`). You can also open a log directly at [Logs](https://dashboard.yorlet.com/developers/logs). Logs list mutating requests (`POST` and `DELETE`). Reads (`GET`) are not stored. Some events are created by Yorlet in the background and have no log — for example a Subscription generating an Invoice. Those events show **System** as the actor. ### Filter logs by object To see every mutating request that touched a record, without starting from an event: 1. Go to [Logs](https://dashboard.yorlet.com/developers/logs). 2. Filter by **Object ID** and paste the record's ID. 3. Use the **Succeeded** and **Failed** tabs to separate successful changes from errors. Each row shows the HTTP method, URL, status, and time. Click a row to inspect the request and response. ## Event object When you retrieve an event from the API, or inspect one in the Dashboard, the payload looks like this: ```json theme={"theme":"dracula"} { "id": "evt_1a2b3c4d", "object": "event", "api_version": "2025-08-21", "created": 1718712000, "type": "customer.updated", "data": { "object": { "id": "cus_123", "object": "customer", "email": "ada@example.com" }, "previous_attributes": { "email": "ada@old.example.com" } }, "request": { "actor": { "type": "user", "id": "user_123", "name": "ada@yourfirm.com", "key_id": null, "key_type": null }, "customer_portal": false, "from_dashboard": true, "id": "req_abc", "idempotency_key": null } } ``` | Field | Description | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Unique identifier for the event. | | `type` | The event type, for example `customer.updated`. See the [full list](/api/events). | | `data.object` | The record the event relates to, at the time the event occurred. | | `data.previous_attributes` | For `*.updated` events, the keys that changed and their previous values. `null` otherwise. | | `request.id` | The API request ID. Matches the log in [Logs](https://dashboard.yorlet.com/developers/logs). `null` when Yorlet created the event itself. | | `request.from_dashboard` | `true` when a team member made the change in the Dashboard. | | `request.customer_portal` | `true` when the change came from a customer-facing portal. | | `request.actor` | Who caused the event. `null` on events created before actor attribution existed. | | `request.idempotency_key` | The [idempotency key](/api/idempotency) on the request, if one was sent. | ### Actor `request.actor` identifies the principal that caused the event: | `type` | Meaning | | --------- | ----------------------------------------------------------------------- | | `user` | A Dashboard team member. `id` is the user ID and `name` is their email. | | `api_key` | A secret or restricted API key. `key_id` is the key that was used. | | `agent` | An [agent key](/business-automation/ai/agent-keys). | | `system` | Yorlet, not a person or key. | ## Events API List and retrieve events with a [secret key](/development/api-keys) that has the `events.read` permission. ### List events for an object Pass `object_id` to return events whose primary record is that object — the same set you see on the object's **Events** table: ```shell theme={"theme":"dracula"} curl "https://api.yorlet.com/v1/events?object_id=cus_123" \ -H "Authorization: Bearer {access_token}" ``` Pass `related_object` to include events that mention the ID even when it is not the primary record. For example, an `invoice.paid` event for a Customer's Invoice: ```shell theme={"theme":"dracula"} curl "https://api.yorlet.com/v1/events?related_object=cus_123" \ -H "Authorization: Bearer {access_token}" ``` The Dashboard **Object ID** filter on [Events](https://dashboard.yorlet.com/developers/events) uses `related_object`. ### Filter by type Match an exact type, or use a trailing `*` to match a prefix: ```shell theme={"theme":"dracula"} curl "https://api.yorlet.com/v1/events?type=invoice.paid" \ -H "Authorization: Bearer {access_token}" ``` ```shell theme={"theme":"dracula"} curl "https://api.yorlet.com/v1/events?type=invoice.*" \ -H "Authorization: Bearer {access_token}" ``` ### Retrieve an event ```shell theme={"theme":"dracula"} curl https://api.yorlet.com/v1/events/{id} \ -H "Authorization: Bearer {access_token}" ``` Events are returned newest first. Use `limit` (default 20, maximum 50) and `offset` to page through results. To reconstruct user activity in your own tools, list events for the object, then join each `request.id` to the log in the Dashboard. The log has the team member's email and the raw request body; the event has the resulting object and `previous_attributes`. ## Events, logs, and the activity log These are three different records of activity: | | What it shows | Where to find it | | ---------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | **Events** | What happened to a record (created, updated, paid, and so on). | The **Events** table on the record, [Events](https://dashboard.yorlet.com/developers/events), or `GET /v1/events`. | | **Logs** | The mutating API request behind a change — who, from where, and with which payload. | [Logs](https://dashboard.yorlet.com/developers/logs), or the **Source** link on an event. | | **Activity log** | Changes to account *settings*, not to Customers, Invoices, or other records. | [Settings → Security → Activity](https://dashboard.yorlet.com/settings/security/activity). See [Activity](/account/audit-logs). | # CSV imports Source: https://docs.yorlet.com/development/imports Bulk-create Yorlet records by uploading CSV files in the Dashboard. CSV imports let you create records in bulk by uploading a spreadsheet as a CSV file. Go to [Developers → Imports](https://dashboard.yorlet.com/developers/imports) to upload a file, review the rows, fix any issues, and run the import. The supported import types are: * **Account collections** * **Customers** * **Units** * **Invoices** ## Permissions You need access to the Developers area to view Imports. To run an import, you also need permission to create the records for that import type: | Import type | Permission | | :------------------ | :------------------------- | | Account collections | Create account collections | | Customers | Create customers | | Units | Create units | | Invoices | Create invoices | ## Run an import The workflow is the same for every import type. Choose the type you want to import (account collections, customers, units, or invoices). If only one type is available, Yorlet selects it for you. Click **Download template** to download a CSV with the correct column headers for the selected import type. Click **Upload CSV** or drag a CSV file onto the import panel. Non-CSV files are rejected. Yorlet checks every row before creating anything. Rows with issues are highlighted, with a message explaining what needs to be fixed. Some import types have options that change how rows are read. For example, account collections and invoices let you choose whether amount values are in pence or pounds, and units let you pick the currency. The import button is enabled when every row has no issues and you have permission to create the records for that import type. Yorlet shows progress while the import runs, then displays a completion summary. ### Fix issues inline Cells in the preview table are editable. Click a cell to change the value from your CSV; Yorlet checks the row again as you type. Where Yorlet can interpret a value, the preview shows a formatted version. For example, amounts show a formatted currency value such as `£330.00`. While editing, the cell shows the original value from the CSV. Use **Show N with issues** to filter the preview to rows that need attention. ### Re-run an import If some rows fail while processing, fix those rows and run the import again. Yorlet tracks rows that were already created and never submits them again, so re-running only attempts the remaining rows. After the first run, the button changes from **Run import** to **Import N remaining**. ## CSV formatting basics These rules apply to every import type: * Column names are not case-sensitive, so `Type` and `type` both work. * Extra spaces at the start or end of values are ignored. * Blank values are treated as empty. * Nested fields use dotted columns, such as `address.line1`. * Custom metadata uses `metadata.` columns, such as `metadata.external_id`. For invoices you can also set per-line-item metadata with `line_items..metadata.`. * Boolean columns accept `true`/`false`, `yes`/`no`, `y`/`n`, or `1`/`0`. ## Account collection CSV format Use these headers for account collection imports: ```csv theme={"theme":"dracula"} type,owner,destination,unit,currency,amount,description,expense_code,fee_code,invoice_number,po_number ``` ### Fields | Header | Description | | :--------------- | :---------------------------------------------------------------------------------------------------------------- | | `type` | The account collection type. Can be `expense`, `fee`, or `service_charge`. | | `owner` | The owner account to collect from. | | `destination` | Optional owner account to allocate the collected funds to. Leave blank to allocate funds to the platform account. | | `unit` | Optional unit related to the account collection. | | `currency` | Three-letter currency code, such as `gbp`. | | `amount` | Amount to collect. How this is interpreted depends on the selected amount format. | | `description` | Description for the account collection. | | `expense_code` | Expense code used when `type` is `expense`. | | `fee_code` | Fee code used when `type` is `fee`. Required only for fee collections. | | `invoice_number` | Optional invoice reference. | | `po_number` | Optional purchase order reference. | ### Amount format Choose how Yorlet should interpret the `amount` column: * **Smallest unit**: Use this if your CSV stores amounts in pence. For example, `1500` means `£15.00`. * **Major unit**: Use this if your CSV stores amounts in pounds. For example, `15.00` means `£15.00`. ### Expense and fee codes For `type: expense`, `expense_code` can be one of: ```text theme={"theme":"dracula"} compliance, council_tax, ground_rent, insurance, maintenance, utilities, other ``` If `expense_code` is blank or unknown, Yorlet uses `other`. For `type: fee`, `fee_code` must be one of: ```text theme={"theme":"dracula"} management_fee, tenant_find_fee, renewal_fee, rent_review_fee ``` Fee details are required only when `type` is `fee`. ## Customer CSV format Use these headers for customer imports: ```csv theme={"theme":"dracula"} email,name,phone,description,invoice_prefix,next_invoice_sequence,address.line1,address.line2,address.city,address.state,address.postal_code,address.country,legal.first_name,legal.last_name,legal.dob,invoicing.email_to,invoicing.email_cc,invoicing.arrears_emails,metadata.example ``` ### Fields | Header | Description | | :------------------------- | :------------------------------------------------------------------------------------ | | `email` | The customer's email address. Required. | | `name` | The customer's full name. | | `phone` | The customer's phone number. | | `description` | An arbitrary description attached to the customer. | | `invoice_prefix` | Prefix used to generate the customer's invoice numbers. | | `next_invoice_sequence` | The sequence number to use for the customer's next invoice. | | `address.line1` | First line of the customer's address. | | `address.line2` | Second line of the customer's address. | | `address.city` | City of the customer's address. | | `address.state` | State or region of the customer's address. | | `address.postal_code` | Postal code of the customer's address. | | `address.country` | Country of the customer's address. | | `legal.first_name` | The customer's legal first name. | | `legal.last_name` | The customer's legal last name. | | `legal.dob` | The customer's date of birth. Accepts `YYYY-MM-DD` or `DD/MM/YYYY`. | | `invoicing.email_to` | Primary email address to send invoices to. Defaults to the customer email when blank. | | `invoicing.email_cc` | Email addresses to CC on invoice emails. Separate multiple addresses with `;`. | | `invoicing.arrears_emails` | Whether the customer should receive arrears emails. Boolean. | | `metadata.example` | Example metadata column. Add your own with `metadata.`. | ## Unit CSV format Use these headers for unit imports: ```csv theme={"theme":"dracula"} name,address.line1,address.line2,address.city,address.state,address.postal_code,address.country,building,management_type,bedrooms,floor,furnished,reference,square_foot,metadata.example ``` ### Fields | Header | Description | | :-------------------- | :--------------------------------------------------------------------------------------- | | `name` | The name of the unit. Required. | | `address.line1` | First line of the unit's address. | | `address.line2` | Second line of the unit's address. | | `address.city` | City of the unit's address. | | `address.state` | State or region of the unit's address. | | `address.postal_code` | Postal code of the unit's address. | | `address.country` | Country of the unit's address. Defaults to `GB` when an address is provided without one. | | `building` | The ID of the building the unit belongs to. | | `management_type` | How the unit is managed. One of `fully_managed`, `let_only`, or `rent_collection`. | | `bedrooms` | Number of bedrooms in the unit. | | `floor` | Floor the unit is on. | | `furnished` | Whether the unit is furnished. Boolean. | | `reference` | An external reference for the unit. | | `square_foot` | Floor area of the unit in square feet. | | `metadata.example` | Example metadata column. Add your own with `metadata.`. | ### Currency The unit's default currency is set from the **Currency** import option rather than a CSV column. Choose `GBP`, `EUR`, or `USD` before running the import. ## Invoice CSV format Invoice imports create **draft** invoices. Use these headers: ```csv theme={"theme":"dracula"} customer,currency,collection_method,description,auto_advance,days_until_due,metadata.example,line_items.0.description,line_items.0.amount,line_items.0.type,line_items.0.tax_percent,line_items.0.unit,line_items.0.transfer_behavior,line_items.0.transfer_destination,line_items.0.metadata.example,line_items.1.description,line_items.1.amount,line_items.1.type,line_items.1.tax_percent,line_items.1.unit,line_items.1.transfer_behavior,line_items.1.transfer_destination,line_items.1.metadata.example ``` ### Invoice fields | Header | Description | | :------------------ | :--------------------------------------------------------------------------------------------------------- | | `customer` | The ID of the customer who will be billed. | | `currency` | Three-letter currency code, such as `gbp`. Applied to the invoice and every line item. | | `collection_method` | How the invoice is collected. One of `charge_automatically` or `send_invoice`. Defaults to `send_invoice`. | | `description` | An arbitrary description attached to the invoice. | | `auto_advance` | Whether the invoice is automatically finalized and progressed through its lifecycle. Boolean. | | `days_until_due` | Number of days until the invoice is due. Valid only when `collection_method` is `send_invoice`. | | `metadata.example` | Example metadata column. Add your own with `metadata.`. | ### Line items Line items use indexed columns. The first line item uses `line_items.0.*`, the second uses `line_items.1.*`, and so on. The template ships with two slots; add more by extending the index (`line_items.2.*`, `line_items.3.*`, ...) up to a maximum of 20 line items. | Header | Description | | :---------------------------------------- | :-------------------------------------------------------------------------------------------- | | `line_items..description` | Description of the line item. | | `line_items..amount` | Amount for the line item. How this is interpreted depends on the selected amount format. | | `line_items..type` | Line item type. One of `charge`, `rent`, or `product`. Defaults to `charge`. | | `line_items..tax_percent` | Tax percentage applied to the line item. Defaults to `0`. | | `line_items..unit` | Optional unit related to the line item. | | `line_items..transfer_behavior` | How funds are transferred. One of `automatic`, `owner`, or `none`. Defaults to `automatic`. | | `line_items..transfer_destination` | The destination account for the transfer. | | `line_items..metadata.example` | Example per-line-item metadata column. Add your own with `line_items..metadata.`. | The invoice-level `currency` and `customer` are applied to every line item, so you do not need to repeat them per item. ### Amount format Choose how Yorlet should interpret line item `amount` values: * **Smallest unit**: Use this if your CSV stores amounts in pence. For example, `1500` means `£15.00`. * **Major unit**: Use this if your CSV stores amounts in pounds. For example, `15.00` means `£15.00`. # Create an application Source: https://docs.yorlet.com/development/integrations/applications/create-an-application Learn how to create an application with the Yorlet API. 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`. ```bash Retrieve a unit theme={"theme":"dracula"} curl https://api.yorlet.com/v1/units/unit_123 \ -H "Authorization: Bearer {{API_KEY}}" ``` ```json availability theme={"theme":"dracula"} { "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](/api/core/units/release) first, or set `release_unit` to `true` when you create the application: ```bash Release a unit to the market theme={"theme":"dracula"} curl https://api.yorlet.com/v1/units/unit_123/release \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{}' ``` ```json Release on create theme={"theme":"dracula"} { "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](/api/core/units/hold) 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](https://docs.yorlet.com/api/core/customers/create) or by providing the `applicants.customer_data` object in the application request. 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 "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`. 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 "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 } ] }' ``` 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`. ```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) | 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. ```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" } } ``` 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 ```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. 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: ```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 } } ``` 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. ```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 } ``` #### 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](/leasing/applications/create-an-application#unit-availability). ```json Release the unit theme={"theme":"dracula"} { "release_unit": 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 "Content-Type: application/json" \ -d '{ "application_configuration": "appconfig_abc123", "type": "standard", "unit": "unit_123", "release_unit": true, "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. 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](/development/integrations/payments/payment-method-sessions#create-a-payment-method-session) and associate it with the subscription you retrieved in the `subscription.created` event. # Create a subscription with Checkout Sessions Source: https://docs.yorlet.com/development/integrations/billing/create-a-subscription Learn how to create a subscription with Checkout Sessions. Checkout Sessions are a way to set up a subscription for your customers. You can create a Checkout Session for a specific amount and currency, and share the Checkout Session URL with your customers. Your customers can then subscribe using their preferred payment method. ## Create a customer Before creating a Checkout Session, you need to create a customer. You can create a customer using the [Customers API](https://docs.yorlet.com/api/core/customers/create). ```bash Create a customer theme={"theme":"dracula"} curl https://api.yorlet.com/v1/customers \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "email": "jane@example.com" }' ``` If the request completed successfully, the response contains the customer object. ```json Customer object theme={"theme":"dracula"} { "id": "cus_lrhplff1u4ZhIPSU", "object": "customer", "email": "jane@example.com" // ... other fields on the Customer object } ``` ## Create a Checkout Session To [create a Checkout Session](https://docs.yorlet.com/api/checkout/checkout-sessions/create), you need to specify the `currency`, `customer`, `description`, and `subscription_data`. ```bash Create a Checkout Session theme={"theme":"dracula"} curl https://api.yorlet.com/v1/checkout_sessions \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "currency": "gbp", "customer": "{{CUSTOMER_ID}}", "description": "Monthly rent subscription", "payment_method_types": ["card", "bacs_debit"], "subscription_data": { "collection_method": "charge_automatically", "interval": "month", "interval_count": 1, "items": [ { "description": "Monthly rent", "type": "rent", "price_data": { "amount": 10000, "currency": "gbp", "tax_percent": 0 } } ], "start_date": 1719225600 } }' ``` If the request completed successfully, the Checkout Session object contains the `url` parameter. ```json Checkout Session object theme={"theme":"dracula"} { "id": "cks_lvu4xju9NAB38beQ", "object": "checkout_session", // ... other fields on the Checkout Session object "url": "https://pay.yorlet.com/checkout/cks_lvu4xju9NAB38beQ-eyJhbGciOiJIUzI1NiJ9" } ``` ### Required parameters | Parameter | Type | Description | | ------------------- | ------ | ------------------------------------------------------------- | | `currency` | string | Three-letter ISO currency code (`gbp`, `eur`, or `usd`) | | `customer` | string | The ID of the customer to use for the Checkout Session | | `description` | string | The description shown to the customer on the Checkout Session | | `subscription_data` | object | Subscription configuration (see below) | ### Subscription data parameters The `subscription_data` object defines the subscription that will be created when the Checkout Session completes. Only `collection_method` and `interval` are required. | Parameter | Type | Required | Description | | ------------------------- | --------- | -------- | ------------------------------------------------------------------------------ | | `collection_method` | string | Yes | `charge_automatically` or `send_invoice` | | `interval` | string | Yes | Billing frequency: `month`, `week`, or `custom` | | `interval_count` | integer | No | Number of intervals between billing (required when `interval` is not `custom`) | | `items` | array | No | Line items for each billing period (required when `interval` is not `custom`) | | `phases` | array | No | Subscription phases (required when `interval` is `custom`) | | `application` | string | No | The identifier of the application to associate with the subscription | | `description` | string | No | The description of the subscription | | `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 | | `add_invoice_items` | array | No | One-time invoice items added to the first invoice | | `custom_fields` | array | No | Custom fields on invoices (max 4, each with `name` and `value`) | | `invoice_settings` | object | No | Invoice settings, including invoice-level `custom_fields` | | `use_future_billing_date` | boolean | No | Whether to use a future billing date for the first invoice | | `metadata` | object | No | Set of key-value pairs to attach to the subscription | ### 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 associated with the item | | `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 | ### Supported payment method types Use `payment_method_types` to control which payment methods are offered to the customer. | Type | Description | | --------------------- | -------------------------- | | `card` | Credit or debit card | | `bacs_debit` | Bacs Direct Debit (UK) | | `sepa_debit` | SEPA Direct Debit (EU) | | `autogiro` | Autogiro (Sweden) | | `bank_transfer` | Bank transfer | | `direct_transfer` | Direct transfer | | `gbp_credit_transfer` | GBP credit transfer | | `pay_by_bank` | Pay by Bank (Open Banking) | | `card_present` | In-person card payment | ### Collect terms of service acceptance Use `consent_collection` to require the customer to accept terms of service before completing the Checkout Session, and `custom_text.terms_of_service.message` to override the default terms text. ```bash Checkout Session with terms of service theme={"theme":"dracula"} curl https://api.yorlet.com/v1/checkout_sessions \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "currency": "gbp", "customer": "{{CUSTOMER_ID}}", "description": "Monthly rent subscription", "consent_collection": { "terms_of_service": true }, "custom_text": { "terms_of_service": { "message": "By subscribing, you agree to our terms and conditions." } }, "subscription_data": { "collection_method": "charge_automatically", "interval": "month", "interval_count": 1, "items": [ { "description": "Monthly rent", "type": "rent", "price_data": { "amount": 10000, "currency": "gbp", "tax_percent": 0 } } ] } }' ``` ### Share the Checkout Session URL After creating a Checkout Session, you will receive a Checkout Session URL. Share this link with your customers so they can subscribe using their preferred payment method. By default, Yorlet automatically emails the URL to the customer. Set `send_email` to `false` if you'd rather share the URL through your own application. ## Handle the Checkout Session completion When your customers complete the checkout process, you will receive a webhook event. You can use the [Webhook Endpoints API](https://docs.yorlet.com/api/core/webhook-endpoints/create) to set up a webhook endpoint and handle the event. # Update a subscription Source: https://docs.yorlet.com/development/integrations/billing/update-a-subscription Learn how to update an existing subscription. Once a subscription exists, you can [update it](https://docs.yorlet.com/api/billing/subscriptions/update) to change its payment method, reschedule billing, pause or resume collection, schedule a cancellation, apply a coupon, and more. Only include the fields you want to change - fields you omit are left untouched. ```bash Update a subscription theme={"theme":"dracula"} curl https://api.yorlet.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "default_payment_method": "{{PAYMENT_METHOD_ID}}" }' ``` If the request completed successfully, the response contains the updated subscription object. ```json Subscription object theme={"theme":"dracula"} { "id": "sub_lrhplff1u4ZhIPSU", "object": "subscription", "default_payment_method": "pm_l34dl7phkOVU7wcI", // ... other fields on the Subscription object } ``` ## Change the default payment method Set `default_payment_method` to the ID of a [payment method](https://docs.yorlet.com/api/payments/payment-methods/object) belonging to the subscription's customer. Pass `null` to remove the default payment method. ```bash Change the default payment method theme={"theme":"dracula"} curl https://api.yorlet.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "default_payment_method": "{{PAYMENT_METHOD_ID}}" }' ``` You can also switch how invoices are collected with `collection_method` (`charge_automatically` or `send_invoice`). Switching to `send_invoice` clears the default payment method type, since invoices are no longer charged automatically. ## Reschedule billing To move the point in the billing cycle that future periods are calculated from, set `billing_anchor` to a Unix timestamp. By default, this only affects the *next* period going forward. ```bash Reanchor the next billing period theme={"theme":"dracula"} curl https://api.yorlet.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "billing_anchor": 1735689600 }' ``` Set `billing_cycle_reset` to `true` to reset the *entire* current billing cycle around the new anchor, rather than only the next period. To change when a subscription ends, set `end_date` to a Unix timestamp, or `null` to let it continue indefinitely. ```bash Change the end date theme={"theme":"dracula"} curl https://api.yorlet.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "end_date": 1767225600 }' ``` ## Schedule a cancellation Set `cancel_at` to a Unix timestamp to automatically cancel the subscription at a future date. The date must be at least one day in the future. Pass `null` to remove a scheduled cancellation. ```bash Schedule a cancellation theme={"theme":"dracula"} curl https://api.yorlet.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "cancel_at": 1767225600 }' ``` You can also set `credit_note_data` on the same request to have Yorlet automatically issue a credit note when the subscription is later closed. To cancel a subscription immediately instead of scheduling it, use the [Cancel a subscription](https://docs.yorlet.com/api/billing/subscriptions/cancel) endpoint. ## Pause or resume collection Set `pause_collection` to stop Yorlet from collecting payment on new invoices, while still generating them according to `behavior`. Pass `null` to resume collection immediately. ```bash Pause collection theme={"theme":"dracula"} curl https://api.yorlet.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "pause_collection": { "behavior": "mark_uncollectible", "resumes_at": 1767225600 } }' ``` | Behavior | Description | | -------------------- | ----------------------------------------------------------- | | `draft` | Invoices are created but left as drafts and never finalized | | `mark_uncollectible` | Invoices are finalized but immediately marked uncollectible | | `void` | Invoices are finalized and immediately voided | ## Apply a coupon Set `coupon` to the ID of a [coupon](https://docs.yorlet.com/api/billing/coupons/object) to apply a discount to the subscription. ```bash Apply a coupon theme={"theme":"dracula"} curl https://api.yorlet.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "coupon": "{{COUPON_ID}}" }' ``` ## Add a one-off invoice item Use `add_invoice_items` to add one-time charges to the next invoice generated by the subscription, without changing the recurring items. ```bash Add a one-off invoice item theme={"theme":"dracula"} curl https://api.yorlet.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "add_invoice_items": [ { "description": "Late payment fee", "type": "charge", "amount": 2500, "currency": "gbp", "tax_percent": 0 } ] }' ``` To change the recurring items on a subscription (for example, updating the rent amount), use the [Subscription Items API](https://docs.yorlet.com/api/billing/subscription-items/update) instead. Set `proration_behavior` on the subscription update to `create_prorations` or `none` to control whether prorated invoice items are generated when a subscription item changes. ### Parameters All parameters are optional - only include the fields you want to change. | Parameter | Type | Description | | ------------------------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `collection_method` | string | `charge_automatically` or `send_invoice` | | `default_payment_method` | string \| null | The identifier of the default payment method for the subscription | | `billing_anchor` | timestamp | Date to anchor recurring billing (Unix timestamp) | | `billing_anchor_config` | object | Anchor config with `day_of_month` (1-31), as an alternative to `billing_anchor` | | `billing_cycle_reset` | boolean | Whether to reset the whole billing cycle around the new `billing_anchor`, rather than only the next period | | `end_date` | timestamp \| null | When billing ends (Unix timestamp) | | `end_date_config` | object | Date object (`day`, `month`, `year`) as an alternative to `end_date` | | `cancel_at` | timestamp \| null | Date to automatically cancel the subscription (must be at least one day in the future) | | `credit_note_data` | object | Credit note to issue automatically when the subscription closes, with `type` (`customer_balance`, `out_of_band`, or `refund`) | | `pause_collection` | object \| null | Pause collection with `behavior` (`draft`, `mark_uncollectible`, or `void`) and `resumes_at` (timestamp) | | `proration_behavior` | string | `create_prorations` or `none`, applied when subscription items change | | `coupon` | string | Coupon ID to apply to the subscription | | `add_invoice_items` | array | One-time invoice items added to the next invoice | | `phases` | array | Subscription phases (only applies when the subscription's `interval` is `custom`) | | `days_until_due` | integer | Days before an invoice is due | | `days_before_collection` | integer | Days before the billing date to create the invoice (0-7) | | `custom_fields` | array | Custom fields on invoices (max 4, each with `name` and `value`) | | `payment_settings` | object | Restricts which payment method types can be used to pay invoices, via `payment_method_types` | | `description` | string | The description of the subscription | | `metadata` | object | Set of key-value pairs to attach to the subscription | # Book a viewing Source: https://docs.yorlet.com/development/integrations/leads/book-a-viewing Learn how to look up bookable slots and book viewings with the Yorlet API. This guide shows you how to book a property viewing using the Viewings API. Viewings are booked against an [enquiry](/development/integrations/leads/create-an-enquiry), and Yorlet handles the confirmation, the calendar invite, the reminder, and the follow-up for you. ## Prerequisites Before booking a viewing, ensure you have: * The Leads product enabled on your account. * A [secret key](/development/api-keys). * An enquiry ID. * Viewing availability configured on the account, if you want to offer bookable slots. Your secret key can perform any action on your account, so only ever use it from your own server. Never embed it in a booking page, a mobile app, or anything else a lead can see. If you want leads to pick their own slot, send them a [booking link](#let-the-lead-book-their-own-slot) rather than calling the slots endpoint from the browser. The hosted page authenticates itself with a key scoped to that one enquiry, so your secret key never leaves your server. If a secret key is ever exposed, [roll it](/development/api-keys) immediately. ## Permissions | Permission | Grants | | ---------------------- | --------------------------------------------------- | | `leads.viewings.read` | Retrieve and list viewings, and list bookable slots | | `leads.viewings.write` | Book, reschedule, and transition viewings | ## Look up bookable slots Slots are derived from the account's weekly viewing availability, minus anything already on the calendar. They respect the configured viewing duration, buffer, minimum notice, and booking horizon, so anything returned is safe to offer a lead. ```bash List bookable slots theme={"theme":"dracula"} curl "https://api.yorlet.com/v1/leads/viewings/slots?enquiry=le_pXm2Qk8sZ1vBnRtY&from=1712716800&to=1713321600" \ -H "Authorization: Bearer {{API_KEY}}" ``` ```json Response theme={"theme":"dracula"} { "object": "list", "data": [ { "object": "leads.viewing_slot", "start_time": 1712743200, "end_time": 1712745000, "duration": 30 } ], "count": 1, "has_more": false } ``` | Parameter | Type | Required | Description | | --------- | --------- | -------- | ------------------------------------------------------------------------ | | `enquiry` | string | Yes | The enquiry to compute slots for | | `from` | timestamp | No | Start of the range. Defaults to now | | `to` | timestamp | No | End of the range. Defaults to 14 days after `from`, and must be after it | An empty `data` array usually means the account has no viewing availability configured, or the whole range falls inside the minimum notice period. ## Book a viewing Only `enquiry` and `start_time` are required. The unit and host default to whatever is on the enquiry, and the duration defaults to the account's viewing duration. ```bash Book a viewing theme={"theme":"dracula"} curl https://api.yorlet.com/v1/leads/viewings \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "enquiry": "le_pXm2Qk8sZ1vBnRtY", "start_time": 1712743200, "duration": 30, "unit": "unit_lrhplff1u4ZhIPSU", "assignee": "user_9fRtZm4nQpLxVsKd", "notes": "Lead is running late, buzz flat 4" }' ``` ```json Response theme={"theme":"dracula"} { "id": "lv_3nQpZr7tKmXwBsLd", "object": "leads.viewing", "created": 1712716800, "enquiry": "le_pXm2Qk8sZ1vBnRtY", "unit": "unit_lrhplff1u4ZhIPSU", "assignee": "user_9fRtZm4nQpLxVsKd", "start_time": 1712743200, "duration": 30, "status": "scheduled", "source": "manual", "notes": "Lead is running late, buzz flat 4", "canceled_at": null, "canceled_reason": null, "completed_at": null, "metadata": {} } ``` ### Viewing parameters | Parameter | Type | Required | Description | | ------------ | --------- | -------- | -------------------------------------------------------------------- | | `enquiry` | string | Yes | The ID of the enquiry to book the viewing for | | `start_time` | timestamp | Yes | When the viewing starts | | `duration` | integer | No | Length in minutes (5–480). Defaults to the account viewing duration | | `assignee` | string | No | The ID of the user hosting. Defaults to the enquiry's assignee | | `unit` | string | No | The ID of the unit being viewed. Defaults to the unit on the enquiry | | `notes` | string | No | Internal notes recorded against the viewing | | `metadata` | object | No | Key-value pairs for storing additional information | Booking a viewing also advances the enquiry to `viewing` when it is at an earlier stage, so you do not need to transition it yourself. Requests made with a secret key are only checked for collisions, not against your published availability, so your own team can book outside their usual windows. Bookings made by a lead through their booking link must fall exactly on a published slot. ## Let the lead book their own slot Rather than choosing a time on the lead's behalf, create a booking link on the enquiry and let them pick. Set `notification.type` to `email` to send it to them, or `none` to return the URL and deliver it yourself. ```bash Create a booking link theme={"theme":"dracula"} curl https://api.yorlet.com/v1/leads/enquiries/le_pXm2Qk8sZ1vBnRtY/booking_link \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "notification": { "type": "email" } }' ``` The response is a `leads.viewing_booking_link` object with the `enquiry` it belongs to and the `url` of the hosted booking page. The link is created on first use and reused for the lifetime of the enquiry, and the hosted page handles its own authentication, so you never expose an API key to the lead. Leads booking through the link can pick a slot, reschedule, and cancel, but they cannot record an outcome. Viewings they book have a `source` of `self_serve`; viewings your team books have `manual`. Turn on automatic booking links in the account's viewing settings and Yorlet emails the lead their link as soon as you transition the enquiry to `qualified` — no extra API call needed. ## Reschedule a viewing Pass a new `start_time` to the update endpoint. Yorlet re-checks the slot, sends the lead an updated confirmation, and reschedules the reminder and follow-up. ```bash Reschedule a viewing theme={"theme":"dracula"} curl https://api.yorlet.com/v1/leads/viewings/lv_3nQpZr7tKmXwBsLd \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "start_time": 1712829600 }' ``` You can also update `duration`, `assignee`, `unit`, and `notes`. Pass `null` to `assignee` or `unit` to clear them. ## Record the outcome Use the status endpoint once the viewing has happened, or to call it off. ```bash Mark a viewing as completed theme={"theme":"dracula"} curl https://api.yorlet.com/v1/leads/viewings/lv_3nQpZr7tKmXwBsLd/status \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "status": "completed" }' ``` | Status | Meaning | | ----------- | ------------------------------------------------------------------------------- | | `scheduled` | Booked and upcoming. Setting this again clears any recorded outcome | | `completed` | The lead attended. Records `completed_at` | | `canceled` | Called off. Records `canceled_at` and the optional `reason`, and frees the slot | | `no_show` | The lead did not attend, and the slot is freed | Marking a viewing as `completed` follows up with the lead and reminds the host to move them on to an application. ## What Yorlet sends the lead Booking a viewing through the API triggers the same lifecycle as booking one in the Dashboard: | When | What happens | | --------------------- | ----------------------------------------------------------------------------------- | | Booked or rescheduled | The lead is emailed a confirmation with a calendar invite, and the host is notified | | 24 hours before | The lead is reminded, unless the viewing has moved or already has an outcome | | After the end time | The lead is followed up with, and the host is nudged to record the outcome | | Marked as completed | The lead is followed up with, and the host is nudged towards an application | ## List viewings ```bash List upcoming viewings for an enquiry theme={"theme":"dracula"} curl "https://api.yorlet.com/v1/leads/viewings?enquiry=le_pXm2Qk8sZ1vBnRtY&sort=ascending&expand[]=assignee&expand[]=unit" \ -H "Authorization: Bearer {{API_KEY}}" ``` | Parameter | Type | Description | | ---------- | --------------- | ----------------------------------------- | | `enquiry` | string | Filter to viewings for a single enquiry | | `status` | string or array | Filter by one or more statuses | | `source` | string | `self_serve` or `manual` | | `unit` | string | Filter by the unit being viewed | | `assignee` | string | Filter by host | | `sort` | string | `ascending` or `descending` by start time | `enquiry`, `assignee`, and `unit` can each be expanded with `expand[]`. # Create an enquiry Source: https://docs.yorlet.com/development/integrations/leads/create-an-enquiry Learn how to capture and qualify leads with the Yorlet API. This guide shows you how to capture a lead using the Enquiries API. Enquiries let you record prospective tenants from your own website, portal, or CRM, collect their qualification details, and move them through your pipeline towards an application. ## Prerequisites Before creating an enquiry, ensure you have: * The Leads product enabled on your account. * A [secret key](/development/api-keys). * A qualification configuration ID, if you want to collect qualification answers. Your secret key can perform any action on your account, so only ever use it from your own server. Never put it in browser JavaScript, a mobile app, or a public repository, and never send it to a lead. To collect details directly from a lead, send them a hosted qualification form or [embed the form](/development/integrations/leads/embed-a-qualification-form) on your website rather than calling the API from the browser. Those pages authenticate themselves with a short-lived key scoped to a single configuration or enquiry, so your secret key never leaves your server. If a secret key is ever exposed, [roll it](/development/api-keys) immediately. ## Permissions | Permission | Grants | | ------------------------------------------ | ---------------------------------------------------------------------------------- | | `leads.enquiries.read` | Retrieve and list enquiries | | `leads.enquiries.write` | Create and update enquiries, transition status, attach qualification, create links | | `leads.qualification_configurations.read` | Retrieve and list qualification configurations | | `leads.qualification_configurations.write` | Create and update qualification configurations | | `leads.qualification_routes.read` | Retrieve and list qualification routes | | `leads.qualification_routes.write` | Create and update qualification routes | ## Create an enquiry Every field is optional, so you can capture a lead from as little as an email address and fill in the rest later. ```bash Create an enquiry theme={"theme":"dracula"} curl https://api.yorlet.com/v1/leads/enquiries \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "email": "jane@example.com", "name": "Jane Doe", "phone": "+441234567890", "unit": "unit_lrhplff1u4ZhIPSU" }' ``` ```json Response theme={"theme":"dracula"} { "id": "le_pXm2Qk8sZ1vBnRtY", "object": "leads.enquiry", "created": 1712716800, "assignee": null, "email": "jane@example.com", "name": "Jane Doe", "phone": "+441234567890", "qualification": { "answers": null, "custom_answers": null, "reason": null, "score": null }, "qualification_configuration": null, "reviewed_at": null, "reviewed_by": null, "source": null, "status": "new", "unit": "unit_lrhplff1u4ZhIPSU", "metadata": {} } ``` ### Enquiry parameters | Parameter | Type | Description | | ----------------------------- | ------ | ------------------------------------------------------------------------------------- | | `email` | string | The lead's email address. Required to email them a qualification form or booking link | | `name` | string | The lead's full name | | `phone` | string | The lead's phone number | | `unit` | string | The ID of the unit the lead is interested in | | `assignee` | string | The ID of the user who owns the lead | | `qualification_configuration` | string | Attach a qualification configuration on creation | | `qualification` | object | Submit `answers` and `custom_answers` alongside the enquiry | | `portal` | object | Portal details when the enquiry came from a property portal | | `metadata` | object | Key-value pairs for storing additional information | An enquiry created without qualification answers starts as `new`. An enquiry created with answers starts as `pending`, because there is something for your team to review. ## Collect qualification answers A qualification configuration defines the questions you ask a lead. You can build one in the Dashboard, or with the Qualification Configurations API. Each configuration exposes a `hosted_qualification_url` that a lead can complete in their browser — submitting it creates the enquiry for you. To put that same form on your own website, [embed it with Yorlet.js](/development/integrations/leads/embed-a-qualification-form). To collect answers against an enquiry that already exists, choose one of the approaches below. Attach a configuration to the enquiry and let Yorlet host the form. Set `notification.type` to `email` to send the lead their link straight away. ```bash Attach a qualification configuration theme={"theme":"dracula"} curl https://api.yorlet.com/v1/leads/enquiries/le_pXm2Qk8sZ1vBnRtY/attach \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "qualification_configuration": "lqc_8dTvKp3wQmXsLbNe", "notification": { "type": "email" } }' ``` Retrieve the link at any time — it is created on first use and reused for the lifetime of the enquiry. ```bash Create a qualification link theme={"theme":"dracula"} curl https://api.yorlet.com/v1/leads/enquiries/le_pXm2Qk8sZ1vBnRtY/qualification_link \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "notification": { "type": "none" } }' ``` The response is a `leads.enquiry_qualification_link` object with the `enquiry` it belongs to and the `url` of the hosted form. Send that URL to the lead however you like — the hosted page handles its own authentication, so you never expose an API key to the lead. An enquiry can only have one qualification configuration. Attaching a second one returns an error, so use the qualification link action when a configuration is already attached. If you collect the answers in your own form, submit them with the update endpoint. Answers are merged with anything already recorded, so you can submit them a few at a time. ```bash Submit qualification answers theme={"theme":"dracula"} curl https://api.yorlet.com/v1/leads/enquiries/le_pXm2Qk8sZ1vBnRtY \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "qualification": { "answers": { "move_in_date": "1_month", "budget": 150000, "household_occupants": 2, "has_pets": false, "employment_status": "employed", "income_range": "40k_50k", "has_right_to_rent": true }, "custom_answers": [ { "id": "q_parking", "value": true } ] } }' ``` Each entry in `custom_answers` needs the `id` of a custom question on the attached configuration, and a `value` that can be a string, number, boolean, or array of strings. ### Standard answers | Parameter | Type | Description | | -------------------------- | ------- | ----------------------------------------------------------------------------------- | | `move_in_date` | string | `immediately`, `1_month`, `2_months`, `3_months`, or `flexible` | | `budget` | number | Monthly budget, in the smallest currency unit | | `household_occupants` | number | How many people will live there | | `household_has_children` | boolean | Whether the household includes children | | `has_pets` | boolean | Whether the lead has pets | | `pet_types` | array | The types of pets the lead has | | `pet_details` | string | Free-form detail about the pets | | `employment_status` | string | The lead's employment status | | `employer_name` | string | The lead's employer | | `income_range` | string | `under_20k`, `20k_30k`, `30k_40k`, `40k_50k`, `50k_75k`, `75k_100k`, or `over_100k` | | `is_smoker` | boolean | Whether the lead smokes | | `current_situation` | string | `renting`, `homeowner`, `living_with_family`, `relocating`, or `other` | | `reason_for_moving` | string | Why the lead is moving | | `current_landlord_name` | string | The lead's current landlord | | `current_landlord_contact` | string | Contact details for the current landlord | | `has_right_to_rent` | boolean | Whether the lead has the right to rent | | `has_guarantor` | boolean | Whether the lead can provide a guarantor | ## Read the score Once answers are submitted, Yorlet scores them against the attached configuration and writes a short explanation. Retrieve the enquiry to read both, expanding the configuration if you need its questions too. ```bash Retrieve an enquiry theme={"theme":"dracula"} curl "https://api.yorlet.com/v1/leads/enquiries/le_pXm2Qk8sZ1vBnRtY?expand[]=qualification_configuration" \ -H "Authorization: Bearer {{API_KEY}}" ``` ```json Response theme={"theme":"dracula"} { "id": "le_pXm2Qk8sZ1vBnRtY", "object": "leads.enquiry", "status": "pending", "qualification": { "score": 82, "reason": "Strong fit. Moving within a month, budget above the asking rent, and no pets.", "answers": { "move_in_date": "1_month", "budget": 150000 }, "custom_answers": [{ "id": "q_parking", "value": true }] } } ``` Scoring runs in the background, so `score` and `reason` are `null` for a short time after the first submission. ## Move the enquiry through your pipeline Use the status endpoint to progress a lead. Pass an optional `reason` to record why. ```bash Qualify an enquiry theme={"theme":"dracula"} curl https://api.yorlet.com/v1/leads/enquiries/le_pXm2Qk8sZ1vBnRtY/status \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "status": "qualified", "reason": "Affordability and move-in date both check out" }' ``` | Status | Meaning | | -------------- | ------------------------------------- | | `new` | Created without qualification answers | | `pending` | Answers submitted, awaiting review | | `contacted` | Your team has reached out | | `qualified` | Approved to progress | | `viewing` | A viewing is booked | | `application` | Moved into your application process | | `won` | The lead signed a tenancy | | `lost` | Closed without converting | | `disqualified` | Rejected during qualification | Transitions to `qualified` and `disqualified` record `reviewed_at` and `reviewed_by` on the enquiry. Moving to `qualified` also emails the lead their viewing booking link when the account has automatic booking links turned on. Booking a viewing advances the enquiry to `viewing` for you, so you do not need to set that status yourself. See [Book a viewing](/development/integrations/leads/book-a-viewing). ## List and filter enquiries ```bash List qualified enquiries theme={"theme":"dracula"} curl "https://api.yorlet.com/v1/leads/enquiries?status[]=qualified&status[]=viewing&expand[]=unit" \ -H "Authorization: Bearer {{API_KEY}}" ``` | Parameter | Type | Description | | ----------------------------- | --------------- | ----------------------------------------------------------------- | | `status` | string or array | Filter by one or more pipeline statuses | | `source` | string | Filter by the channel the enquiry came from | | `assignee` | string | Filter by owner, or pass `unassigned` for enquiries with no owner | | `qualification_configuration` | string | Filter by attached configuration | | `qualified` | boolean | Filter to enquiries that have been qualified | | `email` | string | Filter by the lead's email address | Enquiries are returned newest first, and `assignee`, `unit`, and `qualification_configuration` can each be expanded with `expand[]`. ## Route enquiries automatically Rather than attaching a configuration on every create call, use the Qualification Routes API to attach one whenever a matching enquiry arrives. Leave a condition empty to match anything, and give your most specific routes the lowest `priority`. ```bash Create a qualification route theme={"theme":"dracula"} curl https://api.yorlet.com/v1/leads/qualification_routes \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "name": "Portal leads", "qualification_configuration": "lqc_8dTvKp3wQmXsLbNe", "conditions": { "sources": ["portal"], "portal_types": ["rightmove"] }, "notification": { "type": "email" }, "priority": 10, "active": true }' ``` Routing is skipped for enquiries that already have a configuration attached or that arrive with their answers submitted. # Embed a qualification form Source: https://docs.yorlet.com/development/integrations/leads/embed-a-qualification-form Add a Yorlet qualification form to your website without putting a secret key in the browser. This guide shows you how to embed a qualification configuration on your own website using [@yorlet/js](/development/libraries/yorletjs) or [@yorlet/react](/development/libraries/react). The SDK iframes the hosted form, so the lead fills in their details on your listing page and a new enquiry appears in your pipeline. If you would rather collect answers on your own server, use [Create an enquiry](/development/integrations/leads/create-an-enquiry) with a secret key. ## Prerequisites Before you embed a form, ensure you have: * The Leads product enabled on your account. * A [qualification configuration](/leads/qualification-configurations) with a hosted form URL. * A [publishable key](/development/api-keys) from your account. Do not put a secret key in your website, a mobile app, or a public repository. The embed needs a publishable key (`pk_…`) and the hosted form token (`qct_…`). The publishable key only unlocks the form for your account. It cannot create enquiries on its own. ## Get the form token To find the token, follow these steps: 1. Open [Qualification configurations](https://dashboard.yorlet.com/leads/qualification-configurations). 2. Copy the value from the **Form token** column, or open the configuration and copy **Form token** from the details page. The token starts with `qct_`. The configuration object id (`lqc_…`) will not work. You can also right-click a row and choose **Copy form token**. ## Add the form to a page Install the SDK and mount the form. ```html theme={"theme":"dracula"}
``` Or load the browser bundle: ```html theme={"theme":"dracula"}
``` ```tsx theme={"theme":"dracula"} import { QualificationForm, YorletProvider } from '@yorlet/react'; export function Enquire() { return ( { console.log('Enquiry submitted'); }} /> ); } ``` The iframe grows with the form. You do not need to set a height. ## Prefill and completion Pass `email` to send a known address through to the form as `prefilled_email`. Pass `unit` with the listing's unit id so the enquiry records that property. When the lead submits, `onComplete` fires. If the configuration is set to redirect after completion, the event includes `redirectUrl` — navigate the parent page yourself. The iframe will not change `window.top`. ```js theme={"theme":"dracula"} yorlet.qualification.mount('#enquire', { token: 'qct_...', email: 'jane@example.com', unit: 'unit_...', onComplete: ({ redirectUrl }) => { if (redirectUrl) { window.location.assign(redirectUrl); } }, }); ``` Call `unmount()` on the handle if you need to take the form off the page. ## What you get in Yorlet A successful submit creates an enquiry against that configuration, with the lead's contact details and answers. If the same person submits the same form again within seven days, Yorlet updates that enquiry instead of creating another. When those submits include different `unit` values, Yorlet adds each property to the same enquiry. Yorlet scores the answers in the background, the same as a hosted form opened in a new tab. You do not need `leads.enquiries.write` on a browser key — the hosted page uses a key scoped to that one configuration. To restrict which websites can embed the form, set **Allowed websites** on the configuration. Leave it blank to allow any website. If a form token is leaked, open the configuration, use the overflow menu (•••), and choose **Roll form token**. Hosted URLs and embed snippets must then be updated. ## Next steps * [Yorlet.js reference](/development/libraries/yorletjs) — install options and the full `mount` API * [Yorlet React](/development/libraries/react) — `YorletProvider` and `QualificationForm` * [Create an enquiry](/development/integrations/leads/create-an-enquiry) — server-side capture when you already have the answers * [Qualification configurations](/leads/qualification-configurations) — the questions the form asks # Integrations overview Source: https://docs.yorlet.com/development/integrations/overview Learn how to integrate Yorlet with your application. Yorlet provides a set of APIs that you can use to integrate your application with Yorlet. This guide provides an overview of the APIs and resources available to you. ## Start an integration Learn how to capture and qualify leads Add a qualification form to your own website Learn how to look up slots and book viewings Learn how to create and manage applications Learn how to create and manage subscriptions Learn how to create and manage payment sessions Learn how to collect payment methods from your customers ## Resources Learn how to create and manage API keys Explore the Yorlet API reference to learn more about the available endpoints # Payment Method Sessions Source: https://docs.yorlet.com/development/integrations/payments/payment-method-sessions Learn how to create and manage Payment Method Sessions to collect and save a payment method. Payment Method Sessions allow you to securely collect and save payment methods from your customers. Unlike Payment Sessions which collect a one-time payment, Payment Method Sessions save the payment method for future use with subscriptions, invoices, and transactions. ## Create a customer Before creating a Payment Method Session, you need a customer to attach the payment method to. You can either use an existing customer or create a new one using the [Customers API](https://docs.yorlet.com/api/core/customers/create). ```bash Create a customer theme={"theme":"dracula"} curl https://api.yorlet.com/v1/customers \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "email": "jane@example.com" }' ``` If the request completed successfully, the response contains the customer object. ```json Customer object theme={"theme":"dracula"} { "id": "cus_lrhplff1u4ZhIPSU", "object": "customer", "email": "jane@example.com" // ... other fields on the Customer object } ``` ## Create a Payment Method Session To [create a Payment Method Session](https://docs.yorlet.com/api/payments/payment-method-sessions/create), you need to specify the `customer` and `payment_method_types`. You can optionally include a `return_url` to redirect customers after the payment method is collected. ```bash Create a Payment Method Session theme={"theme":"dracula"} curl https://api.yorlet.com/v1/payment_method_sessions \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "customer": "{{CUSTOMER_ID}}", "payment_method_types": ["card", "bacs_debit"], "return_url": "https://example.com/success" }' ``` If the request completed successfully, the Payment Method Session object contains the `url` parameter. ```json Payment Method Session object theme={"theme":"dracula"} { "id": "pmsess_kfls092pPQalaj2", "object": "payment_method_session", "customer": "cus_lrhplff1u4ZhIPSU", "payment_method": null, "payment_method_types": ["card", "bacs_debit"], "return_url": "https://example.com/success", "url": "https://pay.yorlet.com/payment-methods/pmsess_kfls092pPQalaj2-eyJhbGciOiJIUzI1NiJ9" // ... other fields on the Payment Method Session object } ``` ### Supported payment method types You can collect the following payment method types: | Type | Description | | --------------------- | -------------------------- | | `card` | Credit or debit card | | `bacs_debit` | Bacs Direct Debit (UK) | | `sepa_debit` | SEPA Direct Debit (EU) | | `autogiro` | Autogiro (Sweden) | | `bank_transfer` | Bank transfer | | `direct_transfer` | Direct transfer | | `gbp_credit_transfer` | GBP credit transfer | | `pay_by_bank` | Pay by Bank (Open Banking) | | `card_present` | In-person card payment | ### Share the Payment Method Session URL After creating a Payment Method Session, share the `url` with your customer. They will be guided through a secure flow to enter their payment details. Once complete, they will be redirected to your `return_url`. By default, Yorlet automatically emails the `url` to the customer, so you don't need to share it yourself. Set `send_email` to `false` if you'd rather share the URL through your own application. ```bash Skip the automatic email theme={"theme":"dracula"} curl https://api.yorlet.com/v1/payment_method_sessions \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "customer": "{{CUSTOMER_ID}}", "payment_method_types": ["card"], "send_email": false }' ``` ## Collect payment method for a subscription You can associate a Payment Method Session with a subscription. Once the customer completes the session, the payment method will automatically be attached to the subscription. ```bash Create a Payment Method Session for a subscription theme={"theme":"dracula"} curl https://api.yorlet.com/v1/payment_method_sessions \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "customer": "{{CUSTOMER_ID}}", "payment_method_types": ["bacs_debit"], "subscription": "{{SUBSCRIPTION_ID}}", "return_url": "https://example.com/success" }' ``` ## Retrieve a Payment Method Session You can [retrieve a Payment Method Session](https://docs.yorlet.com/api/payments/payment-method-sessions/retrieve) to check its status and see which payment method was created. ```bash Retrieve a Payment Method Session theme={"theme":"dracula"} curl https://api.yorlet.com/v1/payment_method_sessions/{{PAYMENT_METHOD_SESSION_ID}} \ -H "Authorization: Bearer {{API_KEY}}" \ ``` Once the customer completes the session, the `payment_method` field will contain the ID of the created payment method. ```json Completed Payment Method Session theme={"theme":"dracula"} { "id": "pmsess_kfls092pPQalaj2", "object": "payment_method_session", "customer": "cus_lrhplff1u4ZhIPSU", "payment_method": "pm_l34dl7phkOVU7wcI", "payment_method_types": ["card"], "status": "complete" // ... other fields on the Payment Method Session object } ``` # Payment Sessions Source: https://docs.yorlet.com/development/integrations/payments/payment-sessions Learn how to create and manage Payment Sessions to accept a payment. Payment Sessions are a way to accept one-time payments from your customers. You can create a Payment Session for a specific amount and currency, and share the Payment Session URL with your customers. Your customers can then pay using their preferred payment method. ## Create a customer Before creating a Payment Session, you need a customer to associate the payment with. You can either use an existing customer or create a new one using the [Customers API](https://docs.yorlet.com/api/core/customers/create). ```bash Create a customer theme={"theme":"dracula"} curl https://api.yorlet.com/v1/customers \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "email": "jane@example.com" }' ``` If the request completed successfully, the response contains the customer object. ```json Customer object theme={"theme":"dracula"} { "id": "cus_lrhplff1u4ZhIPSU", "object": "customer", "email": "jane@example.com" // ... other fields on the Customer object } ``` ## Create a Payment Session To [create a Payment Session](https://docs.yorlet.com/api/payments/payment-sessions/create), you need to specify the `amount`, `currency`, `customer`, `mode`, and `payment_method_types`. You can optionally include a `return_url` to redirect customers after the payment is completed. ```bash Create a Payment Session theme={"theme":"dracula"} curl https://api.yorlet.com/v1/payment_sessions \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "amount": 10000, "currency": "gbp", "customer": "{{CUSTOMER_ID}}", "mode": "payment", "payment_method_types": ["card"], "return_url": "https://example.com/success" }' ``` If the request completed successfully, the Payment Session object contains the `url` parameter. ```json Payment Session object theme={"theme":"dracula"} { "id": "py_sess_lvu4xju9NAB38beQ", "object": "payment_session", "amount": 10000, "currency": "gbp", "customer": "cus_lrhplff1u4ZhIPSU", "status": "unpaid", "url": "https://pay.yorlet.com/sessions/py_sess_lvu4xju9NAB38beQ-eyJhbGciOiJIUzI1NiJ9" // ... other fields on the Payment Session object } ``` ### Supported payment method types You can accept payments using the following payment method types: | Type | Description | | --------------------- | -------------------------- | | `card` | Credit or debit card | | `bacs_debit` | Bacs Direct Debit (UK) | | `sepa_debit` | SEPA Direct Debit (EU) | | `autogiro` | Autogiro (Sweden) | | `bank_transfer` | Bank transfer | | `direct_transfer` | Direct transfer | | `gbp_credit_transfer` | GBP credit transfer | | `pay_by_bank` | Pay by Bank (Open Banking) | | `card_present` | In-person card payment | ### Share the Payment Session URL After creating a Payment Session, share the `url` with your customer. They will be guided through a secure flow to complete the payment. Once complete, they will be redirected to your `return_url`. You can also set `send_email` to `true` to automatically send the URL to the customer's email address. ```bash Send email to customer theme={"theme":"dracula"} curl https://api.yorlet.com/v1/payment_sessions \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "amount": 10000, "currency": "gbp", "customer": "{{CUSTOMER_ID}}", "mode": "payment", "payment_method_types": ["card"], "send_email": true }' ``` ## Optional parameters ### Reporting type Use the `reporting_type` parameter to categorize the payment for reporting purposes. Defaults to `charge`. | Type | Description | | -------------- | ------------------------ | | `advance_rent` | Advance rent payment | | `charge` | General charge (default) | | `deposit` | Deposit payment | | `holding_fee` | Holding fee payment | | `rent` | Rent payment | ```bash Payment Session with reporting type theme={"theme":"dracula"} curl https://api.yorlet.com/v1/payment_sessions \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "amount": 100000, "currency": "gbp", "customer": "{{CUSTOMER_ID}}", "mode": "payment", "payment_method_types": ["card", "bacs_debit"], "reporting_type": "deposit", "return_url": "https://example.com/success" }' ``` ### Transaction data Use the `transaction_data` parameter to configure how the resulting transaction should be processed, including transfer behavior and customer balance options. ```bash Payment Session with transaction data theme={"theme":"dracula"} curl https://api.yorlet.com/v1/payment_sessions \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "amount": 100000, "currency": "gbp", "customer": "{{CUSTOMER_ID}}", "mode": "payment", "payment_method_types": ["card"], "transaction_data": { "unit": "{{UNIT_ID}}", "transfer_data": { "use_unit_ownership": true } }, "return_url": "https://example.com/success" }' ``` | Parameter | Type | Description | | ---------------------------------- | ------- | --------------------------------------------------------------------------------- | | `unit` | string | The ID of the unit associated with the transaction | | `transfer_data.use_unit_ownership` | boolean | If a unit ID is supplied, transfers will be created based on the unit's ownership | | `customer_balance.apply` | boolean | Whether to apply the transaction amount to the customer's balance | | `customer_balance.description` | string | A description of the transaction to be applied to the customer's balance | ## Retrieve a Payment Session You can [retrieve a Payment Session](https://docs.yorlet.com/api/payments/payment-sessions/retrieve) to check its status and see the associated transaction. ```bash Retrieve a Payment Session theme={"theme":"dracula"} curl https://api.yorlet.com/v1/payment_sessions/{{PAYMENT_SESSION_ID}} \ -H "Authorization: Bearer {{API_KEY}}" ``` Once the customer completes the payment, the `status` field will change to `paid` and the `transaction` field will contain the ID of the created transaction. ```json Completed Payment Session theme={"theme":"dracula"} { "id": "py_sess_lvu4xju9NAB38beQ", "object": "payment_session", "amount": 10000, "currency": "gbp", "customer": "cus_lrhplff1u4ZhIPSU", "status": "paid", "transaction": "txn_m2k4jf8sL9pQr3nT" // ... other fields on the Payment Session object } ``` ## Cancel a Payment Session You can [cancel a Payment Session](https://docs.yorlet.com/api/payments/payment-sessions/cancel) if it is no longer needed. ```bash Cancel a Payment Session theme={"theme":"dracula"} curl -X POST https://api.yorlet.com/v1/payment_sessions/{{PAYMENT_SESSION_ID}}/cancel \ -H "Authorization: Bearer {{API_KEY}}" ``` # Yorlet React Source: https://docs.yorlet.com/development/libraries/react Embed a qualification form in React with the Yorlet React SDK. `@yorlet/react` wraps [@yorlet/js](/development/libraries/yorletjs) so you can drop a qualification form into a React tree. The form still iframes the hosted page — you never put a secret key in the browser. ## Install ```bash theme={"theme":"dracula"} npm install @yorlet/react @yorlet/js ``` ```tsx theme={"theme":"dracula"} import { QualificationForm, YorletProvider } from '@yorlet/react'; ``` Use a [publishable key](/development/api-keys) (`pk_…`) with the form token. Do not put a secret key or restricted key in the website. The publishable key only unlocks the hosted form for your account — it cannot create enquiries on its own. ## Embed a qualification form Copy the form token from a [qualification configuration](https://dashboard.yorlet.com/leads/qualification-configurations) — it is shown in the **Form token** column and on the configuration's details page. It is not the configuration object id (`lqc_…`). ```tsx theme={"theme":"dracula"} import { QualificationForm, YorletProvider } from '@yorlet/react'; export function Enquire() { return ( { console.log('Form is ready'); }} onComplete={(event) => { if (event.redirectUrl) { window.location.assign(event.redirectUrl); } }} /> ); } ``` Unmounting the component removes the iframe. You do not need to call `unmount()` yourself. ### `QualificationForm` props | Prop | Type | Description | | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------- | | `token` | string | Hosted form token. Must start with `qct_` | | `email` | string | Optional email passed through to the form | | `unit` | string | Optional unit id (`unit_…`) for the listing this form is on | | `publishableKey` | string | Account publishable key. Required when used without `YorletProvider` | | `origin` | string | Only needed when testing. Hosted-app origin. Overrides `YorletProvider` when both are set | | `onReady` | function | Called when the hosted form has painted | | `onResize` | function | Called with the iframe height in pixels whenever the form resizes | | `onComplete` | function | Called when the lead submits. Receives `{ redirectUrl }` when the configuration is set to redirect after completion | Any other props are passed through to the container `div`. ### `YorletProvider` Wrap a tree of forms that share the same publishable key. The provider is optional if you pass `publishableKey` on `QualificationForm`. ```tsx theme={"theme":"dracula"} ``` `useYorlet()` returns the client created by the nearest provider. ## Testing against a local hosted app You do not need `origin` in production. `YorletProvider` and `QualificationForm` already load the form from the production hosted app. Pass `origin` only when you are testing against a local `frontend-app`: ```tsx theme={"theme":"dracula"} ``` ## What happens after submit The lead's answers are stored on an enquiry in your pipeline. If the same person submits the same form again within seven days, Yorlet updates that enquiry instead of creating another. Pass `unit` on a listing page so the enquiry records that property. Further submits from the same person add more properties to the same enquiry. You do not need to call the Enquiries API from the page. If you want to send them somewhere else after they finish, handle `onComplete` — the iframe will not navigate the parent page itself. For a full walkthrough, see [Embed a qualification form](/development/integrations/leads/embed-a-qualification-form). # Yorlet.js Source: https://docs.yorlet.com/development/libraries/yorletjs Embed a qualification form on your website with the Yorlet JavaScript SDK. `@yorlet/js` iframes your hosted qualification form so leads can enquire from your own site. The form authenticates itself — you never put a secret key in the browser. ## Install ```bash theme={"theme":"dracula"} npm install @yorlet/js ``` ```js theme={"theme":"dracula"} import { Yorlet } from '@yorlet/js'; const yorlet = Yorlet.init({ publishableKey: 'pk_...', }); ``` ```html theme={"theme":"dracula"} ``` Use a [publishable key](/development/api-keys) (`pk_…`) with the form token. Do not put a secret key or restricted key in the website. The publishable key only unlocks the hosted form for your account — it cannot create enquiries on its own. ## Embed a qualification form Copy a publishable key from [API keys](https://dashboard.yorlet.com) and the form token from a [qualification configuration](https://dashboard.yorlet.com/leads/qualification-configurations). The token is shown in the **Form token** column and on the configuration's details page. It is not the configuration object id (`lqc_…`). ```html theme={"theme":"dracula"}
``` ```js theme={"theme":"dracula"} const form = yorlet.qualification.mount('#enquire', { token: 'qct_...', email: 'jane@example.com', onReady: () => { console.log('Form is ready'); }, onComplete: (event) => { if (event.redirectUrl) { window.location.assign(event.redirectUrl); } }, }); ``` `mount` returns a handle with `unmount()`, which removes the iframe and stops listening for messages. ### Options | Option | Type | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------- | | `token` | string | Hosted form token. Must start with `qct_` | | `email` | string | Optional email passed through to the form | | `unit` | string | Optional unit id (`unit_…`) for the listing this form is on | | `onReady` | function | Called when the hosted form has painted | | `onResize` | function | Called with the iframe height in pixels whenever the form resizes | | `onComplete` | function | Called when the lead submits. Receives `{ redirectUrl }` when the configuration is set to redirect after completion | The first argument can be a CSS selector or an `HTMLElement`. ## Testing against a local hosted app You do not need `origin` in production. `Yorlet.init()` already loads the form from the production hosted app. Pass `origin` only when you are testing against a local `frontend-app`: ```js theme={"theme":"dracula"} const yorlet = Yorlet.init({ publishableKey: 'pk_test_...', origin: 'http://localhost:3000', }); ``` ## What happens after submit The lead's answers are stored on an enquiry in your pipeline. If the same person submits the same form again within seven days, Yorlet updates that enquiry instead of creating another. Pass `unit` on a listing page so the enquiry records that property. Further submits from the same person add more properties to the same enquiry. You do not need to call the Enquiries API from the page. If you want to send them somewhere else after they finish, handle `onComplete` — the iframe will not navigate the parent page itself. For a full walkthrough, see [Embed a qualification form](/development/integrations/leads/embed-a-qualification-form). If you are using React, use [@yorlet/react](/development/libraries/react) instead of calling `mount` yourself. # Developer tools Source: https://docs.yorlet.com/development/overview Connect Yorlet to your applications with API keys, events, webhooks, and SDKs. Developer tools help you connect Yorlet to your own applications. Create API keys, inspect events and logs, listen for events with webhooks, and use the SDKs to create applications, collect payments, and keep your systems in sync. ## Get started Create secret and restricted keys for the Yorlet API Build common flows for leads, applications, billing, and payments See object history and who made a change Receive a notification when something changes in your account Endpoints, objects, and events for every resource ## Essentials Store extra information on a record and include it in exports How Yorlet stores and displays dates in your account timezone # Yorlet for Platforms Source: https://docs.yorlet.com/development/platforms/introduction Learn how to embed Yorlet's functionality to your software platform. Yorlet for Platforms is a set of tools that enables you to embed the functionality of the Yorlet API into your own application. You can use Yorlet Leasing, Yorlet Billing, Yorlet Owners, and provide financial services to your customers while Yorlet handles all the compliance and heavy lifting. To get started with Yorlet for Platforms, please [contact us](https://www.yorlet.com/contact). # API versioning Source: https://docs.yorlet.com/development/versioning Learn how Yorlet versions its API and how to upgrade safely. The Yorlet API is versioned with dated releases, so we can evolve the API and change response shapes without breaking your existing integration. Each version is a date, for example `2025-08-21`. ## Your account API version Every account is pinned to an API version. The first time you make an API request, your account is pinned to the latest version available at that time. From then on, requests keep using that pinned version unless you explicitly upgrade, so the shape of API responses and webhook payloads stays stable for your integration. You can see and change your account's version on the [API keys page](https://dashboard.yorlet.com/developers/api-keys) in the Dashboard. ## Overriding the version per request You can override your account's pinned version for a single request by sending the `Yorlet-Version` header. This is useful for testing a newer version before you upgrade your account. ```http theme={"theme":"dracula"} curl https://api.yorlet.com/v1/subscriptions \ -H "Authorization: Bearer {{SECRET_KEY}}" \ -H "Yorlet-Version: 2025-08-21" ``` Every response echoes the version it was rendered with back in the `Yorlet-Version` response header. Sending an unrecognised version returns a `400` error. ## Backwards compatibility When we change the shape of an object in a new version, older versions keep receiving the previous shape. For example, if a field is removed in a new version, accounts pinned to an earlier version continue to receive that field. This means upgrading is the only time a response shape changes for you, and you can do it on your own schedule. See the [API changelog](/development/api-changelog) for the changes introduced in each version. ## Upgrading and rolling back To upgrade, open the [API keys page](https://dashboard.yorlet.com/developers/api-keys) in the Dashboard and select **Upgrade available** in the **API version** section. Review the changes, then confirm. After upgrading you have **72 hours** to roll back to your previous version if you need more time to adapt your integration. Within that window, a **Roll back** option appears in the same section. Once the window passes, the upgrade is final. Changes to your account version can take a few minutes to take effect for requests made with an API key. ## Webhook endpoints Each [webhook endpoint](/development/webhooks) has its own API version, set to your account version when the endpoint is created. Events delivered to an endpoint are rendered with that endpoint's version, so you can upgrade your account without changing the payloads an existing endpoint receives. You can set an endpoint's version when you create it, or change it later. # Send Yorlet events to your webhook endpoints Source: https://docs.yorlet.com/development/webhooks Learn how to use webhooks to receive notifications about events in your Yorlet account. Webhooks notify your server when something changes in Yorlet. You create an endpoint, subscribe to the events you care about, and Yorlet sends an HTTP POST to your URL as those events happen. ## What are webhooks? Webhooks are a way for Yorlet to send real-time notifications to your server about events that happen in your Yorlet account. When an event occurs, Yorlet sends an HTTP POST request to the webhook’s configured URL with a payload of the event data. ## Use cases Webhooks are useful for a variety of use cases, such as: * Sending notifications to your server when events are created in your account. * Updating your database when events occur in your account. * Triggering actions in third-party services like Zapier, when events occur in your account. ## Events overview Yorlet generates events for various actions that occur in your account. You can subscribe to specific events to receive notifications about them. For example, you can subscribe to the `customer.created` event to receive a notification when a new customer is created in your account. See [Events and logs](/development/events) to browse events in the Dashboard, inspect who made a change, and list events from the API. See the [full list of event types](/api/events) for everything you can subscribe to. ## Webhook payloads Each delivery is an HTTP `POST` request with a JSON body describing the event: ```json theme={"theme":"dracula"} { "id": "evt_1a2b3c4d", "object": "event", "created": 1718712000, "type": "customer.created", "data": { "object": { "id": "cus_123", "object": "customer" }, "previous_attributes": null }, "request": { "id": "req_abc", "idempotency_key": null, "from_dashboard": false, "customer_portal": false } } ``` | Field | Description | | -------------------------- | --------------------------------------------------------------------------------------------------------- | | `id` | Unique identifier for the event. | | `object` | Always `event`. | | `created` | Time the event was created, as a Unix timestamp (seconds). | | `type` | The event type, e.g. `customer.created`. See the [full list](/api/events). | | `data.object` | The API resource the event relates to, at the time the event occurred. | | `data.previous_attributes` | For `*.updated` events, the keys that changed and their previous values. `null` otherwise. | | `request` | Details of the API request that triggered the event, including the `idempotency_key` if one was provided. | | `account` | Only present on endpoints configured for connected accounts; the ID of the account the event belongs to. | Your endpoint should respond with a `2xx` status code as quickly as possible to acknowledge receipt. Any other status code (or a network error) is treated as a failed delivery and is retried — see [Retries](#retries). ## Securing your webhooks Because your webhook URL is publicly reachable, you should verify that each request genuinely came from Yorlet before acting on it. Every endpoint has a **signing secret** that Yorlet uses to sign deliveries, letting you confirm both the authenticity and the freshness of each request. ### The signing secret The signing secret is generated automatically when you create an endpoint and begins with `whsec_`. It is sensitive and is only returned when you create, retrieve, or roll an endpoint — it is never included in list responses, so store it securely when you first receive it. ```json theme={"theme":"dracula"} { "object": "webhook_endpoint", "id": "we_1a2b3c4d", "url": "https://example.com/yorlet/webhooks", "signing_secret": "whsec_..." } ``` ### The `Yorlet-Signature` header When an endpoint has a signing secret, Yorlet includes a `Yorlet-Signature` header with each delivery: ``` Yorlet-Signature: t=1718712000,v1=5257a869e7ec... ``` The header contains two comma-separated values: | Value | Description | | ----- | --------------------------------------------------------------------------- | | `t` | The timestamp the signature was generated, in seconds since the Unix epoch. | | `v1` | The signature, an HMAC-SHA256 (hex encoded) of the signed payload. | The signed payload is the timestamp and the raw request body joined with a `.`: ``` signed_payload = {t}.{raw_request_body} signature = HMAC_SHA256(signing_secret, signed_payload) ``` ### Verifying signatures Parse the `Yorlet-Signature` header to read the `t` (timestamp) and `v1` (signature) values. Concatenate the timestamp, a `.`, and the **raw** request body (the exact bytes received — do not parse and re-serialize the JSON first, as that can change the payload). Compute an HMAC-SHA256 of this string using your endpoint's signing secret as the key, and hex encode it. Compare your computed signature with the `v1` value using a constant-time comparison. If they match, the request is authentic. Reject requests where the timestamp is outside an acceptable tolerance (for example, more than five minutes from the current time) to protect against replay attacks. You must read the **raw** request body to verify the signature. Many frameworks parse the body into an object before your handler runs; re-serializing that object can produce different bytes and cause verification to fail. Configure your framework to expose the raw body for your webhook route. The following example verifies a signature in Node.js: ```javascript theme={"theme":"dracula"} import crypto from 'node:crypto'; const TOLERANCE_SECONDS = 60 * 5; function verifyYorletSignature(rawBody, signatureHeader, signingSecret) { const parts = Object.fromEntries( signatureHeader.split(',').map((part) => part.split('=')) ); const timestamp = Number(parts.t); const signature = parts.v1; // Reject stale requests to mitigate replay attacks. if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > TOLERANCE_SECONDS) { return false; } const expected = crypto .createHmac('sha256', signingSecret) .update(`${timestamp}.${rawBody}`) .digest('hex'); // Constant-time comparison. return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature)); } ``` ### Rolling your signing secret If a signing secret is ever exposed, roll it to generate a new one. Rolling immediately invalidates the previous secret, so update your endpoint with the new value as soon as you roll it. ```shell theme={"theme":"dracula"} curl https://api.yorlet.com/v1/webhook_endpoints/{id}/roll_secret \ -X POST \ -H "Authorization: Bearer {access_token}" ``` The response includes the endpoint with its new `signing_secret`. ## Retries If your endpoint does not return a `2xx` status code, Yorlet retries the delivery with an exponential backoff over several attempts. Make sure your handler is idempotent: a single event may be delivered more than once, so use the event `id` to detect and ignore duplicates you have already processed. # Introduction Source: https://docs.yorlet.com/introduction Welcome to Yorlet. Set up your account, then explore the products you use every day. Yorlet is the operating system for property businesses. These docs show you how to set up your account, run day-to-day work in the Dashboard, and connect Yorlet to the rest of your stack. ## Set up your account Create customer records for tenants, applicants, and anyone you bill Add buildings and units so you can let, bill, and maintain your portfolio Add your business name, colour, and icon to emails and receipts Bring owners, units, tenancies, and invoices into Yorlet ## Explore our products Capture enquiries, qualify your leads, and book viewings Take an applicant from application through to an active tenancy Collect rent, manage invoices, and recover arrears Accept payments, save payment methods, and issue refunds Hold client funds and pay owners automatically from your balance Onboard landlords and suppliers, then pay them out ## Business automation An assistant for every team member, with paid seats for Recover triage and email Review conversations with customers and owners in one place Automate processes with triggers, conditions, and actions Track repairs from the first report through to resolution Print and post letters to tenants and owners from templates Use reports and exports to understand how the business is performing ## For developers API keys, webhooks, SDKs, and integration guides Endpoints, objects, and events for building on Yorlet # Leads Source: https://docs.yorlet.com/leads Capture enquiries, qualify your leads, and book viewings before onboarding a tenant. Leads is where every prospective tenant starts. An enquiry records who got in touch, which property they are interested in, and how far they have progressed. You can capture enquiries yourself, receive them from a portal such as Rightmove, or let leads submit their own details through a hosted qualification form. From there you qualify them, book a viewing, and hand the strongest leads over to [Leasing](/leasing). You can view and manage every enquiry from the [Enquiries page](https://dashboard.yorlet.com/leads/enquiries). ## How a lead progresses 1. An enquiry arrives, either created by your team or automatically from a portal or hosted form. 2. A [qualification configuration](/leads/qualification-configurations) collects the details you need, and Yorlet scores and summarises the answers for you. 3. You qualify the lead and [book a viewing](/leads/viewings), or send them a link so they can pick their own slot. 4. Once the viewing has taken place you move the lead on to an application. ## Enquiry statuses Every enquiry has a status that shows where it sits in your pipeline: * **New**: The enquiry has arrived but no qualification details have been submitted yet. * **Pending**: The lead has submitted their qualification answers and is waiting for your review. * **Contacted**: Someone on your team has reached out to the lead. * **Qualified**: The lead has been approved to progress. * **Viewing**: A viewing has been booked. * **Application**: The lead has moved into your application process. * **Won**: The lead has signed a tenancy. * **Lost**: The lead closed without converting. * **Disqualified**: The lead was rejected during qualification. Moving an enquiry to **Application** or **Won** records progress in your pipeline. It does not create the application itself, so you still need to [create an application](/leasing/applications/create-an-application) in Leasing. ## Viewing statuses Each viewing booked against an enquiry has its own status: * **Scheduled**: The viewing is booked and upcoming. * **Completed**: The viewing took place. * **No show**: The lead did not attend. * **Canceled**: The viewing was called off, and the slot is free to book again. ## Get started Create, triage, and progress enquiries through your pipeline Build reusable forms that collect and score the details you need Attach the right form automatically as new enquiries arrive Book viewings, let leads pick their own slot, and record outcomes # Enquiries Source: https://docs.yorlet.com/leads/enquiries Create, triage, and progress enquiries through your pipeline. The [Enquiries page](https://dashboard.yorlet.com/leads/enquiries) is where your team works through every lead. You can switch between views, create enquiries by hand, filter and export, and open any enquiry to see its qualification answers and viewings. ## Choosing a view Use the view switcher in the top right of the page to change how your enquiries are displayed: * **Split**: A list of enquiries alongside a preview of the selected enquiry, so you can work through them quickly without leaving the page. * **Table**: A full-width table of every enquiry, best for filtering and exporting. * **Board**: A kanban board with a column for each pipeline status. ## Where enquiries come from Enquiries reach your pipeline in three ways: * **Created by your team**: Someone rings up or emails you and you add them by hand. * **Submitted by the lead**: The lead completes a [qualification configuration](/leads/qualification-configurations) form using its hosted link. * **Received from a portal**: Connect a Rightmove branch from your [integration settings](https://dashboard.yorlet.com/settings/integrations) and incoming leads are created as enquiries automatically. Each enquiry records the source it came from, so you can see at a glance whether a lead arrived through a **Web form**, **Widget**, **Email**, **Portal**, **Phone**, **Referral**, or was added **Manually**. ## Creating an enquiry To create an enquiry, follow these steps: 1. Click **New enquiry** (or press **N**). 2. Enter the lead's **Email**, **Name**, and **Phone**. 3. Click **Create**. New enquiries start with the status **New**. If a [qualification route](/leads/qualification-routes) matches, Yorlet attaches a qualification form straight away and can email the lead a link to complete it. An email address lets you send the lead their qualification form and viewing booking link, so add one wherever you can. ## Working on the board The board gives you an at-a-glance view of your pipeline, with a column for each status. Each card shows the lead's name, email, phone, the unit they are interested in, their source, their qualification score, and how long ago the enquiry arrived. Drag a card from one column to another to change its status — for example, move a card into **Qualified** once you are happy to progress the lead, or into **Lost** when they go quiet. ## Filtering and exporting In the table and split views you can filter your enquiries by **Status**, **Source**, and **Assignee**. Click **Export** to download the enquiries currently shown, and any filters you have applied will be reflected in the exported file. Right-click any row to copy the lead's email or phone number, copy the enquiry ID, or open the enquiry in a new tab. ## Managing a single enquiry Open an enquiry to see its full detail. The page shows a timeline of what has happened, the lead's contact details and source, any portal information, their [viewings](/leads/viewings), and their qualification answers. From the enquiry you can: * Leave **comments** for your team. * Set an **assignee** so it is clear who owns the lead. * Use **Move to** to change the pipeline status. * Open the overflow menu (•••) to **Attach qualification**, **Copy qualification link**, **Send qualification form**, or **Update** the lead's contact details. Once a qualification form is attached, **Attach qualification** is replaced by the options to copy or send the link. **Send qualification form** is only available when the enquiry has an email address. ### Qualification score and summary When a lead submits their answers, Yorlet scores them out of 100 against the questions on the attached configuration and writes a short summary of how well they fit. The score appears on the enquiry, in the table, and on the board card, colour-coded so strong leads stand out. The summary appears at the top of the enquiry page. Marking an enquiry as **Qualified** or **Disqualified** records who reviewed it and when, and both appear on the enquiry timeline. # Qualification configurations Source: https://docs.yorlet.com/leads/qualification-configurations Build reusable forms that collect and score the details you need from a lead. A qualification configuration is a reusable form that asks a lead the questions you need answered before you spend time on a viewing — when they want to move in, what they can afford, whether they have pets, and anything else specific to your portfolio. You design it once and use it across as many enquiries as you like. Every configuration has its own hosted form that leads can complete in their browser. When they submit it, Yorlet records the answers on the enquiry, scores them, and writes a short summary so you can see the fit at a glance. You can manage your configurations from the [Qualification configurations page](https://dashboard.yorlet.com/leads/qualification-configurations). ## Creating a configuration To create a configuration, follow these steps: 1. Click **New configuration** (or press **N**). 2. Enter a **Name**. This is only used to identify the configuration internally and is never displayed to leads. 3. Turn on the **Questions** you want to ask, and set the options for each one. 4. Add any **Custom questions** of your own. 5. Click **Create**. ## Questions Turn on any of the standard questions below. Each one can be marked **Required**, and some have extra options that let you ask follow-up details or record your own letting criteria. * **Move-in date**: When the lead is looking to move. * **Budget**: The lead's monthly budget. * **Household**: How many people will live there. You can also **Ask number of occupants** and **Ask about children**. * **Pets**: Whether the lead has pets. Use **Pets allowed** to record whether pets are acceptable for this configuration. * **Employment**: The lead's employment status. You can also **Ask for employer name** and **Ask for income range**. * **Smoking**: Whether the lead smokes. Use **Non-smokers only** when smoking is not acceptable. * **Current situation**: Where the lead currently lives. You can also **Ask reason for moving** and **Ask for current landlord**. * **Right to rent**: Whether the lead has the right to rent in the UK. * **Guarantor**: Whether the lead can provide a guarantor if one is needed. Options such as **Pets allowed** and **Non-smokers only** tell Yorlet what you will accept, so they are taken into account when a lead's answers are scored. ## Custom questions Add your own questions to collect anything the standard set does not cover. Give each question a label and choose its type: * **Text**: A single line of text. * **Textarea**: A longer, free-text answer. * **Number**: A numeric answer. * **Checkbox**: A yes or no answer. * **Select**: One answer from a list of options you define. * **Multi-select**: Several answers from a list of options you define. Custom questions can be marked required in the same way as the standard ones, and **Select** and **Multi-select** questions need at least one option. ## Sharing the form Each configuration has a hosted form URL, shown in the **URL** column on the configurations table, and a form token (`qct_…`) in the **Form token** column. Click the copy icon to copy either value, or open the configuration to copy them from the details page. Right-click a row and choose **Preview form** to open the hosted form as a lead would see it, or **Copy form token** to copy the token. Anyone who completes the hosted form creates a new enquiry in your pipeline. ## Embed on your website To put the form on a listing page instead of sending leads to the hosted URL, copy the **Form token** and a [publishable key](/development/api-keys), then follow [Embed a qualification form](/development/integrations/leads/embed-a-qualification-form). Use [Yorlet.js](/development/libraries/yorletjs) or [Yorlet React](/development/libraries/react). The form still creates an enquiry in your pipeline — you never put a secret key on the website. On the configuration you can set **Allowed websites** to limit which origins may embed the form. Leave it blank to allow any website. If the same lead submits the form again within seven days, Yorlet updates their existing enquiry. Listing pages can pass a unit id so each property is added to that one enquiry. If a form token is shared more widely than you intended, open the configuration, use the overflow menu (•••), and choose **Roll form token**. The previous hosted URL and any embed that still uses the old token stop working immediately. You can also send the form to an enquiry that already exists. Open the enquiry, use the overflow menu (•••) to **Attach qualification**, then choose **Copy qualification link** or **Send qualification form**. Attaching a configuration also gives you the option to **Email the qualification form** straight away, so long as the enquiry has an email address. To attach a configuration to new enquiries automatically, set up a [qualification route](/leads/qualification-routes). ## Managing configurations Open a configuration from the [Qualification configurations page](https://dashboard.yorlet.com/leads/qualification-configurations) to see its details, then use the overflow menu (•••) and choose **Update** to change its name, questions, or allowed websites. The configurations table labels each configuration `Active` or `Archived`. Archived configurations are no longer offered when you attach a qualification to an enquiry. Answers already submitted against a configuration are kept on the enquiry, so changing or archiving a configuration never affects leads who have already completed the form. # Qualification routing Source: https://docs.yorlet.com/leads/qualification-routes Attach the right qualification form automatically as new enquiries arrive. Qualification routing saves you attaching a form to every enquiry by hand. A route watches for new enquiries that match the conditions you set — where they came from, which portal sent them, or which unit they are about to enquire about — and attaches the [qualification configuration](/leads/qualification-configurations) you have chosen. It can also email the lead a link to complete the form straight away, so qualification starts before anyone on your team picks the enquiry up. You can manage your routes from the [Qualification routing page](https://dashboard.yorlet.com/leads/qualification-routes). ## Creating a route To create a route, follow these steps: 1. Click **New route** (or press **N**). 2. Enter a **Name**, and a **Description** if it helps your team understand what the route is for. 3. Choose the **Qualification configuration** to attach when a matching enquiry arrives. 4. Set your match conditions: **Sources**, **Portals**, and **Units**. 5. Set a **Priority**. 6. Turn on **Email the qualification form** if you want the lead emailed a link as soon as the route matches. 7. Leave **Active** on so the route starts working, then click **Create**. ## Match conditions A route only attaches its configuration when an enquiry matches every condition you have set. Leave a condition empty to match anything. * **Sources**: The ways an enquiry can reach you — **Web form**, **Widget**, **Email**, **Portal**, **Phone**, **Manual**, or **Referral**. Leave empty to match any source. * **Portals**: The property portal the enquiry came from, such as **Rightmove**. Leave empty to match any portal. * **Units**: The specific units you want this route to cover. Click **Add unit** to add each one. Leave empty to match any unit. On the routes table and on each route, an unset condition is shown as `Any`. ## Priority More than one route can match the same enquiry, so each route has a priority that decides which one wins. Lower values are matched first, and new routes default to `100`. Give your most specific routes a lower number and your catch-all routes a higher one. Only one configuration is attached to an enquiry, so once the highest-priority matching route has been applied, no other route is considered. ## Which enquiries are routed Routing only applies to enquiries that arrive without any qualification details. An enquiry is skipped when it already has a configuration attached, or when the lead has already submitted their answers by completing a hosted form. If no route matches, and you have a default qualification configuration, Yorlet attaches that instead for enquiries that arrive by **Email**, **Phone**, **Portal**, or **Referral**, and emails the lead their link. ## Managing routes Open a route from the [Qualification routing page](https://dashboard.yorlet.com/leads/qualification-routes) to see its conditions, priority, configuration, and whether the lead is emailed. Use the overflow menu (•••) and choose **Update** to change any of it. Routes are labelled `Active` or `Archived`. Turn **Active** off to stop a route being applied to new enquiries without deleting it — enquiries it has already matched are unaffected. # Viewings Source: https://docs.yorlet.com/leads/viewings Book viewings, let leads pick their own slot, and record what happened. A viewing is an appointment between a lead and one of your team at a property. You can book one yourself, or send the lead a link and let them choose from the times you have made available. Yorlet handles the confirmation, the reminder, and the follow-up, so all you need to do is turn up and record the outcome. You can see every viewing across your pipeline on the [Viewings page](https://dashboard.yorlet.com/leads/viewings), and the viewings for a single lead on their enquiry. ## Choosing a view Use the view switcher in the top right of the [Viewings page](https://dashboard.yorlet.com/leads/viewings) to change how your viewings are displayed: * **Table**: A full-width table of every viewing, showing when it is, its status, the lead, the unit, the host, and whether it was booked by the lead or by your team. * **Board**: A kanban board with a column for each status (**Pending**, **Scheduled**, **Completed**, **No show**, and **Canceled**). * **Calendar**: A calendar of your viewings alongside your booking availability, so you can see how your week is filling up. You can filter the table by **Status**, **Source**, and **Host**. Selecting a viewing opens the enquiry it belongs to. ## Booking a viewing yourself Viewings are booked from the enquiry, so open the lead first and find the **Viewings** section. To book a viewing, follow these steps: 1. Click **Schedule viewing**. 2. Under **When**, pick a date, then choose one of the available times. If none of them suit, you can set your own time instead. 3. Choose the **Unit** the lead is viewing. 4. Choose a **Host** to show them round. 5. Add any **Notes** the host should know. 6. Click **Schedule**. Booking a viewing moves the enquiry to the **Viewing** status if it has not progressed that far already. The available times come from your [booking settings](#booking-settings) — or from the building’s own hours, if it has an override — and exclude anything already booked at that building. Your team is not held to those windows, so you can always set a custom time when a lead can only make an unusual slot. ## Letting the lead book Rather than agreeing a time back and forth, you can send the lead a link and let them pick a slot themselves. In the **Viewings** section of the enquiry, click **Booking link** and choose either **Copy booking link** or **Send booking link**. Sending the link requires an email address on the enquiry. Leads booking through the link can only choose from the times your [booking settings](#booking-settings) publish — using the building’s hours when that enquiry has a building — and they can reschedule or cancel using the same link. Viewings they book are shown as **Booked by lead**. You can also share a booking link for a whole building from the building record. A lead who books through that link signs in with OneMove (or leaves their contact details), picks a time, and Yorlet creates the enquiry for you. If **Require confirmation for building booking links** is on — or the building overrides it to require confirmation — those bookings start as **Pending**. They hold the slot until someone on your team confirms or declines them from the enquiry or the Viewings board. Enquiry booking links and viewings you schedule yourself are still confirmed immediately. A lead who signs in with OneMove on the same building link can see their current pending or scheduled viewing and cancel or reschedule it there. Guests without OneMove use the manage link in their email. Turn on **Send booking links automatically** in your booking settings and every lead is emailed their link the moment you mark them as **Qualified**. ## Recording the outcome If a viewing is **Pending**, open the overflow menu (•••) and choose **Confirm viewing** to accept the request, or **Decline** to cancel it. Confirming sends the usual confirmation email and calendar invite. Once a confirmed viewing has happened, record what came of it from the **Viewings** section of the enquiry. Open the overflow menu (•••) next to the viewing and choose: * **Mark completed**: The lead attended. Yorlet follows up with them and reminds you to move them on to an application when they are ready. * **Mark no show**: The lead did not attend. * **Cancel viewing**: The viewing is called off and the slot is freed up for another lead. You can also choose **Update** to change the time, host, or notes. Moving a viewing to a new time sends the lead an updated confirmation. ## What the lead receives Yorlet keeps the lead informed without you having to chase: * A request-received email when a building-link booking needs confirmation, with a link they can use to change or cancel the request. * A confirmation email as soon as the viewing is booked, confirmed, or moved, with a calendar invite they can add to their diary. * A reminder 24 hours before the viewing. * A follow-up email after the viewing has finished. If the viewing has finished and nobody has recorded an outcome, the host is nudged to do so. ## Booking settings Your booking rules apply across every viewing, and control which slots leads can choose from. Weekly hours can be overridden on a building; duration, notice, and the booking window always come from the account. To change the defaults, go to [Viewing settings](https://dashboard.yorlet.com/settings/viewings): * **Availability**: The default weekly times your team can host viewings. A building can use its own hours instead. * **Viewing duration**: How long each viewing lasts, in minutes. Slots are offered at this interval. * **Buffer between viewings**: Travel or turnaround time kept free either side of a booked viewing, in minutes. * **Minimum notice**: How far in advance a lead must book, in hours. * **Booking window**: How far into the future leads can book, in days. * **Send booking links automatically**: Email the lead their booking link as soon as an enquiry is marked as qualified. * **Require confirmation for building booking links**: Bookings from a public building link start as pending until a team member confirms them. A building can override this. Click **Save** once you are happy with your changes. Leads picking a slot from a booking link can only choose from the published hours for that building — or your account hours if the building inherits them. If those hours are empty, they will have no times to choose from and you will need to book their viewings yourself. # Leasing Source: https://docs.yorlet.com/leasing Take an applicant from application through to an active tenancy, then renew or end the lease. Leasing is how you onboard new tenants and manage the tenancy afterwards. An application collects details, references, deposits, and signatures. When it completes, Yorlet creates the tenancy and the billing that goes with it. From there you can review the tenancy, make a lease change, or start a renewal. ## How leasing progresses 1. Create an [application](/leasing/applications) for a unit, or send the applicant a link to complete it themselves. 2. Collect [references](/leasing/referencing) and, if you need them, add [guarantors](/leasing/guarantors). 3. Create and [register a deposit](/leasing/deposits) with your protection scheme. 4. When the application completes, a [tenancy](/leasing/tenancies) starts and rent is billed on the [subscription](/billing/subscriptions). 5. Before the lease ends, start a [renewal](/leasing/renewals) or make a [lease change](/leasing/tenancies/lease-changes). ## Get started Configure, create, and manage applications Request and track tenant references Create, register, charge, and return deposits Add guarantors to secure a tenancy Manage move-ins, move-outs, and changes to ongoing tenancies Track upcoming ends of term and automate the renewal process # Get started Source: https://docs.yorlet.com/leasing/applications Learn how to onboard new tenants. Yorlet Leasing helps you easily create and manage rental applications, taking care of all tenant onboarding essentials. This includes compliance checks, referencing, and collecting payments. You can also securely e-sign contracts and manage rent collection methods. Every new application runs on an [application configuration](/leasing/applications/application-configurations): a reusable, step-by-step journey you design once and reuse. Build the configuration first, then select it when you create an application and Yorlet guides each applicant through your steps. ## Get started with Leasing Build reusable, step-by-step onboarding flows Learn how to create a rental application Learn how to manage a rental application Learn how to update a rental application Change an applicant's share of rent, requirements, and details Discover how your customers progress through the application journey # Application configurations Source: https://docs.yorlet.com/leasing/applications/application-configurations Build reusable, step-by-step onboarding flows for your applications. Application configurations let you design your own onboarding journey once and reuse it across applications. Instead of following a fixed sequence, you build a flow from the exact steps your tenancies require — referencing, payments, contracts, and more — and Yorlet guides each applicant through it automatically. This is ideal when different portfolios, sectors, or landlords need different onboarding requirements. Every new application runs on a configuration, so you need at least one published configuration before you can create an application. ## Building a configuration To create a configuration, navigate to [Application configurations](https://dashboard.yorlet.com/application-configurations) and click **New configuration**. Give your configuration a name, then build the flow using the visual builder. Every flow begins with a **Start** node and ends with a **Completion** node. To add a step, click the add (+) button beneath a node and choose a step type. Steps run from top to bottom in the order they appear. You can reorder a step using **Move up** and **Move down**, or remove it with **Remove**. Select any step to edit its settings in the panel on the right. When you are happy with the flow, you can either: * **Save draft**: Save your progress without making the configuration available for use. Draft configurations are labelled `Draft`. * **Publish**: Make the configuration available to use on new applications. Published configurations are labelled `Active`. ## Managing configurations Open a configuration from the [Application configurations](https://dashboard.yorlet.com/application-configurations) page to see its steps and every application that uses it. From here you can: * **Edit flow**: Reopen the builder to change the name, steps, or step settings. * **Deactivate**: Stop the configuration being offered on new applications. Applications already using it are unaffected. * **Activate**: Make a draft or deactivated configuration available again. Each application keeps a copy of the steps as they were when it was created. Editing or deactivating a configuration never changes an application that is already in progress, so you can safely improve your flow while onboarding is under way. ## Step types Steps are grouped into three categories. ### Core * **Pre-qualification**: Collect and assess applicant details, such as affordability and eligibility, before the application progresses. * **Referencing**: Require a tenant reference. You can have the reference created automatically with one of your integrated [referencing](/leasing/referencing) providers. * **Verification**: Run an identity verification check on the applicant. * **Network check**: Look up what other accounts have reported for each applicant. Anything found is shown as a risk signal on the customer. Place this step after **Verification** so the check runs against a verified identity. * **Contract**: Generate and collect a signed tenancy contract. * **Completion**: The final step. Every flow ends here, and it controls what happens once onboarding finishes. **Network check** requires a Guardrails plan, and each applicant checked counts as one billable check. A check stays valid for twelve months, so checking the same person again within that time is not charged. ### Payments * **Holding fee**: Collect a holding deposit to secure the tenancy. * **Deposit**: Collect the security deposit. Once it is paid, Yorlet creates a [Deposit](/leasing/deposits) record for you to register with a protection scheme. * **Advance rent**: Collect the move-in payment. * **Partial payment**: Collect a portion of the rent upfront as a credit towards future invoices. * **Payment method**: Set up rent collection, either **Charge automatically** or **Send invoice**. ### Tools * **Branching**: Split the flow based on conditions. * **Waitpoint**: Pause the flow until you are ready to continue. Give each waitpoint a descriptive name so it is easy to identify. **Waitpoint** is the only step that can be used more than once in a flow. Every other step type can be added once, and every flow ends with a single **Completion** step. ## Step settings Select a step to configure it. The available settings depend on the step type. ### Completion * **Completion behaviour**: **Automatic** completes the application as soon as this step is reached. **Manual** requires you to approve completion. * **Tenancy behaviour**: **Roll periodically** keeps the tenancy running after the initial term ends, and **Complete** ends it at the end of the term. * **Credit note**: How to credit the previous tenancy when the application is a [revision](/leasing/applications/create-an-application#revising-a-tenancy). Choose **No credit note**, **Credit outside of Yorlet**, or **Credit to customer balance**. ### Contract * **Allowed contract templates**: Restrict which contract templates can be used at this step. Leave this empty to allow all of them. * **Owner signature required**: Require the owner's signature when the contract is signed. * **Owner email notification**: Email the owner once the contract has been signed. * **Break clause**: Pre-fill the break clause terms for contracts generated at this step. ### Referencing * **Automatic referencing**: Enable to create references automatically when the application reaches this step. * **Provider**: The referencing provider to use for automatic checks — Let Alliance, Homelet, Canopy, or Advance Rent. ### Payment method * **Rent collection method**: **Charge automatically** collects a rent payment method and charges invoices automatically. **Send invoice** sends invoices to your customers for manual payment. ### Waitpoint * **Waitpoint name**: A descriptive name so you can identify this pause in the flow. The name is shown as the application's status while it is waiting. ## Using a configuration on an application When you create an application, you select a published configuration first — the rest of the form appears once you have chosen one. Several of the configuration's settings then pre-fill the application, including the contract template, owner signature options, rent collection method, and end of tenancy behaviour. See [Create an application](/leasing/applications/create-an-application). Once the application is live, it moves through your steps as your customers complete them, and you can move it along manually with the **Progress** action. See [Manage an application](/leasing/applications/manage-an-application) for progressing, skipping, and reverting steps. # Application Portal Source: https://docs.yorlet.com/leasing/applications/application-portal Discover how your customers progress through the application journey. The Application Portal serves as a guide for your customers, leading them through your onboarding process, handling legal details, payments, and contracts. Branded with your business identity, the portal provides essential information such as your contact details, a preview of the rental contract, and compliance information. ## The customer journey Each applicant gets their own portal link, and what they see follows the steps in the application's [configuration](/leasing/applications/application-configurations). * A **Summary** at the top shows the contract dates, their share of the rent, a preview of the rental contract, and the unit's compliance documents. * Below it, the portal lists the steps they need to complete, each marked `Todo` or `Done`. Applicants work through them in order, and a step only opens once the one before it is finished. * **Personal details** and **Guarantor details** are added to the list when you need them, alongside the steps from your configuration. * Steps handled outside the portal, such as referencing, show as in progress until the provider reports back. * When the application reaches a waitpoint, the portal explains that the step needs action from the property manager and that the applicant will be notified when they can continue. * Once onboarding finishes, the portal confirms that the application is complete. ## Sending a portal link Your customers are automatically emailed an onboarding link when the application is created. You can send a fresh link at any point: 1. Open the application and find the applicant. 2. Click **Send link**. 3. Turn on **Send email** to email the link to the applicant, then click **Create**. 4. Copy the link from the dialog if you would rather share it yourself. When you move an application off a waitpoint, turn on **Email applicants** in the **Progress** dialog to email a link to everyone who has something to do on the next step. See [Manage an application](/leasing/applications/manage-an-application#progressing-an-application). ## Portal settings To customise the portal, navigate to Settings > Leasing > [Application portal](https://dashboard.yorlet.com/settings/application-portal): * **Links**: Add your **Terms of Service**, **Privacy Policy**, and **Pre-application terms**. Pre-application terms can be a link or an uploaded file, and are presented to the customer before they begin the application process. * **Customer**: Turn on **Enable customer address collection** to collect your customer's address during the pre-application flow. * **Terms of service**: Turn on **Disable special requests** to remove the special requests section from the customer acceptance page. * **Custom text**: Change the terminology used for the **Holding deposit**, and the message customers see while their application is **Pending acceptance**. Your logo, colours, and contact details come from your [branding settings](/account/branding). # Create a new application Source: https://docs.yorlet.com/leasing/applications/create-an-application Learn how to create a rental application. Our application process is fully customisable, allowing you to effortlessly tailor each journey to the exact requirements of your customers and landlords. Whether you’re dealing with tenancies in the PRS, BTR, PBSA, or co-living sectors, Yorlet Leasing can adapt to a variety of tenancy types, providing your team with a reliable and repeatable process. Each application runs on an [application configuration](/leasing/applications/application-configurations), so make sure you have published at least one before you start. ## Create a rental application To create an application, navigate to [Applications](https://dashboard.yorlet.com/applications) and click **New application**, then follow these steps: 1. Choose an **Application configuration**. The rest of the form appears once you have selected one. 2. Choose an application type: * **Standard**: Full application and rent payments setup. * **Renewal**: Renewal application and rent payments setup. * **Let only**: Full application with no rent payments setup. * **Active tenancy**: Add an existing tenancy where payments and contracts have already been handled. 3. Select a building and unit. The form shows the unit's [availability](/real-estate/units#availability) so you can release it if it is not yet on the market. Ensure your compliance documents, such as the **Energy Performance Certificate**, **Electric Safety Certificate**, and **Gas Safety Certificate**, are uploaded and up to date. 4. If the unit has an owner, choose whether to **Auto apply unit fees** to this application. 5. Add your applicants. You only need a customer’s email address to get started — legal and contact details can be self-served by the customer within the [Application Portal](/leasing/applications/application-portal). 6. Set the **Schedule**: the start and end dates and the billing interval for rent collection (for example monthly, quarterly, or custom). Press **Save** on the schedule to continue with the rest of the form. 7. Review rental **Pricing**, and add any **Invoice items** that should appear on the first invoice only. 8. Optionally **Overwrite contract dates** if your customers move in or out on different days to the contract dates, and set the **End of tenancy behaviour**. 9. Calculate the application **Payments**, including the **Holding deposit**, **Move-in payment**, and **Deposit**, and choose a **Rent collection method**. 10. Select a **Contract template** and set your signing preferences. 11. Optionally set an **Assignee** and **Deal assignee**, then click **Create**. Once you have completed this process, your customers will be automatically emailed an onboarding link giving them access to the Application Portal. You can always resend this link or generate a fresh one at any point from the application summary page. ### Unit availability For a **Standard** or **Let only** application, the unit you pick must be lettable. After you select a unit, the form shows its letting state — **To let**, **Coming available**, **Vacant**, or **Held** — and the **Available from** date. A unit that is **To let** is already on the market. For a unit that is not, you can release it from this form: 1. Click **Release** to list it now. You can set **Available from** and the advertised rent, the same as releasing from the [unit](/real-estate/units#release-a-unit-to-the-market). 2. Or turn on **Release when creating this application** to list it when you click **Create**. This is on by default for **Coming available** units. Occupied units that have not been released cannot be used for a new letting until you release them. **Renewal**, **Active tenancy**, and revision applications skip this check — they act on a tenancy already in the unit. Releasing an occupied unit does not end the current tenancy. It only lists the unit so you can market it before the tenant moves out. ### Settings taken from the configuration Selecting a configuration pre-fills parts of the form so your journeys stay consistent. Depending on the steps in your flow, this includes: * The **Contract template**, restricted to the templates allowed by the contract step. * The **Owner signature** and **Owner email notification** options. * The **Rent collection method**. * The **End of tenancy behaviour**. You can still change these values on the application before you create it. ## Application payments Depending on your rental application setup, customers may be prompted to make several payments in the Application Portal to secure the tenancy. You can easily configure these payments using the **Calculate payments** button during application creation. The default calculation is as follows, but you have the flexibility to customise these values: * **Holding deposit (one week’s rent):** This payment represents a small commitment towards the tenancy. It is collected after the customer provides their legal information and agrees to your terms and conditions, privacy policy, and pre-application terms. The holding deposit adds a credit to your customer’s balance. * **Move-in payment (three weeks’ rent):** A larger upfront payment towards the rent, which can be collected before or after the contract is signed. * **Deposit (five weeks’ rent):** The security deposit, collected before the contract is generated. When each payment is requested is determined by your [application configuration](/leasing/applications/application-configurations). A payment is only collected if your flow includes the matching step, and the steps run in the order you designed them. It’s important to note that the holding deposit and move-in payment contribute as a credit towards the rental contract. You can leverage this by using the move-in payment to facilitate a large upfront financial commitment. For example, if you collect rent monthly but require a 6-month upfront commitment, setting the move-in payment to 6 months applies a credit to your customer’s account. They won’t be billed until the sixth month of their tenancy, at which point monthly billing will commence. Turn on **Reserve move-in credits for the application** to keep the holding deposit and move-in payment for this application’s own invoices, rather than applying them to the customer’s next invoice. The default comes from Settings > Leasing > [Payments](https://dashboard.yorlet.com/settings/leasing-payments). ### Partial payments When creating an application, you can turn on **Enable partial payments** to collect a portion of the rent upfront. The partial payment generates a credit grant that is applied to the customer’s future invoices. Enter the total pre-tax **Amount** and an optional **Description**. ## Share of rent For tenancies with more than one applicant, you can control how the rent is split between them as you add each applicant to the form. For each applicant, you can: * Set their **Share of rent** as a percentage. The combined share of all applicants must total 100%. * Mark an applicant as the **Lead tenant**. * Mark an applicant as a **Permitted occupier** — permitted occupiers do not contribute to the rent. * Toggle **Require guarantor** if that applicant needs a [guarantor](/leasing/guarantors). By default the lead tenant carries the full rent, and **Split rent equally** divides it evenly across the other applicants. If you have turned on **Split share equally between tenants** in Settings > Leasing, this is reversed: the rent is split evenly by default, and **Assign 100% to lead tenant** puts it back on the lead tenant. You can change the split after the application has been created — see [Update an applicant](/leasing/applications/update-an-applicant#share-of-rent). ## Revising a tenancy If the terms of a pending or active tenancy need to change more substantially than a [lease change](/leasing/tenancies/lease-changes) allows, you can create a revision. A revision is a new application that replaces the existing tenancy once it completes. To create a revision, follow these steps: 1. Open the tenancy, click the overflow menu (•••), and select **Create revision**. 2. Choose how to **Credit note the previous tenancy**: * **No credit note**: Do not issue a credit note for the previous tenancy. * **Credit outside of Yorlet**: Record a credit note that is handled outside of Yorlet. * **Credit to customer balance**: Apply the credit note to the customer’s balance for future invoices. 3. Complete the rest of the form as you would for a new application, then click **Create**. The revision runs through its configuration like any other application. When it completes, the original tenancy is cancelled and replaced by the new one. ## Compliance Yorlet ensures compliance at every step by addressing the following requirements: * **Energy Performance Certificate, Electric Safety Certificate, and Gas Safety Certificate:** Before creating an application, Yorlet verifies the addition and validity of all compliance documents. These documents are presented clearly to customers at each stage of the application portal. You can manage the validity of your essential documents by navigating to Reports > Compliance. * **Pre-application terms, Terms and Conditions, and Privacy Policies:** Customers must accept your legal terms before making a holding deposit. The pre-application terms (also known as Reservation fee terms) are particularly important. You can add these terms to your account by navigating to Settings > Leasing > [Application portal](https://dashboard.yorlet.com/settings/application-portal). * **Renter’s Handbook:** For UK based applications, before signing the rental contract, customers are provided with a link to the Renter’s Handbook and have the option to download a PDF copy. ## Guarantors For certain applications, you may require a guarantor to mitigate risk. Adding a guarantor is simple: after creating an application, navigate to the application page, and access the overflow menu (•••) related to the applicant. From there, select **Add guarantor**. ## Payment Sessions If you need to collect an ad hoc payment for a holding deposit, move-in payment, or deposit, you can utilise [Payment Sessions](/payments/payment-sessions). This feature may come in handy if you accidentally forget to calculate an application payment or require further payment from your customer. # Manage an application Source: https://docs.yorlet.com/leasing/applications/manage-an-application Learn how to manage a rental application. An application moves through the steps in its [application configuration](/leasing/applications/application-configurations) as your customers complete them. Most of the time it progresses on its own — this page covers the moments where your team needs to step in. ## Progressing an application To move an application along yourself, open it and click **Progress**. Depending on the current step, you can: * **Progress** the application to the next step. * **Skip current step** to move straight past the current step. This is not available on a waitpoint or on the completion step. * **Complete** the application once it reaches the completion step. Completing an application creates the tenancy. When the application is sitting on a waitpoint, the dialog also offers **Email applicants**. This is on by default and emails a link to any applicant who has something to do on the next step, such as making a payment, providing more information, or verifying their identity. If your configuration's completion step uses the **Automatic** behaviour, the application completes on its own as soon as it reaches that step. Use **Manual** when you want to review the application before the tenancy is created. ## Reviewing steps The **Steps** section on the application page lists every step in the configuration alongside its status: * `Pending`: The step has not been completed yet. * `Complete`: The step's requirements have been met. * `Skipped`: You moved the application past this step. Waitpoints are shown using the name you gave them in the configuration, so it is clear what the application is waiting for. ## Reverting a step If you skip a step by mistake, or your customer's circumstances change, you can bring it back. Steps that can be reverted show a **Revert** action in the **Steps** section. To revert a step, follow these steps: 1. Open the application and find the step in the **Steps** section. 2. Click **Revert** next to the step. 3. Confirm by clicking **Revert** in the dialog. The application rolls back to that step and re-enters it, so it can be completed again. Reverting only affects the step you choose — every other step keeps its current status. You can revert: * Any step you have `Skipped`. * A completed **Holding fee**, **Deposit**, or **Advance rent** step whose payments are no longer fully covered, so the outstanding amount can be collected again. This is useful when you increase one of these payments after it has already been paid. Reverting is only available while the application is still open. You cannot revert a step on a completed or cancelled application. ## Managing applicants Each applicant card on the application page has its own actions: * **Send link**: Create a fresh link to the [Application Portal](/leasing/applications/application-portal). Turn on **Send email** to email it to the applicant, or copy the link and share it yourself. * **Edit customer**: Change the customer record behind the applicant, such as their legal name and contact details. * **Update applicant**: Change the applicant's requirements, pre-qualification details, and pets. See [Update an applicant](/leasing/applications/update-an-applicant). * **Create reference**: Start a [reference](/leasing/referencing) for the applicant. * **Add guarantor**: Add a [guarantor](/leasing/guarantors) where one is required. * **Mark paid**: Record a payment taken outside of Yorlet. This appears while the application is on a **Holding fee**, **Deposit**, or **Advance rent** step, and satisfies that payment for the applicant. ## Cancelling an application Once you have created an application, you have the ability to cancel it at any time. To cancel an application, click on the overflow menu (•••) and select **Cancel**. If you only need to change the unit, dates, pricing, or contract template after the contract has been generated, cancel the contract instead of the application. See [Update an application](/leasing/applications/updating-applications#updating-after-the-contract-has-been-generated). If you have collected application payments, you will need to decide whether to refund the customer their holding deposit, move-in payment, and deposit payment. Additionally, you will be required to specify a **Reason** for the cancellation. When dealing with a holding deposit related to the cancellation of an application, you will be prompted to choose from the following options: * **Refund payment**: The holding deposit will be refunded to the customer. * **Recognize revenue**: The holding deposit will be converted to revenue for your business. When handling a move-in payment and/or deposit payment in relation to the cancellation of an application, you will be asked to choose from the following options: * **No action**: No action will be taken with the payment. * **Refund payment**: The payment will be refunded to the customer. Please exercise caution when cancelling an application, as this action cannot be undone. Applications created before application configurations were introduced follow a fixed sequence instead of your own steps. Those applications are moved along with **Accept** rather than **Progress**: you accept the application once the holding deposit has been paid, and countersign once the customer has signed the contract. # Update an applicant Source: https://docs.yorlet.com/leasing/applications/update-an-applicant Change an applicant's share of rent, requirements, and details after an application has been created. Applicants are managed from the application page. Each applicant has their own card showing their details, payments, and requirements, and each card has its own actions — so you can change one applicant without affecting the others or the application itself. ## Share of rent The share of rent decides how much of the rent each applicant is responsible for. It is set when you [create the application](/leasing/applications/create-an-application), and you can change it afterwards — for example, moving a tenancy from one applicant paying 100% to two applicants paying 50% each. To change the share of rent, open the application, click the overflow menu (•••), and select **Edit share of rent**. You can also reach the same form from the **Edit** link next to **Share of rent** on an applicant's card, or from the **Share of rent** section of the **Update** form. For each applicant you can: * Set their **Share of rent** as a percentage. The combined share of all applicants must total 100% before you can save. * Mark them as the **Lead tenant**. Only one applicant can be the lead tenant, so turn it off for the current lead before assigning it to somebody else. * Mark them as a **Permitted occupier**. Permitted occupiers live in the property but do not contribute to the rent, so their share is fixed at 0%. * Toggle **Require guarantor** if that applicant needs a [guarantor](/leasing/guarantors). Use **Split equally** to divide the rent evenly between everyone who is not a permitted occupier. This is the quickest way to move from 100% on the lead tenant to an even split. New applicants default to the lead tenant carrying the full rent. To make an even split the default instead, turn on **Split share equally between tenants** in Settings > Leasing. ### When you can change the share of rent You can change the share of rent while the application is open, up until the contract has been generated. Once the contract exists, the split is fixed for the tenancy. The share of rent also cannot be changed while a partial payment is configured on the application, because a partial payment is collected from a single applicant. Remove the partial payment from the **Update** form first, then change the share. Changing the share does not redistribute money that has already been collected. If an applicant has already paid their holding deposit, move-in payment, or deposit, you will be shown a warning and an **Adjust balance** action for each affected applicant, so you can correct their customer balance to reflect the new split. ## Update an applicant's details To change an applicant's requirements or the information they have given you, open the overflow menu (•••) on their card and select **Update applicant**. From here you can set: * **Require guarantor**: When enabled, the applicant must submit guarantor details during their application. Once a guarantor has been added this can no longer be turned off — [remove the guarantor](/leasing/guarantors/manage-a-guarantor) first. * **Pre-qualification**: The applicant's **Nationality**, and their **Company name**, **Role**, and **Gross annual salary** for affordability. Your customers can provide these themselves in the [Application Portal](/leasing/applications/application-portal), so use this to correct or complete what they have submitted. * **Pets**: Click **Add pet** to record an animal, then set its **Type**, and optionally its **Name** and **Age**. Remove a pet with the bin icon. ## What each applicant card shows Alongside the actions, an applicant's card summarises where they have got to: * **Customer**, **Legal name**, and **Phone**: The customer record behind the applicant. Use **Edit customer** from the overflow menu (•••) to change these. * **Share of rent** and **Guarantor**: Their share, and whether a guarantor is required, added, or not needed. * **Pre-qualification**: Click **View** to see the nationality and affordability details they submitted. * **ToS** and **Rent method**: Whether they have accepted your terms and provided a payment method for rent. * **Holding deposit**, **Deposit**, and **Move-in payment**: Whether each payment is required and whether it has been paid. * **Pets**: Any animals recorded against the applicant. While the application is open you can also expand **Customer balance** to review the applicant's balance transactions and click **Adjust balance** to correct it. Changing an applicant's details does not move the application forward. See [Manage an application](/leasing/applications/manage-an-application) for progressing, skipping, and reverting steps. # Update an application Source: https://docs.yorlet.com/leasing/applications/updating-applications Make effective changes to your rental applications without compromising progress. Once you have created a rental application, you may find the need to amend or modify certain terms. Open the application and click **Update** to make changes to the following: * Building and unit. * Payment schedule: adjust the start and end dates, as well as the billing interval for rent collection (for example monthly, quarterly, or custom). * Rental pricing and invoice line items. * Application payments, including the holding deposit, move-in payment, and deposit. * Rent collection method: toggle between **Charge automatically** or **Send invoice**. * Contract template, signing options, and break clauses. * Assignee and deal assignee. The **Update** form also shows a **Share of rent** summary for each applicant. Changing the split is done in its own form — see [Update an applicant](/leasing/applications/update-an-applicant#share-of-rent). ## What you can change, and when Your application configuration determines how long each field stays editable, because Yorlet only lets you change something the application has not already passed: * **Unit, schedule, pricing, and contract template** can be changed until the contract has been generated. After that, **Update** is hidden until you [cancel the contract](#updating-after-the-contract-has-been-generated). * **Holding deposit**, **Move-in payment**, **Deposit**, and **Partial payment** amounts can be changed until the application moves past the matching step. If you increase a payment after your customer has already paid it, [revert](/leasing/applications/manage-an-application#reverting-a-step) that step so the application re-enters it and the outstanding amount can be collected. ## Contracts You can preview the contract from the overflow menu (•••) at any time. **Edit contract** is only available before the contract has been generated, because your edits are applied at the point of generation. Take care when editing: changes apply to this application only and are shown to your customer in the Application Portal. Once the contract has been generated, you cannot change the unit, dates, pricing, or contract template, and **Update** is no longer shown on the application. ### Updating after the contract has been generated To change those details after the contract is out for signature, cancel the contract first. Cancelling clears it from the application, returns the application to waiting for a contract, and brings **Update** back. To cancel the contract and update the application, follow these steps: 1. Open the application and click the contract in the **Contracts** table. 2. Click **Cancel contract**. Confirm in the dialog — this cannot be undone. 3. Return to the application. **Update** is shown again. 4. Click **Update**, make your changes, then click **Update**. 5. Click **Generate contract** to create a new contract with the updated terms. **Cancel contract** is only available while the contract is still out for signature, including after some people have signed. Once everyone has signed, the contract is complete and cannot be cancelled. Voiding a completed contract does not restore **Update**. # Deposits Source: https://docs.yorlet.com/leasing/deposits Collect, protect, charge, and return tenant deposits. A deposit is the security money you collect from a tenant and, in the UK, protect with a government-approved scheme. Yorlet tracks every deposit from the moment it is paid through to return, including scheme registration, custodial transfers, deductions, and payouts to owners. You can view and manage deposits from the [Deposits page](https://dashboard.yorlet.com/deposits). Pending deposits also appear under **Leasing** in the sidebar so you can see which ones still need registering. ## How a deposit progresses 1. Collect the deposit as part of an [application](/leasing/applications). Yorlet creates a Deposit record once it is paid. See [Create a deposit](/leasing/deposits/create-a-deposit). 2. [Register the deposit](/leasing/deposits/register-a-deposit) with your protection scheme. You can do this yourself, or let Yorlet register it automatically with DPS or TDS. 3. For a UK custodial deposit, transfer the funds to the scheme and [mark it as transferred](/leasing/deposits/register-a-deposit#transferring-a-custodial-deposit). 4. While the deposit is active, [add charges](/leasing/deposits/deposit-charges) for arrears, dilapidations, or other deductions. 5. At the end of the tenancy, [return the deposit](/leasing/deposits/return-a-deposit). Outstanding charges are deducted, and the remainder goes back to the tenant. ## Deposit statuses A deposit moves through these statuses: * **Pending**: The deposit has been created but is not yet registered with a scheme. * **Active**: The deposit is protected and can have charges added. * **Disputed**: A charge on the deposit has been disputed. * **Pending return**: You have started the return. Return the remaining funds to the tenant, then mark the deposit as returned. * **Returned**: The deposit has been fully returned. No further charges can be added. UK deposits must be registered within 30 days of being paid. Pending deposits show a **Days to register** countdown, which turns orange in the last two weeks and red in the last seven days. ## Get started Collect a security deposit on an application Protect a deposit with DPS, TDS, or mydeposits Deduct arrears, dilapidations, and other charges Return the remaining balance at the end of the tenancy Send deposit funds to the right owner accounts # Create a deposit Source: https://docs.yorlet.com/leasing/deposits/create-a-deposit Learn how deposits are created from an application. Yorlet creates a Deposit record when the security deposit on an [application](/leasing/applications) is paid. Each application can have one deposit. You do not create deposits from the Deposits page — they are created as part of onboarding. ## Collect the deposit on an application To collect a deposit, follow these steps: 1. Include a **Deposit** step in your [application configuration](/leasing/applications/application-configurations). 2. When you [create the application](/leasing/applications/create-an-application), set the **Deposit** amount. The default is five weeks’ rent, and you can change it. 3. The applicant pays the deposit in the [Application Portal](/leasing/applications/application-portal) when they reach that step. Once the payment succeeds, Yorlet creates a Deposit in **Pending** status. It is linked to the application, the unit, and the applicants, and appears on the [Deposits page](https://dashboard.yorlet.com/deposits). If you collected the deposit outside Yorlet, open the application and use **Mark paid** on the applicant while the application is on the **Deposit** step. That also creates the Deposit record. For UK deposits, the 30-day registration deadline starts when the deposit is paid. ## After the deposit is created A pending deposit still needs to be [registered with a protection scheme](/leasing/deposits/register-a-deposit). Until then it stays in the **Pending** tab on the Deposits page. If automatic registration is enabled and succeeds as soon as the deposit is created, the record can move straight to **Active**. Otherwise, open the deposit and click **Activate**. You can assign a team member, [edit](/leasing/deposits/register-a-deposit#editing-a-deposit) the amount or description, or delete a pending deposit from the overflow menu (•••) if it was created in error. You can only delete a deposit while it is **Pending**. Once it is active, it must be returned rather than deleted. # Adding charges to a deposit Source: https://docs.yorlet.com/leasing/deposits/deposit-charges Learn how to add charges to a deposit. While a deposit is **Active**, you can add charges to deduct funds from it. Once you have finalised the charges, [return the deposit](/leasing/deposits/return-a-deposit) to the tenant. Each charge has a type: * **Arrears** * **Charge** * **Dilapidation** * **Other** Charges appear in the **Charges** table on the deposit record. For each charge, the table shows the **Amount**, **Status**, **Type**, **Description**, and **Destination**. The destination is the [owner](/leasing/deposits/deposit-routing) the charged funds are allocated to when the deposit is returned. The returnable amount is the original deposit minus accepted charges. A charge cannot be more than the remaining deposit after existing charges. ## Add a charge To add a charge, follow these steps: 1. Open the deposit and click **Add charge**. If charges already exist, this is labelled **Add another charge**. 2. Choose a **Type**. 3. Enter the **Charge amount** and a **Description**. 4. For a UK insured deposit, optionally choose a **Destination** owner. If you leave this empty, the charged amount is split across the unit’s owners when you return the deposit. 5. Click **Create**. New charges are accepted immediately and reduce the returnable balance. ## Managing charges From the **Charges** table, open the overflow menu (•••) on a charge to: * **Edit** the charge’s description. * **Cancel** the charge. A cancelled charge no longer reduces the returnable deposit. You cannot add charges after the deposit has been returned. # Deposit routing Source: https://docs.yorlet.com/leasing/deposits/deposit-routing Learn how deposit funds are transferred to owner accounts. Deposit routing controls where deposit money goes when you activate or return a deposit with **Automatic transfers** turned on. Use it to send custodial deposits to a scheme, keep insured deposits in your own account, or pass funds to the unit’s owners. To turn routing on, go to Settings > Owners > [Routing](https://dashboard.yorlet.com/settings/owners/routing) and enable **Deposit routing**. ## Destinations Once deposit routing is enabled, choose where funds should go: * **Default**: Used when the deposit has no scheme-specific destination, including deposits outside the UK. * **Custodial schemes (UK deposits)**: Set a separate owner for DPS, mydeposits, and TDS. These are typically [supplier](/owners/accounts) owner accounts for each scheme. If a scheme destination is not set, Yorlet uses the default destination, or your [platform owner account](/owners/platform-accounts) if no default is set. ## When funds move Automatic transfers only run when you turn on **Automatic transfers** in the activate or return dialog. ### On activation What happens depends on the scheme and whether the deposit is handled by the owner: * **Insured (UK)**: No transfer. You keep the deposit in your own account or client account, as the scheme insures it rather than holding it. * **Custodial (UK)**: The deposit is transferred to the matching scheme destination so you can send it on to the protection scheme. * **Handled by owner**: The deposit is split across the unit’s [owners](/owners/unit-ownership) according to each owner’s percentage ownership, instead of using the routing destinations above. * **Outside the UK**: The deposit is transferred to the default destination. Insured UK deposits do not need an external transfer to a scheme. Custodial UK deposits do — see [Transferring a custodial deposit](/leasing/deposits/register-a-deposit#transferring-a-custodial-deposit). ### On return When you [return a deposit](/leasing/deposits/return-a-deposit) with **Automatic transfers** on, Yorlet transfers accepted [charges](/leasing/deposits/deposit-charges) to their destination owners. This only applies to UK insured deposits. If a charge has a destination, that owner receives the charged amount. If it does not, the amount is split across the unit’s owners according to each owner’s percentage ownership. The remaining balance is what you return to the tenant. Custodial deposits are held by the scheme, so Yorlet does not create owner transfers when you return them. The scheme handles paying the tenant. # Registering a deposit Source: https://docs.yorlet.com/leasing/deposits/register-a-deposit Learn how to register a deposit with a protection scheme. In the UK you have 30 days from when the deposit is paid to register it with a protection scheme. Until it is registered, the [Deposits page](https://dashboard.yorlet.com/deposits) shows a **Days to register** countdown. The reminder turns orange in the last two weeks and red if you miss the deadline. Pending deposits appear in the **Pending** tab on the [Deposits page](https://dashboard.yorlet.com/deposits). ## Register a deposit To register a pending deposit, follow these steps: 1. Open the deposit from the [Deposits page](https://dashboard.yorlet.com/deposits). 2. Click **Activate**. 3. Confirm the **Amount**. 4. For a UK deposit, choose a **Scheme** and **Scheme type**. 5. Either register it automatically, or enter the details from the scheme yourself. 6. Set any additional options, then click **Activate**. The schemes you can choose from are the ones you have enabled in Settings > Leasing > [Deposits](https://dashboard.yorlet.com/settings/deposits): * Deposit Protection Scheme (DPS) * Tenancy Deposit Scheme (TDS) * mydeposits When registering, you also choose the type of deposit: * **Insured**: You retain the deposit in your own account or a designated client account. The scheme insures it, and you are responsible for returning it to the tenant at the end of the tenancy. * **Custodial**: You transfer the deposit to the scheme for safekeeping. The scheme holds the money and handles the return at the end of the tenancy. ### Register manually If you have already registered the deposit with the scheme, enter the **Scheme registration number** and upload the **Certificate**. You need a registration number before you can upload a certificate. ### Register automatically For DPS custodial and TDS insured deposits, you can turn on **Register deposit automatically**. Yorlet registers the deposit with the scheme and retrieves the registration number and certificate, so you do not enter them twice. Automatic registration is only available when the matching integration is connected. If it is not, the activate dialog links you to [deposit settings](https://dashboard.yorlet.com/settings/deposits) to set it up. For TDS, you also choose a **Branch**. The default comes from your TDS integration settings. If automatic registration fails, the error is shown on the deposit. You can open **Activate** again to retry or to register the deposit manually. ### Additional options When activating, you can also set: * **Handled by owner**: The deposit was transferred to the owner to handle registration. Automatic transfers then go to the unit’s owners rather than your routing destinations. See [Deposit routing](/leasing/deposits/deposit-routing). * **Send email to customer**: Email the customer that the deposit has been registered, including the scheme and registration number. The certificate is attached when one is available. * **Automatic transfers**: Initiate transfers based on your [deposit routing](/leasing/deposits/deposit-routing) settings. Once activation succeeds, the deposit is labelled **Active**. Scheme provider, type, and registration number cannot be changed after that. Deposits outside the UK do not need a protection scheme. You can activate them once the amount is greater than zero. ## Transferring a custodial deposit UK custodial deposits must be transferred to the protection scheme to stay compliant. After the deposit is active, click **Mark as transferred** and select the date it was **Transferred on**. The date defaults to today. The deposit record also shows a reminder until this is done. ## Editing a deposit To update a deposit, click **Edit**. You can change the **Amount**, **Description**, and whether it is **Handled externally**. You can also upload a replacement certificate from the deposit record. You cannot change the amount once charges or a return have been recorded, and you cannot change the scheme provider, type, or registration number on an active deposit. ## Automatic deposit registration Yorlet can register deposits directly with DPS (custodial) and TDS (insured). Connect each integration in Settings > Leasing > [Deposits](https://dashboard.yorlet.com/settings/deposits). #### Connecting DPS Create a DPS account first. Then go to deposit settings, find **DPS**, and click **Setup**. You will need your **Member ID**, **Client ID**, and **Client secret**. You may have to contact DPS support to get these credentials. #### How it works When activating a deposit, select DPS and **Custodial**, then turn on **Register deposit automatically**. Yorlet registers the deposit in your DPS account and retrieves the registration number and certificate. #### Connecting TDS Create a TDS account first. Then go to deposit settings, find **TDS Insured**, and click **Connect**. You will be redirected to TDS to log in and connect your account. After connecting, click **Edit** to add your **Member ID** and default **Branch**. When you activate a deposit with automatic registration, you can still choose a different branch. #### How it works When activating a deposit, select TDS and **Insured**, then turn on **Register deposit automatically** and choose a **Branch**. Yorlet registers the deposit in your TDS account and retrieves the registration number and certificate. If TDS has accepted the deposit but not yet created it, try activating again shortly. Once an integration is connected, you can also control automatic registration in deposit settings: * **Enable automatic deposit registration**: Automatic registration is on by default for new deposits. You can turn it off for a specific deposit when you activate it. * **Require approval before the automatic deposit is sent to the provider**: Adds a manual step before Yorlet sends the deposit to the scheme. You also choose which schemes appear when you activate a deposit by turning each provider on under **Deposit providers**. # Return a deposit Source: https://docs.yorlet.com/leasing/deposits/return-a-deposit Learn how to return a deposit at the end of a tenancy. At the end of a tenancy, after deductions have been agreed, return the remaining deposit to the tenant. Outstanding [charges](/leasing/deposits/deposit-charges) are deducted first. The remaining balance is what you pay back. The deposit must be **Active** to start a return. ## Start the return To start returning a deposit, follow these steps: 1. Open the deposit from the [Deposits page](https://dashboard.yorlet.com/deposits). 2. Click **Return**. 3. Optionally turn on **Automatic transfers** to send charged funds to owner accounts, based on your [deposit routing](/leasing/deposits/deposit-routing) settings. 4. Click **Return deposit**. The deposit moves to **Pending return**. This cannot be undone. Any accepted charges are deducted, and the remaining amount is recorded as the amount to return. Automatic transfers on return apply to UK insured deposits. Custodial deposits are held by the scheme, which pays the tenant. ## Mark the deposit as returned After you have paid the remaining balance to the tenant (or the scheme has), complete the record: 1. Click **Mark as returned**. 2. Choose the date it was **Returned on**. This defaults to today. 3. Click **Mark as returned**. The deposit status becomes **Returned**. No further charges can be added. This cannot be undone. # Guarantors Source: https://docs.yorlet.com/leasing/guarantors Create and manage guarantors to secure a tenancy. Sometimes a tenant needs a guarantor to secure a property. This is common when they are students, self-employed, or have a limited credit history. A guarantor agrees to cover the rent if the tenant cannot. Yorlet lets you add a guarantor to an application, collect their details, and have them securely e-sign a guarantor contract. Learn how to add a guarantor to an application Learn how to accept, contract, revert, and remove a guarantor # Create a guarantor Source: https://docs.yorlet.com/leasing/guarantors/create-a-guarantor Learn how to add a guarantor to an application. You add a guarantor to an individual applicant on an application. Once added, the guarantor provides their details and, where required, signs a guarantor contract. ## Add a guarantor To add a guarantor, follow these steps: 1. Open the application from the [Leasing Dashboard](https://dashboard.yorlet.com/applications). 2. On the relevant applicant, open the overflow menu (•••) and select **Add guarantor**. 3. Choose the **Guarantor type**: * **Individual**: Enter the guarantor's **First name** and **Last name**. * **Company**: Enter the **Company name** and **Company number**. 4. Add the guarantor's **Email**, **Phone**, and **Address**. 5. Click **Create**. The guarantor is added to the applicant and a guarantor record is created. You can view and manage it from the guarantor page. You only need the guarantor's email to get started — they can self-serve the rest of their details. You can also require a guarantor for an applicant when editing the [share of rent](/leasing/applications/create-an-application) on an application. ## What happens next Once a guarantor has been added, you can accept them, generate their contract, and have them sign it. See [Manage a guarantor](/leasing/guarantors/manage-a-guarantor) for the full workflow. # Manage a guarantor Source: https://docs.yorlet.com/leasing/guarantors/manage-a-guarantor Learn how to accept, contract, revert, and remove a guarantor. After a guarantor has been added to an application, you manage them from the guarantor page. From here you can review their details, accept them, generate their contract, revert them if they were completed without a contract, or remove them. ## Guarantor statuses A guarantor's status updates as they progress through onboarding: * **Pending approval**: The guarantor has provided their details and is awaiting your approval. * **Awaiting signature**: The guarantor's contract has been generated and is waiting to be signed. * **Accepted**: The guarantor has signed their contract. * **Complete**: The guarantor is complete and the application can progress. ## Accepting a guarantor When a guarantor is pending approval, you have two options from the guarantor page: * **Generate**: Accept the guarantor and generate their contract. Select a **guarantor contract template**, then choose whether to **Send contract to guarantor** — when enabled, the guarantor is emailed a link to review and sign. Once they have signed, the guarantor becomes `Accepted`. * **Complete**: Mark the guarantor as complete without generating a contract. Use this when no guarantor contract is required. This advances the application accordingly. If you later need a contract, you can [revert](#reverting-a-completed-guarantor) the guarantor. If you accepted a guarantor but chose not to send the contract immediately, you can produce it later using **Generate contract**. ## Reverting a completed guarantor If you marked a guarantor as complete without a contract and later need one, you can move them back to pending approval. **Revert** appears on the guarantor page when the guarantor is `Complete` and has no contract. It is not available if a contract already exists. To revert a guarantor, follow these steps: 1. Open the guarantor page. 2. Click **Revert**. 3. Confirm in the **Revert guarantor** dialog. This moves the guarantor back to **Pending approval** so you can generate a contract. 4. Click **Generate**, select a **guarantor contract template**, and continue as usual. After you revert, the guarantor is no longer complete. Generate and sign their contract before the application can treat them as finished. ## Editing a guarantor To update a guarantor's details, open the guarantor page and click the edit (pencil) icon. You can edit a guarantor up until their contract is pending signature, accepted, or complete. ## Removing a guarantor To remove a guarantor, open the guarantor page and click the remove (bin) icon, or use **Remove guarantor** from the applicant's overflow menu (•••) on the application. A guarantor can be removed at any point before they are complete. Removing a guarantor cannot be undone. If the guarantor was required for the applicant, you will need to add a new guarantor before the application can progress. # Referencing Source: https://docs.yorlet.com/leasing/referencing Learn how to create and track tenant references. Yorlet offers a dedicated dashboard to efficiently manage the referencing process and keep all reference-related information in one place. Tenant referencing is a crucial step in assessing the suitability of prospective tenants for your property. Whether you choose an integrated referencing supplier or opt for off-platform references, Yorlet makes it easy to stay organised and monitor progress. ## Off-platform referencing If your preferred referencing supplier is not integrated with Yorlet or does not support integrations, you can still track and log the progress of your references within your Yorlet account. By creating an off-platform reference, you can maintain a record of your reference process. You can store PDF files for referencing results for each tenant and assess the outcome to determine if the tenant is suitable for your property. References can be categorized as **Accept**, **Consider**, or **High risk** based on your results. Whenever your referencing supplier provides referencing results, you can update the status of your referencing and upload a PDF copy of the results to the corresponding reference. ## Integrated referencing With integrated referencing, you can submit reference requests and automatically collect results within your Yorlet account. Similar to off-platform referencing, you will create a referencing record, but you won’t need to manually update the results once they are finalized. The process may vary depending on the referencing supplier you work with. Yorlet supports the following integrated providers: * **Advance Rent** * **Canopy** * **HomeLet** * **Let Alliance** [Learn more about setting up integrated referencing](/leasing/referencing/integrated-referencing). When you use **Advance Rent**, the reference record surfaces additional data such as affordability, credit score, sanctions, and progress, directly within the reference. For applicable references, you can also download the tenant's **Right to Rent** documentation from the reference page. ## Creating a reference You can create a Reference record in Yorlet using two methods: * **From the referencing dashboard:** Go to the Referencing dashboard, click **New reference**, choose a customer, and decide if the reference should be associated with an ongoing application. An ongoing application refers to an application that is currently in progress. Then, specify if the reference should be automatic (integrated) or off-platform. Finally, click **Create reference**, and a record will be added to your Yorlet account. * **When creating an application:** Go to the Leasing dashboard, click **New application**, choose an application type, and add a customer. You will see a box with a toggle switch named **Require reference**. By default, the switch is turned off, so you need to switch it on to create a reference. ## Managing references Once a reference record has been created, you can manage several aspects of the reference at any time. You have the flexibility to update the reference outcomes based on your assessment: * **Accept**: The tenant meets the referencing criteria. * **Consider**: Further evaluation is needed before making a decision (accepting an application). * **High risk**: The tenant poses a potential risk and requires careful consideration. When reviewing a reference, you have the flexibility to update the reference outcomes based on your assessment. Here’s an example to illustrate this process: 1. You create a reference record for a tenant and proceed with the referencing process. 2. After reviewing the reference information, you find that the tenant’s financial history requires further evaluation. At this stage, you can set the outcome to **Consider** to indicate that additional scrutiny is needed before making a final decision. 3. You conduct further checks or request additional information from the tenant to gather more details about their financial situation. 4. Based on the additional information received, you determine that the tenant poses a higher risk due to significant financial issues. In this case, you can update the outcome to **High risk** to reflect the potential risks associated with accepting the application. 5. With the reference outcome set to **High risk**, you can carefully assess whether to proceed with the application or explore alternative options to minimise potential risks. By updating the reference outcomes, you can accurately reflect your assessment and ensure that you make well-informed decisions about prospective tenants. Additionally, when the outcome of your reference has been finalised, and you have a PDF reference report, you can upload and attach it to the reference record. This document will be viewable from the Yorlet Dashboard and available for download. Please note that uploading a document will replace the current one that is uploaded, so it’s best to use this functionality when creating an off-platform reference. # Integrated referencing Source: https://docs.yorlet.com/leasing/referencing/integrated-referencing Connect a referencing provider so results land in Yorlet automatically. Integrated referencing submits a reference request to a provider and brings the results back into Yorlet. You create the reference as usual, then the provider updates it as checks complete — you do not need to enter the outcome by hand. To manage your integrations, go to [Settings → Referencing](https://dashboard.yorlet.com/settings/referencing). ## Connect a provider To start using Advance Rent, go to [Settings → Referencing](https://dashboard.yorlet.com/settings/referencing) and click **Setup** for Advance Rent. Once connected, references created with Advance Rent automatically surface affordability, credit score, sanctions, and progress data, and you can download the tenant's **Right to Rent** documentation from the reference page. Create a HomeLet account first. Then go to [Settings → Referencing](https://dashboard.yorlet.com/settings/referencing), find HomeLet, and click **Setup**. You will need your **Member ID**, **Client ID**, and **Client secret** from HomeLet support. Create a Let Alliance account first. Then go to [Settings → Referencing](https://dashboard.yorlet.com/settings/referencing), find Let Alliance, and click **Setup**. You will need your **Member ID**, **Client ID**, and **Client secret** from Let Alliance support. Create a Canopy account first. Then go to [Settings → Referencing](https://dashboard.yorlet.com/settings/referencing), find Canopy, and click **Setup**. You will need your **Member ID**, **Client ID**, and **Client secret** from Canopy support. For the Canopy process, support, and reports, see the [Canopy help centre](https://agenthelp.canopy.rent). # Renewals Source: https://docs.yorlet.com/leasing/renewals Ensure high occupancy by tracking and automating the renewal process. Yorlet Leasing offers a dedicated dashboard and a streamlined workflow to efficiently manage the renewal process, maximising occupancy and providing a seamless experience for tenants. As a tenancy approaches its end, Yorlet creates a renewal intent record, allowing you to either renew or terminate the tenancy. The dashboard enables you to take quick action and stay on top of your occupancy rates. ## Setting up automatic renewals To get started with Renewals, navigate to the settings dashboard in your account, then go to Leasing > [Renewals](https://dashboard.yorlet.com/settings/renewals). Turn on **Create an automatic renewal intent** to enable the automatic creation of a renewal intent at the end of each tenancy. Additionally, you need to define the number of days before the tenancy ends when you want Yorlet to generate the renewal intent record. This can be set between 1 and 120 days. Once configured, renewal intent records will start appearing in the [Renewals Dashboard](https://dashboard.yorlet.com/renewals) under the **Pending** section. ## Managing renewal intents When a renewal intent is created, it will appear in the **Pending** section of the Renewals Dashboard. The record provides a snapshot of the tenancy, including details on outstanding arrears and registered deposits, to assist you in navigating the process. You can also mark a renewal intent as either **Renewing** or **Leaving**, which triggers one of two workflows: ### Renewing If the tenant decides to renew their tenancy, click the **Renewing** button. This updates the status of the renewal intent, and a new button, **Create renewal**, will appear. When selected, the application builder will open in the **Renewal** format, automatically populating tenant and property information. You will need to update specific details such as payment schedules, pricing, line items, application payments, and contracts. Once completed, the tenant will receive an email with a link to the Application Portal, where they can proceed with the standard application process. Once the application process is finished, the renewal intent status will be updated to **Complete**. ### Leaving If the tenant has decided to leave the tenancy without renewing, click the **Leaving** button. This updates the status of the renewal intent to **Leaving**. Then, navigate to the overflow menu (•••) and select **Complete leave**. The renewal intent will be updated to the **Complete** status, and the tenancy will end on the expected date. Please note that this action is irreversible. ### Change renewal intent type Before you choose to **Create a renewal** or **Complete leave**, you can switch the status of a renewal intent between **Renewing** and **Leaving**. To do this, go to the overflow menu (•••) and select **Switch to renewing** or **Switch to leaving**. You can make this switch as many times as needed. ### Leaving sub-reasons When a tenant is leaving, you can capture why. You can configure custom **Leaving sub-reasons** for each reason category in Settings > Leasing > [Renewals](https://dashboard.yorlet.com/settings/renewals). These appear when marking a renewal intent as not renewing. ## Rent reviews As well as renewals, the Renewals Dashboard handles rent increases under the **Rent increase** tab. A rent review lets you propose an increase, serve a compliant Section 13 notice, track the tenant's response, and apply the new rent automatically. See [Rent reviews](/leasing/renewals/rent-reviews) to learn more. # Rent reviews Source: https://docs.yorlet.com/leasing/renewals/rent-reviews Propose, serve, and apply rent increases with a compliant Section 13 workflow. A rent review lets you propose a rent increase on an ongoing tenancy and manage it through to completion. For UK assured shorthold tenancies, Yorlet generates the statutory **Section 13** notice (**Form 4**), tracks the tenant's response, records any tribunal decision, and applies the new rent automatically on the effective date. Rent reviews appear under the **Rent increase** tab of the [Renewals Dashboard](https://dashboard.yorlet.com/renewals), and on the **Rent reviews** section of the related tenancy. ## Starting a rent review A rent review can be created in a few ways: * **Automatically**: If you have enabled automatic rent reviews, Yorlet creates a rent review when a tenancy becomes eligible. See [Settings](#settings) below. * **From a tenancy review**: When scheduling a [tenancy review](/leasing/tenancies/tenancy-reviews), you can choose to **Create rent increase** when the review date is reached. * **From a tenancy**: Start a rent review directly from the tenancy's timeline. When a rent review is first created it has a `Pending` status, and the timeline shows when the review is due. ## Serving notice To propose the increase, open the rent review and click **Serve notice**. You will be asked to provide: * **Current total rent** and **Proposed total rent**: Enter the total rent across all tenants, not the amount per tenant. Where possible, the current rent is pre-filled from the tenancy. * **Date notice served**: The date the notice was served to the tenant. This cannot be in the past, and unless early notice is allowed, cannot be before the suggested due date. * **Effective date**: When the new rent takes effect. This must be at least two months after the notice served date. * **Email Form 4 to the tenant**: When enabled, the Section 13 notice is emailed to the tenant as soon as notice is served. You can always send it later. If the dates Yorlet holds need correcting, you can override the values printed on the Form 4: the **Tenancy start date (4.2)**, the **Most recent rent increase (4.3)**, and the **Date of first rent increase (4.4)**. The start dates are sticky and carry forward to future rent reviews on the same tenancy. Once notice is served, the rent review moves to `Notice served` and the **Section 13 - Form 4** notice becomes available to **View**, **Download**, or **Email to tenant**. A tenant must be given at least two months' notice. Yorlet also enforces a 12-month review cycle from the last increase or tenancy start, unless you have allowed early notice. ## Recording the tenant's response After notice is served, use the overflow menu (•••) to record what happens next: * **Tenant accepted**: The tenant agrees to the proposed rent. The review moves to `Accepted`. * **Tenant challenged**: The tenant refers the increase to a tribunal. The review moves to `Challenged`, where you can record a tribunal reference. * **Record tribunal decision**: Once a challenged review has been decided, record the outcome (including the rent set by the tribunal). The review moves to `Tribunal decided`. * **Withdraw notice**: Withdraw the served notice. The review moves to `Withdrawn`. ## Applying the increase When the effective date is reached, Yorlet automatically applies the agreed rent to the tenancy's subscription and the rent review moves to `Effective`. If the rent was set by a tribunal, the tribunal's figure is used. ## Statuses * **Pending**: The rent review has been created and is awaiting notice. * **Notice served**: A Section 13 notice has been served to the tenant. * **Accepted**: The tenant has accepted the proposed rent. * **Challenged**: The tenant has challenged the increase at a tribunal. * **Tribunal decided**: A tribunal has decided the rent. * **Effective**: The new rent has been applied to the tenancy. * **Withdrawn**: The served notice was withdrawn. ## Rent review fees If a **Rent review fee** is set on the [unit](/real-estate/units), the fee is charged to the unit's owners when the rent review is applied. The fee is split between owners according to their share of the unit, and follows the fee tax settings on the unit. No fee is charged if the tenancy's original application had **Auto apply unit fees** turned off. By default the fee is charged when the increase takes effect. Turn on **Charge the rent review fee when notice is served** in your [renewals settings](#settings) to charge it earlier in the process instead. Whichever timing you choose, the fee is charged once and becomes available to the owner on the effective date. It is not refunded automatically if the notice is later withdrawn. ## Settings To configure rent reviews, navigate to Settings > Leasing > [Renewals](https://dashboard.yorlet.com/settings/renewals): * **Upcoming renewals**: Turn on **Create an automatic renewal intent** and set how many days before the end of a tenancy the record should be created (between 1 and 120 days). * **Rent increase notice**: Turn on **Allow serving notice before the suggested date** to serve notice at any time. When this is off, notice can only be served on or after the system-suggested due date based on the last rent increase or tenancy start. * **Rent review fee**: Turn on **Charge the rent review fee when notice is served** to charge the landlord as soon as notice is served, rather than when the increase takes effect. # Tenancies Source: https://docs.yorlet.com/leasing/tenancies Manage move-ins, move-outs, and make changes to ongoing tenancies with ease. When you successfully complete an application or add a new active tenancy, a tenancy record will be created in your account. These records contain all the necessary information related to the tenancy, including property and tenant details, links to their applications and subscriptions, and complete payment history. Tenancies have statuses that update dynamically: * **Pending**: The tenancy has been approved but has not yet started and will begin in the future. * **Active**: The tenant has moved in, and the tenancy term has commenced. * **Complete**: The tenant has moved out, and the tenancy term has ended. * **Canceled**: The tenancy was ended before its term completed. You can add an active tenancy at any time by navigating to the [Tenancy Dashboard](https://dashboard.yorlet.com/tenancies) and selecting **New tenancy**. This will initiate the rental application process using the **Active tenancy** format. ## Managing a tenancy From a tenancy record, open the overflow menu (•••) to take action: * **Tenancy review**: Schedule a reminder to review the tenancy. See [Tenancy reviews](/leasing/tenancies/tenancy-reviews). * **Compliance certificate**: Download a PDF compliance certificate for the tenancy. * **Send compliance documents**: Email the tenancy's customers the unit's EPC, electric safety, and gas safety certificates. See [Compliance documents](/leasing/tenancies/compliance-documents). * **Lease change**: Make changes to an active tenancy. See [Lease changes](/leasing/tenancies/lease-changes). * **Create revision**: Create a new application that revises the current tenancy. See [Revising a tenancy](/leasing/applications/create-an-application#revising-a-tenancy). * **Stop cancellation**: Remove a scheduled end date and keep the tenancy running. * **End tenancy**: End an active or pending tenancy. ## Ending a tenancy To end a tenancy, select **End tenancy** from the overflow menu (•••). You can end it immediately or schedule it for a future date, choose whether to cancel the associated subscriptions, and provide a reason, such as requested by the customer, tenant replacement, eviction, arrears, or early termination. Scheduling an end date sets when the [unit](/real-estate/units#availability) is next available, so it becomes **Coming available** without putting it on the market. You can start a new letting from that unit by [creating an application](/leasing/applications/create-an-application#unit-availability) and releasing it from the form. When the tenancy actually ends, the unit is released to the market as **To let**, unless you have held it back. ### Stopping a scheduled cancellation If a tenancy is scheduled to end on a future date and your tenant decides to stay, you can call it off. Select **Stop cancellation** from the overflow menu (•••), then confirm. This removes the scheduled end date and keeps the tenancy active. Any scheduled cancellation of the tenancy's subscriptions is also reversed, so rent continues to be collected as normal. If you have not already released the unit, it leaves **Coming available** and returns to **Occupied**. **Stop cancellation** only appears while the end date is still in the future. Once a tenancy has ended, you cannot reinstate it. # Compliance documents Source: https://docs.yorlet.com/leasing/tenancies/compliance-documents Email a tenancy's customers the compliance certificates on file for their unit. Compliance documents — the EPC, electric safety, and gas safety certificates for a unit — are uploaded to the unit's [Compliance section](/real-estate/units). From an active or pending tenancy, you can email whichever of these certificates are on file directly to the tenancy's customers, without leaving the Dashboard. ## Sending compliance documents To send compliance documents, follow these steps: 1. Open the tenancy you want to send documents for. 2. Click the overflow menu (•••) and select **Send compliance documents**. 3. Review the confirmation dialog, then click **Send**. Yorlet emails every customer on the tenancy who has a valid email address on file, attaching whichever of the EPC, electric safety, and gas safety certificates are currently uploaded to the unit. **Send compliance documents** only appears on **Pending** and **Active** tenancies, and only sends successfully if the unit has at least one compliance certificate uploaded and at least one customer with a valid email address. Add or update certificates from the unit's Compliance section. Need a standalone PDF instead of an email? Select **Compliance certificate** from the same overflow menu (•••) to download one for the tenancy. # Lease changes Source: https://docs.yorlet.com/leasing/tenancies/lease-changes Learn how to make changes to ongoing tenancies. In certain situations, you may need to modify specific aspects of a pending or active tenancy. Lease changes allow you to make essential adjustments. To make a lease change, find the tenancy you’d like to make changes for, click on the overflow menu (•••) and select **Lease change**. You will be asked to provide a **Description** of the change, followed by one or more of the following options: * **Contract end date**: Extend or shorten the length of a tenancy, or choose **Switch to rolling**, which extends the contract indefinitely until you cancel the tenancy or specify an end date. You can also set the **End of tenancy behaviour** to **Roll periodically** or **Complete**. * **Applicants**: Add or remove tenants on the tenancy, and set whether each is a lead tenant or permitted occupier along with their share of rent. * **Move-in date**: Modify the day your tenant moves in. * **Move-out date**: Change the day your tenant moves out. * **Unit**: Switch to another building and/or unit. * **Effective on**: Set the date that applicant and unit changes take effect. This option is only available for applicant and unit changes. * **Addendum**: Select an addendum from your contract templates. The addendum is added as a new contract and must be signed by all applicants for the change to take effect. Please note that you can make multiple lease changes simultaneously. For example, if you want to change both the move-in date and the property the tenant is leasing, you can toggle on both changes and apply them together. All lease changes are permanently documented in the tenancy record, providing a description and an audit trail of the changes that occurred. You cannot create a lease change while there is an active renewal intent on the tenancy. Cancel the renewal intent first. # Tenancy reviews Source: https://docs.yorlet.com/leasing/tenancies/tenancy-reviews Schedule reminders to review a tenancy and stay ahead of key dates. A tenancy review is a scheduled reminder to revisit a tenancy at a future date — for example, ahead of a renewal, a rent review, or a compliance check. Yorlet notifies the assigned team member when the review is due, so nothing slips through the cracks. ## Scheduling a review To schedule a review, open the tenancy, click the overflow menu (•••), and select **Tenancy review**. Then provide: * **Review assignee**: The team member responsible for the review. * **Review due at**: The date the review is due. This must be in the future. * **Notification channels**: Choose how the assignee is notified — **Dashboard notification**, **Email notification**, or both. At least one channel is required. * **Create rent increase**: Optionally, automatically create a [rent review](/leasing/renewals/rent-reviews) when the review date is reached. Click **Add** to save the review. When the review date arrives, the assignee is notified through the channels you selected. If you enabled **Create rent increase**, a rent review is created for the tenancy automatically. Use **Create rent increase** to combine your review reminder with the start of a rent review, so the rent increase workflow is ready and waiting on the due date. # Letters Source: https://docs.yorlet.com/letters Print and post physical letters to tenants and owners from reusable templates. Letters lets you send physical post to [customers](/customers) and [owners](/owners) without leaving Yorlet. Write the letter once as a template, merge in names and addresses, then print and post it. Letters are printed in colour, double-sided. You can view and manage every letter from the [Letters page](https://dashboard.yorlet.com/letters). You can also send a letter automatically from a [workflow](/business-automation/workflows/actions#send-letter). ## Enable Letters Letters is a pay-as-you-go add-on. To enable it, follow these steps: 1. Go to [Your plans](https://dashboard.yorlet.com/settings/plans). 2. Find **Letters** and click **Get started**. 3. Complete checkout. Once enabled, **Letters** appears in the sidebar, with **Templates** underneath. You are billed per send, plus extra pages and premium postage. See [list pricing](https://www.yorlet.com/pricing#letters). You need the admin role to enable Letters. ## Letter statuses Every letter has a status that shows where it is: * **Draft**: The letter has been created but not sent. You can still edit or delete it. * **Sending**: The letter has been submitted for print and post. * **Sent**: The letter has been accepted for print and post. It can no longer be edited. * **Failed**: Sending did not complete. You can fix the problem and send it again. * **Canceled**: The letter was cancelled before it was printed. The [Letters page](https://dashboard.yorlet.com/letters) has a tab for each status. ## Delivery Choose how the letter is posted when you create it: * **Standard**: Ordinary postage. This is the default. * **Tracked**: Postage with tracking, when a tracking number is available. * **Premium**: Premium postage, billed as an extra charge. The first page is included in the send. Extra pages are billed separately, and **Premium** postage is billed on top. Letters are always printed in colour and double-sided. ## What you need before you send To print and post a letter, Yorlet needs: * A **name**, **line 1**, **city**, and **postcode** on the customer or owner you are writing to. * A business **name** and **address** on your account, so the letter can show a return address. If sending fails, the letter moves to **Failed** and the reason is shown on the letter page. ## Get started Create a letter, choose postage, and print and post it Build reusable letters with merge fields and signatures # Send a letter Source: https://docs.yorlet.com/letters/send-a-letter Create a letter, choose postage, and print and post it to a customer or owner. The [Letters page](https://dashboard.yorlet.com/letters) lists every letter. Open a letter to see who it is addressed to, the delivery you chose, when it was sent, and any tracking number. ## Creating a letter To create a letter, follow these steps: 1. Click **New letter** (or press **N**). 2. Choose the **Recipient type**, then pick the **Customer** or **Owner**. 3. Optionally choose a **Template**. The letter copies that template's content, so later edits to the template do not change this letter. If the template has **Variables**, fill in each value. 4. Optionally enter a **Name**. If you leave it blank, the template name is used. 5. Choose **Delivery**: **Standard**, **Tracked**, or **Premium (extra charge)**. 6. Choose the **Address window** — **Left** or **Right** — to match the envelope window. 7. If you did not pick a template, write the **Content**. See [Templates](/letters/templates) for headings, text, signatures, and merge fields. A preview of page 1, including the envelope window, updates as you write. 8. Turn on **Send immediately** if you want it printed and posted as soon as you create it. 9. Click **Create**. You can also start a letter from a customer or owner. Open the record, open the actions menu, and click **Send letter**. The recipient is filled in for you. New letters start as **Draft**, unless you turned on **Send immediately**. ## Sending from a workflow If you use [Workflows](/business-automation/workflows/overview), add a **Send letter** step to print and post automatically. Choose a template, who to write to (a customer or owner ID), and delivery. If the template has variables, fill each one — you can insert a field from the trigger. Amounts on invoices are stored in pence. To print them as money, insert the field and choose **Currency** from **Format**, or type `| currency` after the path. For example `{{ trigger.object.total | currency }}` becomes £100.00 when the total is 10000. Use `| date` for a readable date. The letter is sent as soon as the step runs — it does not stay as a draft. The recipient needs a name and address, and your account needs a return address, the same as when you send a letter yourself. ## Sending a letter To send a draft or failed letter, follow these steps: 1. Open the letter, or right-click it in the table. 2. Click **Send**. 3. Review the confirmation. Postage is billed per send, plus extra pages and premium delivery. The letter cannot be edited after it is submitted. 4. Click **Send letter**. The letter moves to **Sending**, then **Sent** when it has been accepted for print and post. The letter page then shows **Pages**, **Sent**, and **Tracking** when a tracking number is available. Once a letter is submitted, you cannot edit it. Cancel it instead if it has not yet been printed. ## Editing a draft Only **Draft** letters can be edited. Open the letter and click **Edit**, or right-click the row and select **Edit letter**. You can change the name, delivery, address window, and content. ## Cancelling a letter Cancel a letter if it should not be printed. You can cancel a letter while it is **Draft**, **Sending**, **Sent**, or **Failed**. To cancel a letter, follow these steps: 1. Open the letter, or right-click it in the table. 2. Click **Cancel letter**. 3. Click **Cancel letter** to confirm. Cancelling cannot be undone. ## Deleting a draft Only **Draft** letters can be deleted. Sent, cancelled, and failed letters stay in the list. To delete a draft, follow these steps: 1. Open the letter, or right-click it in the table. 2. Click **Delete**. 3. Click **Delete** to confirm. Deleting a draft cannot be undone. ## Failed letters If sending does not complete, the letter moves to **Failed** and the letter page shows why. Fix the problem — for example a missing address — then click **Send** to try again. ## Filtering On the [Letters page](https://dashboard.yorlet.com/letters), use the status tabs or click **Filter** to narrow the list by **Status**, **Recipient**, or **Delivery**. Right-click any row to copy the letter ID or open it in a new tab. # Letter templates Source: https://docs.yorlet.com/letters/templates Build reusable letters with merge fields and signatures, then send them to customers or owners. Templates are the reusable content behind your letters. Write the wording once, insert merge fields for names and addresses, and optionally add a signature. Each time you [send a letter](/letters/send-a-letter) from a template, Yorlet copies that content onto the letter so later template edits do not change letters you have already created. You can manage templates from the [Letter templates page](https://dashboard.yorlet.com/letters/templates). ## Creating a template To create a template, follow these steps: 1. Go to [Letter templates](https://dashboard.yorlet.com/letters/templates). 2. Click **New letter template** (or press **N**). 3. Enter a **Name**, such as an arrears reminder. 4. Optionally add a **Description** of when to use it. 5. Choose the **Recipient**: **Customer**, **Owner**, or **Any** if the template can be used for either. 6. Choose the **Address window** — **Left** or **Right**. 7. Optionally add **Variables** — a key and label for values you fill in later, such as an amount due. 8. Build the **Content** with heading, text, and signature blocks. A preview of page 1, including the envelope window, updates as you write. 9. Click **Create**. When you create a letter, only templates that match the recipient type are offered. A template set to **Any** can be used with customers or owners. The same templates appear when you add a **Send letter** step to a workflow. ## Content blocks The letter body is a list of blocks. Use **Heading**, **Text**, and **Signature** to add blocks, then move them up or down or delete them. * **Heading**: A short title. You can insert merge fields. * **Text**: The body of the letter. You can insert merge fields, and start a new paragraph with a line break. * **Signature**: A printed name, and optionally a signature image. ### Signatures For a signature block: * **Printed name** appears under the signature. If you leave it blank, your account name is used. * **Signature image** is an optional PNG or JPEG. Click **Upload signature** to attach one. If you do not upload an image, the printed name is shown in a signature style instead. ## Merge fields Merge fields are replaced with real details when the letter is sent. In a heading or text block, type `{{` or pick a field from the list. The fields available depend on who the template is for. Customer templates do not offer owner fields, and owner templates do not offer customer fields. | Field | What it inserts | | --------------------------- | --------------------------- | | `{{customer.name}}` | The customer's name | | `{{customer.email}}` | The customer's email | | `{{customer.phone}}` | The customer's phone | | `{{customer.address}}` | The customer's full address | | `{{owner.name}}` | The owner's name | | `{{owner.email}}` | The owner's email | | `{{owner.phone}}` | The owner's phone | | `{{owner.address}}` | The owner's full address | | `{{account.name}}` | Your account name | | `{{account.support_email}}` | Your support email | | `{{account.support_phone}}` | Your support phone | | `{{account.address}}` | Your account address | | `{{today}}` | The date the letter is sent | You can also insert individual address lines, such as `{{customer.address.line1}}` or `{{customer.address.postal_code}}`. The same line fields exist for `owner` and `account`. ## Custom variables Use variables for details that change each time you send the letter, such as an amount due or a notice date. To add a variable, click **Add** under **Variables**, enter a **Key** (for example `amount_due`) and a **Label**, then insert `{{variables.amount_due}}` in a heading or text block. When you create a letter from the template, or add a **Send letter** step to a workflow, Yorlet asks you to fill in each variable. In a workflow you can insert a value from the trigger, and format amounts or dates (see [Send a letter](/letters/send-a-letter#sending-from-a-workflow)). Start body text with `Dear {{customer.name}},` so every letter opens with the right name. ## Editing and deleting templates Click a template in the table, or right-click and select **Edit template**, to change its name, description, recipient, address window, or content. To delete a template, right-click it and select **Delete template**, then confirm. Existing letters created from that template are not affected. # Maintenance Source: https://docs.yorlet.com/maintenance Track, prioritise, and resolve maintenance issues across your properties. Maintenance issues let you keep on top of repairs and upkeep across your properties. Each issue records what needs fixing, which unit it relates to, who is dealing with it, and how urgent it is. Your team can raise issues directly, and your tenants can report problems from their portal, so everything lands in one place. Maintenance has two pages in the Dashboard: * The [Maintenance page](https://dashboard.yorlet.com/maintenance) is your reporting view, showing how your team is performing and how much work is outstanding. * The [Issues page](https://dashboard.yorlet.com/maintenance/issues) is where your team works through individual issues, on a board, in a table, or in a split view. ## Issue statuses Every issue has a status that shows where it is in your workflow: * **Open**: The issue has been reported but nobody has started work on it yet. * **In progress**: Someone is actively working on the issue. * **Resolved**: The issue has been fixed and no further action is needed. ## Issue types Issues are grouped by type so you can tell where they came from: * **Customer request**: Raised by a tenant from their portal. * **Internal**: Raised by your team. * **Planned**: Scheduled or preventative work. ## Reported and internal work Tenant-reported work and work your team raises itself are usually handled by different people against different promises, so both the Maintenance page and the Issues page have a set of source tabs in the top right: * **All**: Every issue. * **Reported**: Issues a tenant reported from their portal, which have the **Customer request** type. * **Internal**: Issues your team raised, including **Planned** work. Whichever tab you choose applies to everything below it, so the metrics, chart, board, and table always describe the same set of work. You can also set separate [response targets](/maintenance/response-targets) for reported and internal issues. ## Overview metrics The [Maintenance page](https://dashboard.yorlet.com/maintenance) opens with a row of metrics summarising your portfolio: * **Raised today**: Issues created since midnight. * **Open**: Issues nobody has started yet. * **In progress**: Issues someone is actively working on. * **Overdue**: Unresolved issues that are past the resolution target for their priority. Issues on hold are not counted, because their clock is paused. * **Avg. resolution**: The mean time from an issue being raised to being resolved, over the last 30 days. Time spent on hold is not counted. * **Resolved on time**: The share of issues resolved within their target over the last 30 days. Below the metrics, the **Open issues** chart breaks your outstanding work down by priority so you can see what is waiting. ## Priorities Set a priority to help your team focus on what matters most: * **Low** * **Medium** * **High** * **Urgent** Priority also decides how quickly an issue should be responded to and resolved. See [Response targets](/maintenance/response-targets). ## Issue categories Each issue can be tagged with a category to describe the kind of work involved, such as **Heating system**, **Air conditioning**, **Appliance**, **Electricity**, **Exterior**, **Housing**, **Housekeeping**, **Locksmith**, **Pest control**, **Painting**, **Plumbing**, or **Other**. ## Get started Create, prioritise, and resolve issues from the table, split, and board views Let tenants report issues from their portal and set your team's availability Measure issues against response and resolution targets, and pause the clock when you are waiting Set your availability, your response targets, and who hears about maintenance activity # Manage issues Source: https://docs.yorlet.com/maintenance/manage-issues Create, prioritise, and resolve maintenance issues from the Dashboard. The [Issues page](https://dashboard.yorlet.com/maintenance/issues) is where your team works through every issue. You can switch between views, create new issues, filter and export, and open any issue to see its full history. ## Choosing a view Use the view switcher in the top right of the page to change how your issues are displayed: * **Split**: A list of issues alongside a preview of the selected issue, so you can move through them quickly without leaving the page. * **Table**: A full-width table of every issue, best for filtering, sorting, and exporting. * **Board**: A kanban board with a column for each status (**Open**, **In progress**, and **Resolved**). Yorlet remembers the view you last used and returns you to it next time. Alongside the view switcher are the **All**, **Reported**, and **Internal** source tabs, which scope the page to tenant-reported work or work your team raised. In the table and split views you also get tabs for **Open**, **In progress**, and **Resolved**. ## Creating an issue To create an issue, follow these steps: 1. Click **New issue** (or press **N**). 2. Enter a **name** and an optional **description**. 3. Choose the **unit** the issue relates to. 4. Optionally assign a team member as the **assignee**. 5. Pick an **issue category**, a **priority**, and a **status**. 6. Click **Create issue**. A unit is required when you create an issue from the Dashboard so the repair is linked to the right property. You can also raise an issue from a unit. Open the unit and click **New** on its **Maintenance issues** section, and the unit is filled in for you. ## Working on the board The board gives you an at-a-glance view of your workload, grouped into a column per status. Each card shows the issue name and description, its category, its assignee, and the unit it relates to — or **Communal** for work in a shared area. Cards also show how many photos and videos are attached, the priority, and how long is left against the issue's target, such as **Due in 3 hours** or **2 hours overdue**. Issues your team raised are marked **Internal** or **Planned**; tenant requests carry no type label. * Drag a card from one column to another to update its status — for example, move a card into **In progress** when work starts, or **Resolved** when it is done. * Use the create action at the top of a column to add a new issue that starts in that status. ## Filtering and exporting In the table and split views, click **Filter** to narrow the list by **Status**, **Assignee**, **Priority**, **Building**, **Category**, **Type**, or **SLA**. The **SLA** filter has two options, **Breached** and **On hold**, which are the quickest way to find work that has missed its target or is waiting on something. Click **Export** to download the issues currently shown, and any filters you have applied will be reflected in the exported file. ## Managing a single issue Open an issue to see its details and history. At the top of the page you can change the assignee, and a badge shows how the issue is standing against its target, alongside the **Response due**, **First response**, and **Resolution due** times. Use **Put on hold** to pause the clock while you are waiting on someone else, and **Resume** to start it again. See [Response targets](/maintenance/response-targets) for how the clocks work. From the issue page you can also: * Click **Edit** to change the name, description, category, priority, or status, to mark the issue as a **Communal area** issue, to record that the **Tenant wants to be present**, or to put the issue **On hold** with a **Reason for the hold**. * Upload **photos** of the issue (PNG, JPEG, or PDF). * Upload **videos** of the issue (MP4, MOV, or WebM, up to 100 MB each). * Leave **comments** for your team. * Review the **tenants** and **unit owners** linked to the property. * Follow the **timeline** to see when the issue was created, updated, and resolved. When a tenant has asked to be present for the visit, the days and times that suit them are shown on the issue so you can arrange the work. See [Tenant requests](/maintenance/tenant-requests) for more. # Response targets Source: https://docs.yorlet.com/maintenance/response-targets Measure maintenance issues against response and resolution targets, and pause the clock when you are waiting. Response targets are the promises your team works to. Every issue is given a time to respond and a time to resolve, based on its priority and whether a tenant reported it, and Yorlet then tracks each issue against those deadlines. This is what powers the **Overdue**, **Avg. resolution**, and **Resolved on time** metrics on the [Maintenance page](https://dashboard.yorlet.com/maintenance). Tenant-reported work and internal work carry separate targets, because a tenant waiting at home is a tighter promise than a job your team scheduled itself. ## The two clocks Each issue runs two clocks from the moment it is raised: * **Respond within**: How long your team has to pick the issue up. This clock stops at the first response. * **Resolve within**: How long your team has to get the work done. This clock runs until the issue is resolved. Yorlet records the first response as soon as someone picks the issue up — either when it is assigned to a team member, or when its status moves out of **Open**. A tenant acting on their own issue never counts as your response. The issue page shows both deadlines under **Response due** and **Resolution due**, alongside the **First response** time once it has been recorded. ## Target statuses Every issue carries a badge summarising where it stands: * **On track**: The issue is within its targets with time to spare. * **At risk**: The issue is close to its next deadline. * **Breached**: The response or resolution deadline has passed. * **On hold**: The clock is paused. Hover the badge to see the reason. * **Met**: The issue was resolved within its resolution target. On the board, cards show the same information as a countdown instead, such as **Due in 3 hours** or **2 hours overdue**. Issues raised before you had any response targets have no badge, because there was no promise to measure them against. They are also left out of the **Resolved on time** metric. To find work that needs attention, filter the table by **SLA** and choose **Breached** or **On hold**. ## Putting an issue on hold Sometimes an issue cannot progress for reasons outside your team's control, such as waiting on parts or on access to the property. Putting it on hold pauses both clocks so the wait does not count against you. To put an issue on hold, follow these steps: 1. Open the issue. 2. Click **Put on hold**. 3. Optionally click **Edit** and add a **Reason for the hold**, such as "Waiting on parts", so your team knows what it is waiting for. Click **Resume** when work can continue. The time the issue spent on hold is added back to its deadlines, so your team keeps the time it had left when work stopped. While an issue is on hold it is left out of the **Overdue**, **Avg. resolution**, and **Resolved on time** metrics. Resolving an issue automatically takes it off hold, and an issue that has already been resolved cannot be put on hold. ## Changing priority Changing an issue's priority applies the targets for its new priority. The deadlines are recalculated from when the issue was raised, not from when you changed it, so an urgent issue that was logged as low priority yesterday shows its true position straight away. ## Default targets Until you set your own targets, Yorlet applies these defaults. Reported hours are the promise for tenant requests; internal work is given roughly double. | Priority | Reported respond | Reported resolve | Internal respond | Internal resolve | | ---------- | ---------------- | ---------------- | ---------------- | ---------------- | | **Urgent** | 4 hours | 24 hours | 8 hours | 48 hours | | **High** | 8 hours | 48 hours | 24 hours | 72 hours | | **Medium** | 24 hours | 5 days | 48 hours | 7 days | | **Low** | 48 hours | 7 days | 72 hours | 14 days | ## Setting your own targets Targets are set per priority for reported and internal work on the **Response targets** section of your [maintenance settings](/maintenance/settings). Changing a target applies to issues raised from then on, and to any existing issue whose priority you change afterwards. # Maintenance settings Source: https://docs.yorlet.com/maintenance/settings Set your team's availability, your response targets, and who hears about maintenance activity. Your maintenance settings control when your team can attend visits, the targets your issues are measured against, and who is told when something is raised. To change them, navigate to Settings > Maintenance in the [Dashboard](https://dashboard.yorlet.com/settings/maintenance), make your changes, and click **Save**. You need the admin role to save maintenance settings. ## Availability **Availability** is the weekly schedule of times your maintenance team can attend visits. Tenants who ask to be present when reporting an issue can only pick times inside these windows. To set your availability, follow these steps: 1. Turn on the days your team is available. Days that are turned off are shown as **Unavailable**. 2. Adjust the **start** and **end** times for each day. New days start at 09:00 to 17:00. 3. Click **Add time range** if a day has more than one window, such as a morning and an afternoon slot. 4. Click **Save**. If you have not set any availability, tenants can still report issues and ask to be present — they just will not be able to pick a specific time slot. ## Response targets **Response targets** set how quickly issues should be responded to and resolved. Issues past their target are flagged as **Breached**, and time spent on hold does not count against them. See [Response targets](/maintenance/response-targets) for how the clocks work. Targets are set separately for the two sources of work: * **Reported**: Targets for issues a tenant reports. * **Internal**: Targets for issues your team raises, including planned work. To set your targets, follow these steps: 1. Choose the **Reported** or **Internal** tab. 2. For each priority from **Urgent** down to **Low**, enter the hours for **Respond within** and **Resolve within**. 3. Switch to the other tab and repeat. 4. Click **Save**. Targets are entered in hours so that same-day promises stay easy to express. For longer targets, use the equivalent in hours — 168 hours for a week, for example. ## Notifications **Notifications** control who hears about maintenance activity at an account level: * **Team inboxes**: Up to ten shared email addresses, emailed whenever an issue is raised, whoever it ends up assigned to. Click **Add inbox** to add one, and the remove button to take one away. Shared inboxes are useful so cover survives one person being away. * **Notify the assignee**: Turn this on to tell whoever an issue is assigned to that it is theirs, through their own chosen channels. Each team member also chooses how they hear about maintenance in their own notification settings, for when an issue is raised, when an issue is assigned to them, and when an issue is resolved. Tenants who reported an issue are updated separately, through the mobile app. See [Tenant requests](/maintenance/tenant-requests). # Tenant requests Source: https://docs.yorlet.com/maintenance/tenant-requests Let tenants report maintenance issues from their portal and keep them updated as you work. Tenants can report maintenance issues themselves from their tenant portal, so problems reach you without a phone call or email. Each request appears on your [Issues page](https://dashboard.yorlet.com/maintenance/issues) as an issue with the **Customer request** type, ready for your team to prioritise and resolve. ## How tenants report an issue From their portal, a tenant selects **New request** and then: 1. Chooses a **category** that best describes the problem. 2. Adds a short **description** with more detail. 3. Optionally attaches **photos** of the issue. 4. Optionally ticks **I wish to be present during the visit** and picks the times that suit them. Once submitted, the request is created as a maintenance issue in your account with the tenant and their unit already linked, and named after the category the tenant chose. ## Setting your availability When a tenant asks to be present, they can only choose from the visit times your team has made available. Set these windows on the **Availability** schedule in your [maintenance settings](/maintenance/settings). If you have not set any availability, tenants can still report issues and ask to be present — they just will not be able to pick a specific time slot. ## Finding tenant requests Select the **Reported** tab in the top right of the [Maintenance](https://dashboard.yorlet.com/maintenance) or [Issues](https://dashboard.yorlet.com/maintenance/issues) page to scope everything to tenant-reported work. In the table and split views you can also filter by **Type** and choose **Customer request**. Reported issues are measured against their own [response targets](/maintenance/response-targets), which are usually tighter than the targets for internal work because a tenant is waiting for an answer. When a tenant has asked to be present, the days and times they chose are shown on the issue so you can arrange the work. See [Manage issues](/maintenance/manage-issues) for more on working through issues. ## Keeping tenants updated Tenants who use the mobile app are notified automatically as their request moves on. They hear when work starts, when a resolved request is reopened, and when the request is marked as resolved, so you do not need to chase them with an update. # Importing data Source: https://docs.yorlet.com/onboarding/importing-data Import owners, units, tenancies, invoices, and collections into Yorlet. Importing is the fastest way to get an existing portfolio into Yorlet. Work through the steps in order: owners first, then buildings and units, then active tenancies. You can also import invoices, subscriptions, and account collections once those records exist. ## Import steps This is your landlord, leaseholder, and supplier data. This is your building and unit data. You can use the owner data imported in step one to attach the units to their owners. These are your active tenancies. You can use the unit data imported in step two to attach the tenancies to their units. ## Owners The owner record is used to store the details of the people or businesses that own the properties. #### Formatted fields The following fields need to be formatted to ensure that the data is imported correctly. | Field | Description | | :---------------- | :------------------------------------------------------------------------------ | | `business_type` | Can be one of `individual` or `company`. | | `type` | Can be one of `landlord`, `leaseholder`, or `supplier`. | | `address.country` | This should be a two letter country code. For example, “GB” for United Kingdom. | | `tax_residency` | This should be a two letter country code. For example, “GB” for United Kingdom. | Download the owners import template. ## Buildings and units Yorlet supports two different structures for your properties: [single property](/real-estate/buildings#single-property) and [multi-unit](/real-estate/buildings#multi-unit). Use the single property type when you’re adding a property you wish to lease as one. For example, a property with three residents all each paying rent. We are going to create a building record at the same time as a unit record. Single property buildings can only have one unit. #### Formatted fields The following fields need to be formatted to ensure that the data is imported correctly. | Field | Description | | :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `currency` | This should be a three letter currency code. For example, “gbp” for British Pound. | | `reference` | If you have a unique reference for the unit either from your own system or a previous system, you can add it here. | | `building_data.address.country` | This should be a two letter country code. For example, “GB” for United Kingdom. | | `furnished` | This should be either `true` or `false`. | | `fees.management_fee` | This should be an integer. For example, 10% should be 10. | | `fees.tax` | This should be an integer. For example, 20% VAT should be 20. | | `owners[0].owner` | This should be the ID of the owner record you created in the owners import that you want to attach to this unit. This can also be the email address of the owner if you have not yet imported the owner data. | | `owners[0].percent_ownership` | This should be an integer. For example, 100% ownership should be 100. | You can add multiple owners to a unit if the property is owned by multiple people. For each owner increment the index of the `owners` array. For example, the first owner is `owners[0]`, the second owner is `owners[1]`, and so on. The sum of all the `owners[].percent_ownership` fields should be 100. Download the unit import (single property) template. The multi-unit property type has a few different use cases: * A property that has multiple apartments, like a large building with 10 different properties you lease individually. * A house of multiple occupancy (HMO), where you lease individual rooms to different customers. We are going to create a building record first and then create a unit record for each unit in the building. ### Buildings Create a building record for each property you want to import. You can find the guide to creating a building [here](/real-estate/buildings#create-a-building). ### Units After creating the building record, you can create the unit records. You will need the building ID of the building you created in the buildings import. #### Formatted fields The following fields need to be formatted to ensure that the data is imported correctly. | Field | Description | | :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `building` | This should be the ID of the building record you created in the buildings import. | | `reference` | If you have a unique reference for the unit either from your own system or a previous system, you can add it here. | | `alternate_postal_code` | This should be the postal code of the unit if it is different to the building's postal code. | | `currency` | This should be a three letter currency code. For example, “gbp” for British Pound. | | `furnished` | This should be either `true` or `false`. | | `fees.management_fee` | This should be an integer. For example, 10% should be 10. | | `fees.tax` | This should be an integer. For example, 20% VAT should be 20. | | `owners[0].owner` | This should be the ID of the owner record you created in the owners import that you want to attach to this unit. This can also be the email address of the owner if you have not yet imported the owner data. | | `owners[0].percent_ownership` | This should be an integer. For example, 100% ownership should be 100. | You can add multiple owners to a unit if the property is owned by multiple people. For each owner increment the index of the `owners` array. For example, the first owner is `owners[0]`, the second owner is `owners[1]`, and so on. The sum of all the `owners[].percent_ownership` fields should be 100. Download the unit import (multi-unit) template. ## Active tenancies The active tenancy record is used to store the details of the tenancies that are currently active including current tenants and rent details. #### Formatted fields The following fields need to be formatted to ensure that the data is imported correctly. | Field | Description | | :------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | Must be `active_tenancy`. | | `currency` | This should be a three letter currency code. For example, “gbp” for British Pound. | | `unit` | This should be the ID of the unit record you created in the units import. | | `start_date` | This should be a date in the format `YYYY-MM-DD`. | | `end_date` | This should be a date in the format `YYYY-MM-DD`. If the tenancy is rolling, you can leave this blank. | | `subscription_data.collection_method` | The collection method for the subscription. `charge_automatically` requires the customer to provide a payment method; charges are made automatically each billing cycle. `send_invoice` sends an invoice to the customer each billing cycle, including a link to pay manually. | | `subscription_data.start_date` | This should be the next rent payment date. This should be a date in the format `YYYY-MM-DD`. | | `subscription_data.interval` | This should be the interval of the rent payment. This should be one of `month` or `week`. | | `subscription_data.interval_count` | This should be the number of intervals between rent payments. For example, if the rent is paid monthly, this should be 1. If the rent is paid every 3 months, this should be 3. | | `subscription_data.amount` | This should be the amount of the rent in the unit's currency. | | `subscription_data.description` | This should be a description of the rent. This is visible to the tenant on their invoice. | | `applicants[0].share_of_rent` | This should be an integer. For example, 100% share of rent should be 100. | You can add multiple applicants to a tenancy if there are multiple people sharing the rent. For each applicant increment the index of the `applicants` array. For example, the first applicant is `applicants[0]`, the second applicant is `applicants[1]`, and so on. The sum of all the `applicants[].share_of_rent` fields should be 100. Download the active tenancies import template. ## Invoices The invoice record is used to bill customers. #### Formatted fields The following fields need to be formatted to ensure that the data is imported correctly. | Field | Description | | :----------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer` | Must be the ID of the customer record you created in the customers import. | | `currency` | This should be a three letter currency code. For example, “gbp” for British Pound. | | `collection_method` | The collection method for the subscription. `charge_automatically` requires the customer to provide a payment method; charges are made automatically each billing cycle. `send_invoice` sends an invoice to the customer each billing cycle, including a link to pay manually. | | `unit` | This should be the ID of the unit record you created in the units import. | | `period_start` | This should be a date in the format `YYYY-MM-DD`. | | `period_end` | This should be a date in the format `YYYY-MM-DD`. | | `line_items[0].amount` | This should be a the amount to charge. | | `line_items[0].description` | This should be a description of the line item. | | `line_items[0].tax_percentage` | This should be the tax percentage for the line item. Should be a number between 0 and 100. | | `line_items[0].type` | This should be the type of the line item. Can be `rent`, `charge`, or `product`. | You can add multiple line items to an invoice. For each line item, increment the index of the `line_items` array. For example, the first line item is `line_items[0]`, the second line item is `line_items[1]`, and so on. Download the invoices import template. ## Subscriptions The subscription record is used to bill customers recurringly. #### Formatted fields The following fields need to be formatted to ensure that the data is imported correctly. | Field | Description | | :------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer` | Must be the ID of the customer record you created in the customers import. | | `currency` | This should be a three letter currency code. For example, “gbp” for British Pound. | | `collection_method` | The collection method for the subscription. `charge_automatically` requires the customer to provide a payment method; charges are made automatically each billing cycle. `send_invoice` sends an invoice to the customer each billing cycle, including a link to pay manually. | | `start` | This should be the next payment date. This should be a date in the format `YYYY-MM-DD`. | | `end` | This should be a date in the format `YYYY-MM-DD`. If the subscription is rolling, you can leave this blank. | | `interval` | This should be a string of the interval. Can be `month` or `week`. | | `interval_count` | The interval count of the subscription. For example, if the `interval` is `month` and the `interval_count` is `1`, the subscription will be billed every month. If the `interval` is `week` and the `interval_count` is `2`, the subscription will be billed every 2 weeks. | | `items[0].amount` | This should be a the amount to charge. | | `items[0].description` | This should be a description of the line item. | | `items[0].tax_percentage` | This should be the tax percentage for the line item. Should be a number between 0 and 100. | | `items[0].type` | This should be the type of the line item. Can be `rent`, `charge`, or `product`. | You can add multiple line items to a subscription. For each line item, increment the index of the `items` array. For example, the first line item is `items[0]`, the second line item is `items[1]`, and so on. Download the subscriptions import template. ## Account collections The account collection record is used to deduct funds from an owner's account, for example to charge a management fee, recover an expense, or collect a service charge. You can also import account collections directly in the Dashboard. See [CSV imports](/development/imports) for the self-serve import flow. #### Formatted fields The following fields need to be formatted to ensure that the data is imported correctly. | Field | Description | | :------------ | :------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | The type of the account collection. Can be `expense`, `fee`, or `service_charge`. | | `unit` | This should be the ID of the unit record you created in the units import that this account collection relates to. | | `owner` | This should be the ID of the owner record you created in the owners import. This is the owner whose account the funds will be deducted from. | | `description` | An arbitrary string describing the account collection. Often useful for displaying to users. | | `amount` | This should be the amount to charge in the smallest currency unit. For example, £400.00 should be 40000. | | `currency` | This should be a three letter currency code. For example, “gbp” for British Pound. | | `destination` | The ID of an owner account to allocate the collection funds to. Leave blank to allocate the funds to the platform account. | Download the account collections import template. # Yorlet Owners Source: https://docs.yorlet.com/owners Onboard landlords and suppliers, then route money to the right accounts. Owners is how you onboard landlords, leaseholders, and suppliers, then route money to them. Each owner has an account that can hold a balance, receive collections, and be paid out. Attach owners to units so rent and fees go to the right people. You can view and manage owners from the [Owners page](https://dashboard.yorlet.com/owners). ## Get started Choose the right owner account for a landlord, leaseholder, or supplier Collect identity verification information for your owner accounts Update the details on an owner account Use the owner account that represents your own platform Attach owner accounts to units to structure their ownership Split payments between your platform and owner accounts Debit an owner account for expenses, fees, or service charges ## Pay out owners See what each owner is owed or owes Pay an owner from their available balance Group payouts into a payment run and approve them together Collect and report tax on rental income for landlords who live abroad # Understanding owner account balances Source: https://docs.yorlet.com/owners/account-balances Learn how owner account balances work. Each owner account has its own, separate account balance. Owner accounts can have balances in four states: * **Pending**: meaning the funds are not yet available to pay out. * **Available**: meaning the funds can be paid out now. * **In transit**: meaning the funds are currently in flight to an owner via a payout. * **Reserve**: meaning the funds are currently held in reserve. When you transfer funds to an owner account, the amount is initially reflected in the pending balance. The funds become available based on when the funds from the original payment are received in your bank account. Once funds become available, they will be reflected in the available balance and paid out based on the [Owner Payout](/owners/owner-payouts) settings configured for the owner. ## Check an owner account’s balance You can check an owner’s current balance by navigating to the **Balance** section on an Owner record. ## Accelerating pending balances You can accelerate a pending transaction by clicking the overflow menu (•••) for the transaction on the **Transactions** tab of the **Balance** section. You can then edit the **Available on** date to modify the date when this transaction will be available to owners. ## Negative balances When you create collections or refund payments, an owner’s balance may become negative if they don’t have the funds to cover the actions. In such cases, you will have to wait for new payments to be made to the owner before they can be paid out. ## Send funds You can manually allocate payments to a owner's balance by using **Send funds**. Click the overflow menu (•••) on the **Balance** section of an Owner record, then click **Send funds**. You can allocate the payment to a specific unit and optionally apply those unit fees to the payment. ## Create an adjustment You can manually credit or debit an owner's balance with an adjustment. Click the overflow menu (•••) on the **Balance** section of an Owner record, then click **Create adjustment**. Choose the **Adjustment type** (**Credit** to increase the balance or **Debit** to decrease it), enter an **Amount** and a **Description** that will be visible to the owner, and optionally attribute it to a **Unit**. ## Download a statement To download a PDF statement of an owner's balance activity, click the overflow menu (•••) on the **Balance** section of an Owner record, then click **PDF statement**. ## Owner reserves In some cases, you may want to create reserves on an owner account to cover upcoming collections that will be made against their account. Reserved funds will be reflected in the reserve balance and can be held for an unlimited amount of time. ### Create an owner reserve Under the **Balance** section of an Owner record, click the overflow menu (•••), then **Reserve funds**. You can specify the amount to reserve and a description that will be visible to the owner. ### Release an owner reserve Navigate to the owner reserve you wish to release and click **Release funds**, you can specify the amount to release and a description that will be visible to the owner # Onboard accounts Source: https://docs.yorlet.com/owners/account-onboarding Let Yorlet collect identity verification information for your owner accounts. To ensure you remain compliant with local legislation around Know Your Customer (KYC) we need to collect identity verification information for your owner accounts. After you’ve created a new owner account you will need to complete the KYC requirements that are still outstanding. These requirements are based on the type of owner and whether they are a `company` or an `individual`. ## Onboarding Sessions The most efficient and secure way to gather identity verification data from owners is through Onboarding Sessions for Owners. These sessions are designed to manage the collection and identity verification of each owner’s information using a user-friendly web form hosted by Yorlet. The web form adapts dynamically according to the information still required. This not only reduces the complexity of managing sensitive data but also ensures that the information is accurate and up-to-date. Onboarding Sessions also provide a comprehensive verification process that includes the collection of identity documents and facial recognition technology to ensure that each owner is who they claim to be. This added level of security helps to protect against identity theft and fraud. ### Create an Onboarding Session Navigate to the owner you’d like to create an Onboarding Session for, then use the **Actions** menu and select **Create onboarding link**. You’ll be able to specify whether you’d like to send the link in an email or get the one-time link you can share with the owner. Please note these sessions expire after seven days, but you can always create another one if needed. ## Manually collect requirements If you’d prefer to collect the information manually you can do so by navigating to the owner and using the **Actions** menu to select **Edit information**. You can see all the outstanding requirements for the owner by hovering over the **Restricted** badge. ### Required information The required information is based on the type of owner and whether they are a `company` or an `individual`. The following table shows the minimum required information for an owner account. | Business type | Required information | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Individual | Email, address, date of birth, first name, and last name | | Company | Email, company legal name, company registration number, company address, representative’s address, representative’s date of birth, representative’s first name, and representative’s last name | ### Collecting identity verification information To collect identity verification information you’ll need to upload a copy of the owner’s identity document. You can do this by clicking the **Upload** button next to the **Identity document** field. You can then upload a copy of the document and click **Save**. ## Handle new requirements becoming due As local regulations evolve, we might be required to collect additional identity verification information from owners. In these cases we will add these requirements to the `eventually_due` field, we recommend either manually collecting these details or creating new Onboarding Sessions. # Choose an account type Source: https://docs.yorlet.com/owners/accounts Learn more about the different types of owner accounts you can use with Yorlet Owners. When using Owners, you can create a variety of accounts for different use cases. There are three account types you can use with Owners: * Landlord * Leaseholder * Supplier ## Landlord accounts A *Landlord* account should be used when you need to associate a unit with an ultimate beneficial owner. For example, when you manage a property on behalf of a landlord. ## Leaseholder accounts A *Leaseholder* account should be used when you wish to record the current occupier of a unit, this is usually used to then charge the leaseholder for service charges or ground rent. A leaseholder is someone who owns a property on a lease for a fixed length of time, but the freeholder will own the property outright. A leaseholder is also sometimes called a tenant, but this should not be confused with short-term agreements. ## Supplier accounts A *Supplier* account should be used when you want to charge collections to owner accounts that need to be paid out to a third party. For example, you might collect a maintenance charge from a landlord’s rental income and pay it out to the contractor who carried out the work. ## Business types It is important to choose the correct business type when creating an owner as this affects future requirements. They are: * `individual` - you will need to collect information about the person. * `company` - you will need to collect information about the company and its beneficial owners. This includes Limited Liability Companies, Limited Liability Partnerships, Trusts, and Public Companies. ## Create an account You can create a new owner account from the **Owners** tab of your Yorlet [Dashboard](https://dashboard.yorlet.com/owners). You must specify the account type and the business type. # Understanding fund flows Source: https://docs.yorlet.com/owners/fund-flows Learn how to split payments between your platform and owner accounts when you collect payments. ![title](https://res.cloudinary.com/djp21wtxm/image/upload/v1680656182/i1600x835-32O6wp-yhXed_ttvncf.png) ## Transfers Transfers allow you to move funds collected from payments to different owner accounts. We support a variety of use cases for fund movements. When creating invoices, subscriptions, or one-off payments, you can specify different transfer behaviours that dictate the fund flows of the payments. ### Transfer behaviours Yorlet supports three main transfer behaviours: * `automatic` - initiates transfers to owners of the supplied unit’s ownership structure. * `owner` - initiates transfers directly to a specific owner. * `none` - will not initiate any transfers. Yorlet recommends always using `automatic` when transferring rent payments to ensure that the current owners of the unit receive the funds. ### Automatic transfer behaviour Automatic transfers are recommended when you want to transfer funds based on the current ownership structure of a supplied unit. You can set up [Unit Ownership](/owners/unit-ownership) records to create these structures for accurately moving funds to the desired owner accounts. ### Owner transfer behaviour Owner transfers are recommended when you want to transfer funds to a single owner, regardless of the ownership structure of the unit. For example, you want to collect utilities from customers and need to allocate these funds to a supplier owner account. ## Collecting fees When initiating transfers you can collect fees on the transfer amount with [Collections](/owners/fund-flows/collections), this enables you to charge owners for services, like rent collection. When using the `automatic` transfer behaviour fees are automatically deducted from the owner based on the unit’s owner fees. For example: * An invoice for £1,200 is successfully paid * The associated unit has the management fee set to 10% * The line item of the invoice has the type `rent` and is set to `automatic` transfer * Yorlet initiates a transfer to the owner of the unit * An owner payment is created on the destination owner account * Yorlet creates a collection for £120 from the owner based on the unit’s management fee * Your platform balance is credited by £120, the amount collected from the owner’s balance ## Transfer events This table illustrates the events and resources that are created when transferring funds: | Event | Resource | | ------------------ | ------------------------------------------------------- | | Payment succeeds | Transfer created | | Transfer succeeds | Owner Payment created | | Owner Payment paid | Owner Balance Transaction created for the Owner Payment | | Owner Payment paid | Collection created due to unit’s fee settings | | Collection applied | Owner Balance Transaction created for the Collection | ## Reversing transfers You can reverse a transfer to correct a misallocation of funds to an owner’s balance. You can do this by navigating to the transfer you wish to reverse and clicking **Reverse** in the top right. You can then specify the amount to reverse and add a note about the details of the reversal. ## Refunding payments When you refund payments collected through Yorlet Payments, Yorlet will also reverse the associated transfers to owners and refund any collections made against those transfers’ destination owner payments. # Charging owners Source: https://docs.yorlet.com/owners/fund-flows/collections Learn how to charge owner accounts to debit their balances. At times, you may need to collect funds from your owner accounts: * To charge the owner account for your services * To collect payments on behalf of suppliers, like maintenance expenses or service charges When collecting from Landlord, Leaseholder, or Supplier accounts, you can create collections to debit their balances and either credit your Platform account or transfer funds to another owner account. ## Creating a collection To create a collection, follow these steps: 1. Navigate to the owner account you want to create a collection for 2. Under the **Balance** section, click on the overflow menu (•••) and select **Create collection** 3. Fill out the required fields including amount, description, and tax percent 4. You can specify a destination for the collection, this will create an owner payment to transfer the funds from one owner to another 5. You have the option to toggle **Collect now**. Toggling this on will immediately apply the collection to the balance, regardless of whether the owner has available funds to cover it. Alternatively, you can toggle it off and the collection will remain in a pending state until you approve it. ## Approving collections If you created a collection with **Collect now** toggled off, it remains in a `pending` state until you approve it. To approve a collection, navigate to the collection and click **Approve**. Once approved, the collection is applied to the owner's balance. ## Platform fees You can earn commission on the payments you collect from owner accounts by setting the platform fee percentage. The owner will see the full amount in their account and then the payment will be split between the destination and platform account. ## Updating collections You can update a collection by navigating to the collection you wish to update and clicking **Edit** in the top right of the **Summary** section. You can then update the description, period, and unit. ## Cancelling collections Cancelling a collection removes the balance transaction from the owner’s balance. You can do this by navigating to the collection you wish to cancel and clicking **Cancel** in the top right. You can only cancel a collection when it is either in a `pending` or `applied` state. ## Refunding collections You can refund a collection after it has been `applied` or `paid`. You can do this by navigating to the collection you wish to refund and clicking **Refund** in the top right. You can then specify the amount to refund and add a description about the details of the refund. Refunding a collection that was created with a destination owner account will also refund the destination owner payment that credited the destination owner balance. To download a tax invoice for a collection, navigate to the collection and click **Tax PDF**. ## Manage recurring collections For charges you need to collect on a regular basis, such as a recurring management fee, you can use a recurring collection. A recurring collection automatically creates a new collection on a set frequency, and the collections it creates behave just like the ones you create manually. You can view your recurring collections on the [Subscriptions page](https://dashboard.yorlet.com/owners/subscriptions) in the Owners area. Each recurring collection shows its **Owner**, **Amount**, **Frequency**, billing cycles and the **Next collection** date, along with a list of the **Collections** it has created. Recurring collections are set up for you through the Yorlet API rather than from the Dashboard. Once created, you can manage them from the Dashboard. To update a recurring collection, navigate to it and click **Edit**. You can change the **Amount** and **Description** used for future collections. To stop a recurring collection from creating any further collections, navigate to it and select **Cancel subscription**. # Owner payouts Source: https://docs.yorlet.com/owners/owner-payouts Learn how Yorlet manages payouts for your owner accounts. Yorlet enables you to pay out funds from your owner account balance to an external account. You can create payouts for any owner account that has a balance. You can also create payouts for your platform owner account. ## Payout lifecycle A payout moves through the following statuses: | Status | Description | | :----------------- | :---------------------------------------------------------------------------------------------- | | `draft` | The payout has been created but not yet approved. | | `pending` | The payout has been approved and is awaiting payment. | | `requires payment` | The payout is waiting to be paid, for example as part of a [payment run](/owners/payment-runs). | | `in transit` | The funds are on their way to the owner's bank account. | | `paid` | The payout has been paid. | | `failed` | The payout could not be paid. | | `cancelled` | The payout was cancelled before it was paid. | You can review payouts grouped by these statuses on the [Payouts page](https://dashboard.yorlet.com/owners/payouts). ## Bank accounts To create a new bank account for an owner, follow these steps: 1. Navigate to the owner account you want to create a bank account for. 2. Under the **Payout information** section, click **Add**. 3. Fill out the information, there are different requirements for each country. You can also use [Onboarding Sessions for Owners](/owners/account-onboarding) to allow owners to securely provide their bank information themselves through an online portal. ### Multiple bank accounts By default, Yorlet will pay out funds to the external account that you have specified on the owner account. If you need to generate payouts for specific units, you can override the external account for each unit and create payouts for multiple destinations. To do this, navigate to the Unit Ownership page and select the unit for which you want to override the external account. Then, add a bank account to be used for payout generation. ## Automatic payouts By default, Yorlet is configured to automatically process payouts on a daily rolling basis. This means that when payments are transferred to owner balances and accumulate, Yorlet will automatically create a new draft payout every day for owners with a positive balance. This automatic scheduling controls when draft payouts are created. It is separate from the **Automatic** payout method, which pays owners from the funds held in your balance and requires the [Balance](/balance) plan. See [automatic owner payouts](/balance/automatic-owner-payouts). ### Payout schedule You can configure the payout schedule for each owner individually. There are four possible scheduling settings: * **Manual**: prevents automatic payouts. You will have to manually pay out the owner’s balance. * **Daily**: automatically pays out charges after they become available in the owner’s balance. * **Weekly**: automatically pays out the balance once a week, on a specified day. * **Monthly**: automatically pays out the balance once a month, on a specified day. Payouts scheduled between the 29th and 31st of the month are instead sent on the last day of a shorter month. To configure these settings, go to the **Payout information** section of the owner account. ### Automatic approvals By default, new payouts remain in the `draft` state until they are manually reviewed and approved. However, you have the option to enable automatic approvals for the owner’s account, which will approve new payouts automatically. This is an advanced setting that automates the payout approval process. We recommend ensuring that all your fees are correctly configured before enabling this setting. To configure these settings, go to the **Payout information** section of the owner account. ### Payout transaction grouping You can configure how you’d like to handle payouts for multiple units. The transaction grouping options are: * **All**: will generate a single payout for all units. * **Per unit**: will generate a payout for each unit. To configure these settings, go to the **Payout information** section of the owner account. ## Manual payouts To create a manual owner payout, follow these steps: 1. Navigate to the owner account you want to create a payout for. 2. Under the **Balance** section, you can click on the overflow menu (•••) and select **Create payout**. 3. Fill out the information. When specifying a unit, the payout will be generated only for that unit. If you do not specify a unit, the payout will be generated for all units. ## Manage a payout Open a payout to review its summary and take action on it. The available actions depend on the payout's status: * **Approve payout**: approve a `draft` payout, which moves it to `pending`. When approving, you choose the **Payout method**: **Automatic** (Yorlet pays the owner from your client funds) or **Manual** (you pay the owner outside Yorlet). The **Automatic** method requires the [Balance](/balance) plan; see [automatic owner payouts](/balance/automatic-owner-payouts). Without the plan, only **Manual** is available. * **Pay payout**: pay an approved automatic payout from your client funds. * **Mark as paid**: record that a manual payout has been paid outside Yorlet. You can set the date it was paid and choose whether to send a receipt. * **Mark as failed**: record that a manual payout could not be paid. You can add a failure message and optionally flag the destination bank account as errored. * **Cancel payout**: cancel a `draft` or `pending` payout. On the payout page you can use keyboard shortcuts: `a` to approve, `p` to pay or mark as paid, `f` to mark as failed and `c` to cancel. ### Failed payouts If a payout fails, the funds remain in the owner's balance so you can resolve the issue, for example by [updating the owner's bank account](/owners/updating-accounts#update-payout-bank-accounts), and pay them out again. ## Payout receipts When a payout is successfully marked as paid, we will send confirmation to the owner’s email address along with a PDF receipt of the funds detailing all the transactions that were included in the payout. # Payment runs Source: https://docs.yorlet.com/owners/payment-runs Manage payment runs for your owner payouts. Payment runs are a convenient way to pay your owners in bulk rather than having to make individual payments. You can easily track and manage your payments in one place, avoid errors, and ensure that your owners are paid accurately and on time. ## Create a payment run You must have some owner payouts in the pending state to create a new payment run. Learn more about [Owner Payouts](/owners/owner-payouts). To create a payment run, navigate to either the **Payment runs** or **Payouts** tab under the **Owners** section of the navigation menu and click **New payment run**. Yorlet will group all pending owner payouts that are not currently attached to a payment run. When creating a payment run, you can choose: * **Method**: **Manual** to export the payouts and pay them through your bank, or **Automatic** to have Yorlet pay them from your client funds. * **Type**: which owners to include - **All**, **Landlords** or **Suppliers**. * **Region**: **All**, **Domestic** or **International**. For manual payment runs, you can download a Bacs file, Sage file, or create a CSV export to upload to your bank to make the bulk payments. ## Approve a payment run A new payment run is created with the status **Requires approval**. To process it, open the payment run and click **Approve**. You will see a summary of the client funds being paid out across the included payouts, then confirm with **Pay** to release the payments. ## Managing payment runs Each payment run includes a summary of the total amount of the payment run and the status of each payout. Once you receive confirmation of the payout status, you can mark each payout as `paid`, `failed`, or `canceled`. # Platform owner accounts Source: https://docs.yorlet.com/owners/platform-accounts Learn about the owner account for your platform. When Yorlet Owners is enabled for your account we will automatically provision your account with a platform owner account. This account serves as the default destination for collections when no other destination is provided. This account enables you to receive funds deducted from owners for fees, expenses, and non-resident tax charges. You can make payouts from this account just like other owner accounts. However, these payouts describe money movements from your client account to your business account for fee payouts or payments to local tax authorities. ## Differences to other owner accounts The owner accounts for your platform are essentially the same as other owner accounts. However, there are some key differences: * You cannot create new platform owner accounts yourself, they are provisioned by Yorlet when Owners is enabled. * You can only have one platform owner account. * You cannot create collections against the platform account that move funds from the platform account balance to other owner accounts. * You can use Owner Payment Refunds to return collected funds to other owner accounts. * You can attach multiple external accounts for payouts. * You do not need to provide full identity verification information to enable payouts. ## Viewing your platform owner account You can find your platform owner account in the **Platform owner balance** section under the **Balance** tab of your Yorlet [Dashboard](https://dashboard.yorlet.com/balance). ## Moving money Use [Owner Payouts](/owners/owner-payouts) to pay out funds from your platform owner account balance to an external account. See [Creating an owner payout](/owners/owner-payouts#manual-payouts) for more information. # Tax reporting Source: https://docs.yorlet.com/owners/tax-reporting Collect and report tax on rental income for landlords who live abroad. HM Revenue & Customs requires you to collect tax on rental income for landlords who live abroad. Yorlet automatically tracks the tax collected on behalf of your non-resident landlords and prepares the forms you need to report and pay it, under the Non-resident Landlord (NRL) scheme. ## Set up tax reporting Before you can file, add your scheme details in the Dashboard. To configure tax reporting, follow these steps: 1. Go to your [tax reporting settings](https://dashboard.yorlet.com/settings/owners/tax-reporting). 2. Enter your **Reference number**. This is your HMRC reference number for tax reporting. 3. Enter your **Signature**. This is the digital signature used on your tax filings. 4. Click **Save**. ### Route non-resident tax collections You can choose which owner account receives the tax you collect from non-resident landlords. In your [routing settings](https://dashboard.yorlet.com/settings/owners/routing), under **Non resident tax collections**, select the owner to route these collections to. If you leave it empty, they are routed to your platform account. Yorlet identifies non-resident landlords from the tax residency you set on the landlord's owner account. Learn more about [account types](/owners/accounts). ## Tax forms Yorlet generates a tax form for each report you need to submit. You can view and manage them on the [Tax forms page](https://dashboard.yorlet.com/owners/tax-forms). Tax forms are organised into tabs by status: * **Needs attention**: the form has outstanding items before it can be filed. * **Ready**: the form is ready to be filed. * **Filed**: the form has been submitted. Yorlet produces the following form types: | Type | Description | | :----- | :--------------------------------------------------------------------- | | `NRL6` | The annual certificate provided to each landlord showing tax deducted. | | `NRLQ` | The quarterly return of tax collected. | | `NRLY` | The annual return of tax collected. | ## View and download a tax form To view a tax form, select it from the [Tax forms page](https://dashboard.yorlet.com/owners/tax-forms). The form shows its type, period, the owner it relates to, and the amounts **Collected** and **Refunded**. To download a copy of the form, click **Download report**. ## Delete a tax form You can only delete a tax form that has not been filed. To delete a tax form, follow these steps: 1. Navigate to the tax form you want to delete. 2. Use the and select **Delete**. # Unit ownership Source: https://docs.yorlet.com/owners/unit-ownership Learn how to attach owner accounts to units to structure their ownership. Unit ownerships help you structure how [funds flow](/owners/fund-flows) to owner accounts, it is important to take time to set these up correctly as they will power automatic transfers for rent collection and other billing mechanisms. ## Setting up ownership structures There are two ways to set up the ownership structure for a unit: * Create a unit * Attach an owner to a unit ### Create a unit with an owner See the [create a unit](/real-estate/units) documentation to see how to create a unit with an owner. ### Attach an owner to a unit Navigate to the owner you’d like to attach to a unit, then in the **Unit ownerships** section click **New**. Choose the unit you’d like to attach the owner to from the **Unit** list, you can also search for the unit. Once selected, you will see the unit’s current owners if there are any, and the owner you started from will be pre-populated in the **Owners** list. Use **Add owner** to attach any additional owners, and set each owner’s **percentage ownership**. Click **Add unit** to complete the change. #### Units with multiple owners When attaching or changing owners, use **Add owner** to add additional owners and set their payout split. The **Total ownership** must add up to 100%; use **Split equally** to divide it evenly across the owners. If you have multiple owners but only one owner receives payments, make sure you set that owner’s split to 100% and the others to 0%. ## Managing unit ownerships To change the ownership structure of a unit or an owner’s percentage ownership of a unit, you need to initiate a change of ownership. Navigate to the unit you’d like to change the owner for, then either use the overflow menu (•••) and select **Change ownership**, or click **Change owner** in the **Owners** section. You will see the unit’s current owners if there are any. Under **New owner**, choose one of the following: * **Account**: remove the current owner(s) and set the unit’s ownership to your own account. * **Landlord owner**: assign the unit to one or more owner accounts. Use **Select an owner** to choose each owner, **Add owner** to add more, and set each owner’s **percentage ownership** (the **Total ownership** must add up to 100%, and **Split equally** divides it evenly). When changing to landlord owners, you can also use these options: * **Carry over previous details**: for owners who already own this unit, carry over their bank account, assignee, and delivery details from their previous record instead of resetting them. * **Property management agreement**: optionally create a new PMA for the owners by choosing a contract template. If a property management agreement is created, the owners will have to be manually activated once an agreement is reached. Under **Ending current ownership**, you can control how the outgoing ownership is ended: * **Ownership ends at**: select a future date to end the ownership later. If left empty or set to a past date, the ownership ends immediately. * **Reason for ending**: choose why the ownership is ending, such as **Lost instruction**, **Sold unit**, **Moved in**, **Lost negotiation**, or **Other**. * **Description**: optionally add more detail about why the ownership is ending. * **Send email**: optionally notify the departing owner(s) of their notice period by email. Click **Confirm change of owner** to complete the change. ## Archiving unit ownership records Navigate to the unit you’d like to archive the current ownership records for, then use the overflow menu (•••) and select **Change ownership**. Under **New owner** select **Account**, this will remove the current owners from the unit. Click **Confirm change of owner** to complete the change. When you change the owners of a unit, any current owners attached to the unit will be automatically archived once the change is completed. To view archived ownership records, navigate to a unit and open the **Archived** tab in the **Owners** section. ## Owner fees This section shows the current owner fees for the unit. You can add a Management fee, Tenant find fee, Renewal fee, and a Tax rate to use for these prices. The tax rate can be set to `exclusive` or `inclusive`. To modify these details, click Edit. # Updating accounts Source: https://docs.yorlet.com/owners/updating-accounts Learn how to update the details of your owner accounts. You can update an owner account at any time to keep their details, contact information and payout destination up to date. ## Update owner details To update an owner's details, follow these steps: 1. Navigate to the owner you'd like to update. 2. Use the **Actions** menu and select **Edit information**. 3. Update the owner's details and save your changes. The fields you can change depend on the owner's business type: * **Individual**: email, first and last name, date of birth, address and phone number. * **Company**: email, legal name, company number, VAT number, address and phone number. For landlords, you can also update their tax residency, which determines whether [tax reporting](/owners/tax-reporting) applies to their rental income. If an owner is missing information required for payouts or identity verification, their account shows as `Restricted`. You can supply the outstanding details from **Edit information**, or send the owner an [onboarding link](/owners/account-onboarding) to collect it. ## Update payout bank accounts An owner's payout destination is managed separately from their personal details. To add a bank account, navigate to the owner, and under the **Payout information** section click **Add**, then complete the bank details (the requirements vary by country). You can also let owners provide their own bank details through an [onboarding link](/owners/account-onboarding). To pay out specific units to different accounts, see [multiple bank accounts](/owners/owner-payouts#multiple-bank-accounts). # Payments Source: https://docs.yorlet.com/payments Accept payments, save payment methods, issue refunds, and respond to disputes. Payments is how money comes into Yorlet. Collect a one-off amount, send a customer a link to pay, save a payment method for later, and refund when you need to. The same payment methods work across [invoices](/billing/invoices), [applications](/leasing/applications), and [owner collections](/owners/fund-flows/collections). ## Get started Charge a saved payment method for a one-off amount Send a customer a link to pay without handling card details Cards, Direct Debit, bank transfers, and other ways customers can pay Refund a payment in full or in part Respond to chargebacks and submit evidence to the bank # Accept a payment Source: https://docs.yorlet.com/payments/accept-a-payment Charge a saved payment method for a one-off amount. You can charge a customer's saved payment method for a one-off amount, whether that's a card, direct debit or a [bank transfer](/payments/payment-methods/bank-transfers) with a [remaining balance](/customers/remaining-balances). If the customer does not have a payment method on file, send them a [payment session](/payments/payment-sessions) instead so they can pay without you handling their details. Use a [payment session](/payments/payment-sessions) when you do not already have a payment method on file. ## Create a payment Make sure you have the customer's permission to charge their payment method. There are three ways to open the **Create payment** sheet: * **From the customer** — Navigate to the customer, open the **Actions** menu and select **Create payment**. * **From a bank transfer payment method** — Navigate to a bank transfer payment method with a remaining balance and click **Charge balance** in the header. * **From the Remaining balances page** — On the [Remaining balances page](https://dashboard.yorlet.com/customers/balances), right-click a row and select **Charge balance**. Then, in the **Create payment** sheet: 1. If it isn't already set, choose the **Customer** to charge. 2. Enter the **Amount**, **Currency** and **Description**. 3. Select the **Payment method** you'd like to charge. Chargeable cards, direct debits and bank transfers with a remaining balance all appear here. 4. Click **Create payment**. Once the payment is created you'll be taken to the Payment record to track its status. ### Advanced options Choose whether to send an email receipt to the customer after the payment is successful. Credit the transaction amount to the customer's balance so it can be used to settle a future invoice. You can optionally add a **Balance description** to explain the credit on the customer's statement. # Disputes Source: https://docs.yorlet.com/payments/disputes Respond to payment disputes, submit evidence to the cardholder's bank, and recover funds. A dispute (also called a chargeback) is raised when a customer questions a payment with their bank. The bank can return the funds to them, and you have a limited time to send evidence that the charge was legitimate. You can review and respond to disputes from the [Disputes page](https://dashboard.yorlet.com/disputes). Card disputes can be contested with evidence. [Bacs](/payments/payment-methods/bacs-debit) and [SEPA](/payments/payment-methods/sepa-debit) Direct Debit disputes are final and cannot be appealed. ## What happens when a payment is disputed When a dispute is created: * The disputed amount is deducted from your balance, usually within 24 hours. * A dispute fee is deducted for card and SEPA Direct Debit disputes. See [Fees](#fees). * If the payment was for an invoice, the invoice is marked with a late payment failure. * If the funds had already been paid out to an owner, a transfer reversal is created. * Admins receive an email and a Dashboard notification with a link to the dispute. The original payment stays on the [Payments page](https://dashboard.yorlet.com/payments) and shows a link to the dispute. If the dispute needs a response, you have until the evidence due date to submit evidence. Three days before that deadline, admins receive a reminder email. Once the deadline passes, you can no longer submit evidence. Refund a payment you agree was made in error before the customer disputes it. A [refund](/payments/refunds) is faster and cheaper than a chargeback, and there is no dispute fee. ## View disputes To open a dispute, follow these steps: 1. Go to the [Disputes page](https://dashboard.yorlet.com/disputes) under **Payments**. 2. Use the **Unresolved** and **Resolved** tabs, or open a dispute from the related payment. 3. Optionally assign a team member so it is clear who is responding. The dispute shows the amount, fee, reason, customer, and the related payment and invoice. A timeline tracks when the dispute was created, when evidence is due, and when it is under review. ## Dispute statuses | Status | Description | | ------------------------ | ---------------------------------------------------------------------------------------------------------- | | Needs response | You can still submit evidence. Respond before the due date. | | Evidence submitted | Your evidence has been sent to the cardholder's bank. A decision can take up to three months. | | Won | The bank found in your favour. The disputed amount is returned to your balance. | | Lost | The bank found in the customer's favour. The deducted funds are not returned. | | Warning - needs response | An early enquiry from the card network. Funds are not withdrawn yet, but you should still review the case. | | Warning - under review | The warning is being reviewed. | | Warning - closed | The warning was closed without becoming a full dispute. | ## Respond to a card dispute You can add evidence while the status is **Needs response**. Save your progress as you go, then submit once everything is complete. You can only submit once: after that, the evidence cannot be changed or sent again. To add evidence, follow these steps: 1. Open the dispute. 2. Click **Manage evidence**. 3. Upload documents and fill in the details that support your case. Click **Save evidence** to keep your progress. 4. When you are ready, close the evidence sheet and click **Submit evidence**. 5. Confirm that the evidence is complete, then click **Submit evidence** again. Once submitted, the evidence cannot be changed or resubmitted. Make sure everything is complete before you confirm. **Submit evidence** stays disabled until at least one document or detail has been saved. ### Documents Upload PNG, JPEG, or PDF files. Use the category that matches the file: | Field | What to upload | | -------------------------- | ------------------------------------------------------------------------------------------------------- | | **Customer communication** | Emails, messages, or letters with the customer about the payment, property, or tenancy. | | **Refund policy** | The refund or cancellation policy the customer agreed to. | | **Service documentation** | Proof the service was provided: a signed tenancy or licence, the invoice, check-in records, or similar. | ### Details | Field | What to write | | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | | **Why should you win this dispute?** | A clear, concise explanation of why the charge is legitimate. This is the narrative the bank reads first. | | **Product description** | What the customer paid for, for example a month's rent at a named property, a holding deposit, or an application fee. | | **Refund policy disclosure** | How and when the customer was shown your refund policy before they paid. | | **Refund refusal explanation** | Why they are not entitled to a refund, if they asked for one. | | **Service date** | The date the service was provided, such as the tenancy start date or the first day of the rent period. | ## Evidence best practice Banks review a high volume of cases and often decide from the written explanation plus a few supporting documents. Strong evidence is specific, dated, and tied to this customer and this charge. * Respond before the due date. Late evidence is not accepted. * Address the dispute reason. Fraud evidence is different from a refund complaint. * Write in plain English. State what was paid for, when, by whom, and why the charge is valid. * Use names, dates, amounts, and addresses that match the Customer, Invoice, and payment. * Prefer a signed tenancy or licence, the invoice, and emails from the customer's own address over generic policy text. * Keep scans readable. Crop to the relevant pages; do not upload an entire unsearchable pack. * Do not argue, threaten, or include unrelated complaints. Stick to facts the bank can verify. Requiring [3D Secure](/payments/fraud-prevention) on card payments makes fraudulent disputes harder to win against you, because liability often shifts to the customer's bank. ### What to include by reason The customer (or someone using their card) told the bank they did not make or recognise the payment. Include: * The signed tenancy, licence, or application in the customer's name. * Emails or messages from the customer arranging the property, viewing, or payment. * The invoice and payment receipt. * Proof they occupied or used the property, such as a check-in record or key handover. * In **Why should you win this dispute?**, explain that the named customer authorised the payment for a specific property and period. The customer claims they were owed a refund that never arrived. Include: * Your refund policy and **Refund policy disclosure** showing they saw it before paying. * **Refund refusal explanation** if they were not entitled to a refund (for example the rent period had already started). * If you already refunded them, proof of that refund: date, amount, and destination. The customer claims they did not receive what they paid for. Include: * **Service date** and **Service documentation** showing the tenancy started or the rent period was provided. * The tenancy or licence agreement. * Communication that they collected keys, moved in, or otherwise used the property. * **Product description** naming the property and the period covered by the charge. The customer claims they were charged twice, or that a recurring payment continued after they cancelled. Include: * The invoices that show each charge was for a distinct period or product. * If two payments were made in error, refund the duplicate rather than fighting both disputes. * For recurring rent, the subscription or tenancy dates and any cancellation notice you received, with when it took effect. ## Direct Debit disputes [Bacs Direct Debit](/payments/payment-methods/bacs-debit) and [SEPA Direct Debit](/payments/payment-methods/sepa-debit) disputes are final. There is no evidence process and no appeal. If a Direct Debit is disputed: * The payment is marked `lost`. * Contact the customer to resolve it directly. * If you agree a repayment, [create a new payment](/payments/accept-a-payment). Bacs Direct Debit is widely used for rent. Fraudulent Direct Debit disputes are uncommon; when one happens, recover the funds with the customer rather than through the bank. ## After you submit The dispute moves to **Evidence submitted**. The cardholder's bank reviews the case, which can take up to three months. The dispute status updates to **Won** or **Lost** when the bank decides. * **Won**: the disputed amount is returned to your balance. The dispute fee is not refunded. * **Lost**: the deducted funds stay with the customer. You can add internal comments on the dispute for your team at any time. These are not sent to the bank. ## Mark a dispute as resolved **Mark resolved** takes the dispute off your **Unresolved** list in Yorlet. It does not change the bank's decision. You cannot mark a dispute resolved while it still needs a response. Card disputes that the bank has decided are usually resolved for you. Use **Mark resolved** when you have finished working a case that is no longer awaiting evidence — for example a Direct Debit dispute, or a card dispute already under review. Marking a dispute resolved cannot be undone. To mark a dispute as resolved, follow these steps: 1. Open the dispute. 2. Click **Mark resolved**. 3. Click **Resolve** to confirm. ## Fees The disputed amount is withdrawn when a full dispute is created (not for a warning). An additional dispute fee applies to some payment methods: | Payment method | Dispute fee | | ----------------- | -------------------------------------------------- | | Cards | £20.00 (or the equivalent in the payment currency) | | SEPA Direct Debit | €7.50 | | Bacs Direct Debit | No additional dispute fee | The fee is shown on the dispute as **Fee**. It is not returned if you win. # Fraud prevention Source: https://docs.yorlet.com/payments/fraud-prevention Learn how to prevent payment fraud using Yorlet. Yorlet Payments includes real-time fraud protection and requires no additional setup or third party integration. ## 3D Secure liability shift When a business triggers 3DS verification, liability for fraud shifts from the business to the issuer in most cases. This applies whether or not your Issuing cards are enrolled in 3DS, meaning issuers can take on increased liability without any additional verification. ### Require 3D Secure for application card payments We recommend that you rely on our SCA Engine to automatically prompt your customers for authentication based on risk level and other requirements. However, if you wish to request 3D Secure authentication for all application payments, you can. To manage this setting, follow these steps: 1. Navigate to **Settings** > **Leasing** > **[Payments](https://dashboard.yorlet.com/settings/leasing_payments)**. 2. To enable the setting, toggle on **Require 3D Secure**. Enabling this setting will require all payments to be authenticated with 3D Secure, potentially resulting in lower authorisation rates. If a customer still raises a chargeback, you can [submit evidence](/payments/disputes) to contest it. # Payment methods Source: https://docs.yorlet.com/payments/payment-methods Learn about the different supported payment methods. We currently support over 20 different payment methods that cover 135+ currencies, and we’re continuing to add more based on customer demand. Enabling an additional payment method is as simple as clicking a button. We automatically present your customers with the available methods based on the currency you’re charging in. ## Manage payment methods To manage your payment methods, follow these steps: 1. Navigate to **Settings** > **Payment methods**. 2. To enable a payment method, click **Turn on**. 3. Clicking on a payment method will expand it’s card, showing you more information about the method. 4. If you want to use the payment method for invoice payments, you’ll need to click **Turn on** in the invoice payments section of a payment method’s card. You can easily see at a glance which payment methods you have enabled, and whether they can be used for invoice payments. ## Cards Cards are a popular way for consumers to make payments online. Yorlet supports global and local card networks. Learn more about [supported cards](/payments/payment-methods/cards). | Global | Europe | US and Canada | Asia | | :--------------- | :--------------- | :------------ | :-------------- | | Visa | Cartes Bancaries | Discover | JCB | | Mastercard | | | China Union Pay | | American Express | | | | | Diners | | | | ## Bank debits Bank debits are commonly used for high-value payments like rent. The business can debit the customer’s bank account directly without having to rely on them pushing funds. | Global | Europe | US and Canada | Asia | | :----- | :-------------------------------------------------------- | :--------------- | :---------------- | | — | [Bacs Direct Debit](/payments/payment-methods/bacs-debit) | ACH Direct Debit | BECS Direct Debit | | | [SEPA Direct Debit](/payments/payment-methods/sepa-debit) | | | | | [Autogiro](/payments/payment-methods/autogiro) | | | ## Bank redirects Bank redirects let customers pay online using their bank account. | Global | Europe | US and Canada | Asia | | :----- | :------------------------------------------------------------------------------------------ | :------------ | :--- | | — | [Pay by Bank](/payments/payment-methods/pay-by-bank) (UK)Beta | — | — | ## Bank transfers Customers can use bank transfers to send money to a virtual bank account set up by Yorlet to reconcile payments automatically. Learn more about [bank transfers](/payments/payment-methods/bank-transfers). | Global | Europe | US and Canada | Asia | | :----- | :----------------- | :------------ | :--- | | — | UK Bank Transfer | — | — | | | SEPA Bank Transfer | | | ## Direct transfers Customers pay online via their bank account directly into the platform’s client account. These payments happen outside of Yorlet. Learn more about [direct transfers](/payments/payment-methods/direct-transfers). | Supported country | Currency | | :----------------------------------------------- | :------- | | Sweden | EUR, SEK | | United KingdomBeta | GBP | ## Wallets Customers can use wallets to pay with a saved card. This provides a fast and secure way to pay and reduces fraud. | Global | Europe | US and Canada | Asia | | :-------------------------------------------- | :----- | :------------ | :----------------------------------------------------------------------------------- | | [Apply Pay](/payments/payment-methods/cards) | — | — | [Alipay](/payments/payment-methods/alipay)Beta | | [Google Pay](/payments/payment-methods/cards) | | | [WeChat Pay](/payments/payment-methods/wechat-pay)Beta | # Alipay Source: https://docs.yorlet.com/payments/payment-methods/alipay Accept Alipay, a popular wallet in China. Alipay lets customers in China pay from their Alipay wallet. This payment method is in beta. ## Request early access If you would like early access, contact sales. # Autogiro Source: https://docs.yorlet.com/payments/payment-methods/autogiro Learn about Autogiro, one of the most common bank-to-bank transfers in Sweden. Autogiro is a popular method for collecting payments in Sweden. ## Timing Autogiro payments work on a 11 business day cycle. This table illustrates the timings for a Autogiro payment: | Day | Event | | ------ | ---------------------------------------------------------------------------- | | Day -8 | This is the last day you can send a notification of payment to your customer | | Day 0 | The funds leave the customers account | | Day 3 | The funds settle to your account | ## Request early access This feature is currently in beta, if you would like early access please contact sales. # Bacs Direct Debit Source: https://docs.yorlet.com/payments/payment-methods/bacs-debit Learn about Bacs Direct Debit, one of the most common bank-to-bank transfers in the UK. Yorlet users in the UK have the ability to receive Bacs Direct Debit payments from customers who have a UK bank account. This means you can offer a secure and convenient payment option for your customers, who can easily authorise payments without having to manually initiate them every time. ## Collect a Bacs Direct Debit To collect a Bacs Direct Debit payment method, follow these steps: 1. Navigate to the customer account for which you want to collect the payment method. 2. Under the **Payment methods** section, click **Collect payment method**. 3. Choose the **Bacs Direct Debit** payment method type. You can also select multiple methods or just one; the customer will only be able to supply one method in the session. 4. Optionally, you can choose an active subscription to allocate the payment method to. This will update the subscription’s default payment method and set the collection method to **Charge automatically**. 5. Optionally, you can choose to send the collection link to the customer’s email. 6. Click **Create**. 7. Share the collection link with your customer. ## Timing Bacs Direct Debit payments work on a 3 business day cycle. It takes 4 business days to confirm the success or failure of a Bacs Direct Debit payment when a mandate is already in place, and 7 business days when you must collect a new mandate. Occasionally, Bacs Direct Debits can fail even if they have been marked as paid in your Yorlet account. In such cases, a dispute is created for the payment, with the reason code we receive from the network. If the payment is for an invoice, the invoice will be updated to show the late payment failure, and a new invoice will be created automatically to recover the funds. This table illustrates the timings for a Bacs Direct Debit payment, in business days from the time (T) that a payment is made when a new mandate must be collected: | Day | Event | | ---------------- | --------------------------------------------------------- | | T (before 20:00) | The payment is submitted | | T + 2 | The funds leave the customer's account | | T + 3 | The funds settle to your Yorlet merchant account | | T + 4 | The payment is confirmed as successful (existing mandate) | | T + 7 | The payment is confirmed as successful (new mandate) | ## Notifcations The Bacs Direct Debit scheme requires customers be notified about the follwing events: * When payment details are collected and the mandate is submitted * Every time a payment is submitted Yorlet automatically handles sending these emails to your customers. ## Disputes Bacs Direct Debit disputes are final and cannot be appealed. If a customer successfully disputes a payment, you must contact them to resolve the dispute. If you’re able to come to an agreement and your customer is willing to return the funds, you can [create a new payment](/payments/accept-a-payment). See [Disputes](/payments/disputes) for how disputed payments appear in the Dashboard. Bacs Direct Debit is one of the most popular methods used by Yorlet customers in the UK to collect rent. Although there is risk associated with accepting Bacs Direct Debit for rent payments, fraudulent disputes are extremely rare and in the event of a dispute, we work with customers to recover funds. ## Refunds Refunds for payments made with Bacs Direct Debit must be requested within 180 days of the original payment. Refunds usually take 3-4 business days to be processed. If you accidentally charge your customer, please contact them right away to prevent a payment dispute. Learn how to [create a refund](/payments/refunds). # Bank Transfers Source: https://docs.yorlet.com/payments/payment-methods/bank-transfers Learn about Bank Transfer payments, a simple way to receive funds directly from your customers' bank accounts. Bank transfers allow customers to send funds directly from their bank account to a bank account. This payment method is ideal for one-off payments, large transactions, or customers who prefer not to set up recurring payment mandates. ## Create a bank transfer payment method To create a bank transfer payment method, follow these steps: 1. Navigate to the customer account for which you want to create the payment method. 2. Under the **Payment methods** section, click **Add bank transfer account**. 3. Click **Add**. 4. Share the payment instructions with your customer. Bank transfer payment methods are unique to each customer and should not be shared with other customers. ## Timing Bank transfer timings vary depending on the country and payment scheme used. UK bank transfers support the following payment schemes: | Scheme | Timing | Availability | | --------------- | --------------------------------------- | ---------------- | | Faster Payments | Near-instant (typically within 2 hours) | UK bank accounts | | CHAPS | - | Not supported | | SWIFT | - | Not supported | EU bank transfers support the following payment schemes: | Scheme | Timing | Availability | | -------------------- | ----------------- | ---------------------- | | SEPA Credit Transfer | 1-2 business days | European bank accounts | | SWIFT | - | Not supported | ## International payments Bank transfers do not support direct international payment. Instead, we recommend instructing your customers to use [Wise](https://wise.com) to send funds to your their bank transfer payment method. ## Automatic reconciliation Yorlet automatically matches incoming bank transfers to customers using unique reference codes. When a payment is received: * If the reference matches an outstanding invoice, the invoice is marked as paid * If the reference matches a customer but no specific invoice, the funds are added to the customer's credit balance * If no match is found, the payment is flagged for manual review ## Remaining balances When an incoming bank transfer cannot be fully applied to an invoice — for example when the amount doesn't match, or when there is no outstanding invoice at the time — the unapplied funds accumulate on the payment method as a **remaining balance**. You can then charge that balance to settle a specific invoice or credit the customer's balance. Remaining balances are cleared in two ways: * **Automatically** — as new invoices are issued, [automatic reconciliation](/billing/invoices/automatic-reconciliation) matches the remaining balance against them and marks them paid. * **Manually** — use **Charge balance** on the bank transfer payment method, or right-click a row on the [Remaining balances page](https://dashboard.yorlet.com/customers/balances) and select **Charge balance** to create a payment for a specific invoice or credit the customer's balance. Learn more about [remaining balances](/customers/remaining-balances). ## Disputes Bank transfers are not subject to the same dispute mechanisms as card payments or direct debits. Once a bank transfer is received, it cannot be reversed by the customer without your consent. This makes bank transfers a lower-risk payment method for high-value transactions. If a customer claims they sent a payment that has not been received, you can use the [trace a payment](/payments/trace-a-payments) feature to investigate. ## Refunds To refund a bank transfer payment, you must initiate a manual payout to the customer's bank account. Learn how to [create a refund](/payments/refunds). Ensure you verify the customer's bank details before processing a refund to avoid sending funds to an incorrect account. # Cards Source: https://docs.yorlet.com/payments/payment-methods/cards Learn about Debit and Credit cards. Yorlet enables you to receive card payments from your customers in a secure and convenient way. You can easily accept card payments from your customers, providing them with a seamless and secure experience. ## Collect a Card To collect a Card payment method, follow these steps: 1. Navigate to the customer account for which you want to collect the payment method. 2. Under the **Payment methods** section, click **Collect payment method**. 3. Choose the **Cards** payment method type. You can also select multiple methods or just one; the customer will only be able to supply one method in the session. 4. Optionally, you can choose an active subscription to allocate the payment method to. This will update the subscription’s default payment method and set the collection method to **Charge automatically**. 5. Optionally, you can choose to send the collection link to the customer’s email. 6. Click **Create**. 7. Share the collection link with your customer. ## 3D Secure authentication In Europe, the Strong Customer Authentication regulation requires the use of 3D Secure (3DS) for card payments to provide customers with an extra layer of fraud protection. Yorlet automatically manages 3DS authentication during the payment process. ## Wallets To optimise the checkout experience when using cards on a transaction, we automatically present Apple Pay and Google Pay to the customer. ## Timing Card payments are processed instantly, allowing you to know immediately whether the payment succeeded or failed. ## Refunds You can refund a Card payment through the Dashboard. Refunds usually take 5-10 business days to be processed, depending upon the customer’s bank. Learn how to [create a refund](/payments/refunds). ## Disputes If a customer questions a card payment with their bank, a dispute is created in Yorlet. You can submit evidence to contest it. Learn how to [respond to a dispute](/payments/disputes). # Direct transfers Source: https://docs.yorlet.com/payments/payment-methods/direct-transfers Accept Direct Transfer payments. Direct transfers let a customer pay you by sending money from their bank. This payment method is in beta. ## Request early access If you would like early access, contact sales. # Pay by Bank Source: https://docs.yorlet.com/payments/payment-methods/pay-by-bank Accept Pay by Bank payments. Pay by Bank lets a customer pay you directly from their bank account. This payment method is in beta. ## Request early access If you would like early access, contact sales. # SEPA Direct Debit Source: https://docs.yorlet.com/payments/payment-methods/sepa-debit Collect euro payments with SEPA Direct Debit. SEPA Direct Debit collects payments in euros from a customer’s bank account in the Single Euro Payments Area. This payment method is in beta. ## Timing SEPA Direct Debit payments work on a 3 business day cycle. This table illustrates the timings for a SEPA Direct Debit payment: | Day | Event | | ----- | ------------------------------------------------ | | Day 0 | The funds leave the customers account | | Day 3 | The funds settle to your Yorlet merchant account | ## Disputes SEPA Direct Debit allows a payer to request a refund of an authorised collection from their bank within 8 weeks of being debited. The payer is also entitled to request a refund of an unauthorised or fraudulent collection from their bank up to 13 months after being debited. A dispute can also arise if the bank is unable to debit the customer’s account due to an issue, such as the account being frozen or having insufficient funds, but has already provided the funds to make the charge successful. In such cases, the bank reclaims the funds through a dispute process. When a dispute is raised Yorlet deducts the dispute amount and a dispute fee from your balance. | Currency | Dispute fee | | -------- | ----------- | | EUR | €7.50 | SEPA Direct Debit disputes are final and there is no process for appeal. See [Disputes](/payments/disputes) for how disputed payments appear in the Dashboard. ## Request early access This feature is currently in beta, if you would like early access please contact sales. # WeChat Pay Source: https://docs.yorlet.com/payments/payment-methods/wechat-pay Accept WeChat Pay, a popular mobile payment method in China. WeChat Pay lets customers in China pay from their WeChat wallet. This payment method is in beta. ## Request early access If you would like early access, contact sales. # Payment Sessions Source: https://docs.yorlet.com/payments/payment-sessions Learn how collect payments from customers with shareable links. You can accept payments quickly without having to create subscriptions or invoices with Payment Sessions. Share the link with your customer in emails, messages, or automatically. Payment Sessions support all available [payment methods](/payments/payment-methods) and can be configured with [Transfers](/owners/fund-flows). ## Create a payment session To create a new payment session, follow these steps: 1. Navigate to the customer you want to create a payment session for. 2. Click on the **Actions** menu and select **Create payment session** 3. Select the reporting type you’d like to use for the payment. 4. Enter the **Amount**, **Currency** and **Description**. 5. You can configure the payment methods you’d like to allow the customer to use. 6. Click **Create payment**. We also support some advance options when creating a payment session: ### Advanced options Choose whether to send an email to the customer with a link to the payment session. Optionally, you can configure whether the funds should be added to the customer’s balance after the payment succeeds, to be used to offset future invoices. Learn more about the [customer balance](). ## Share a payment session After you create a payment session a Transaction record will be created to manage the payment status. While the payment session is unpaid you can navigate to the transaction and retrieve the link to share with your customer. ## Customise branding You can customise the look and feel of the payment session page in the Yorlet Dashboard. Go to your [branding settings](https://dashboard.yorlet.com/settings/branding) to: * Upload a icon * Customise your brand colour Learn more about [branding](/account/branding). # Payouts Source: https://docs.yorlet.com/payments/payouts Set up your bank accounts to receive payouts. Payouts move your available payments balance to your own bank account. Add a bank account for each currency you want to receive, then request a payout from [Balance](/balance/payouts) when funds are ready. ## Adding a bank account You can add a bank account from [Settings → Bank accounts](https://dashboard.yorlet.com/settings/bank-accounts). You can only have one active bank account for each currency. If you accept a payment in a currency you don’t have a bank account for, we will convert the amount to your default currency. ## Timing Funds are available to payout 2 business days after the successful capture of a payment. ## Instant Payouts Beta If you need your funds sooner than the regular payout timing, you can use Instant Payouts. With Instant Payouts, you can receive funds within 30 minutes, including on weekends and holidays. There is an additional charge for using Instant Payouts. ## Request early access Instant Payouts is currently in beta, if you would like early access please contact sales. # Refund a payment Source: https://docs.yorlet.com/payments/refunds Learn how to refund payments. You can refund a payment in the Dashboard. This guide will show you how to refund payments to your customers. ## Refund a payment Refunds cannot be undone. Make sure you have the correct amount and customer details before processing a refund. To create a new payment session, follow these steps: 1. Navigate to the payment you want to refund. 2. Click the **Refund** button in the top right of the screen. 3. Enter the **Amount**, **Reason**, and add any aditional details about the refund. 4. Click **Refund**. Refunds can take 5–10 days to appear on a customer’s statement. Yorlet’s fees for the original payment won’t be returned, but there are no additional fees for the refund. # Real estate Source: https://docs.yorlet.com/real-estate Add buildings and units so you can let, bill, and maintain your portfolio. Real estate is your portfolio in Yorlet. A Building is the property — a house, a block of flats, or an HMO. Units sit under that building and are what you actually let. Together they support build-to-rent, residential, student, commercial, and block management. You can manage [buildings](https://dashboard.yorlet.com/buildings) and [units](https://dashboard.yorlet.com/units) from the Dashboard. ## Asset types Yorlet supports the following asset types out of the box: * Build to rent and multifamily * Residential property * Student property * Commercial property * Block management ## Get started Create a building for each property, as a single let or a multi-unit block Add units, set availability, and keep property details in one place # Buildings Source: https://docs.yorlet.com/real-estate/buildings Learn how to create and use buildings in Yorlet. The Building record is a core resource within Yorlet and can represent anything from a single property to a block of flats, it is used to group units into a single entity. ## Building types Yorlet supports a variety of building and unit configurations to provide you with maximum flexibility when setting up your properties. ### Single property Use the single property type when you’re adding a property you wish to lease as one. For example, a property with three residents all each paying rent. ### Multi-unit The multi-unit property type has a few different use cases: * A property that has multiple apartments, like a large building with 10 different properties you lease individually. * A house of multiple occupancy (HMO), where you lease individual rooms to different customers. ## Manage buildings Create a building for every new property that you want to use within Yorlet. You can create and manage buildings from the [Buildings page](https://dashboard.yorlet.com/buildings). ### Create a building To create a building, follow these steps: 1. Click **New** in the top right of the [Buildings page](https://dashboard.yorlet.com/buildings). 2. Choose between **Single property** and **Multiple units**. 3. Enter your property information, you can also set your default unit fees. 4. Click **Create**. ### Edit a building To edit a building, follow these steps: 1. Navigate to the building record you want to modify. 2. Click **Edit**. 3. Make the changes you want. 4. Click **Update**. ### Viewing hours and booking links If Leads is enabled, you can give a building its own viewing hours and a public booking link. To override the account viewing hours: 1. Open the building and click **Edit**. 2. Open the **Viewings** tab. 3. Turn on **Use custom viewing hours** and set the weekly times. 4. Click **Update**. Turn the toggle off to inherit the [account viewing hours](/leads/viewings#booking-settings) again. An empty custom calendar means the building offers no self-serve slots. On the same **Viewings** tab you can choose whether bookings from this building’s public link need a team member to confirm them, inherit the [account setting](/leads/viewings#booking-settings), or confirm automatically. Enquiry booking links are not affected. Confirm or decline pending viewings from the enquiry or the [Viewings board](/leads/viewings). To share a booking link for the building, open the overflow menu (•••) and choose **Copy viewing booking link**. The link is created the first time you copy it, and stays the same afterwards. Archived buildings cannot have a booking link. ### Archive a building To archive a building, follow these steps: 1. Navigate to the building record you want to archive. 2. Use the overflow menu (•••) and select **Archive building**. ### Delete a building To delete a building, follow these steps: Buildings can’t be deleted once they have been used by another resource. If you’re no longer using the building, you can archive it. 1. Navigate to the building record you want to delete. 2. Use the overflow menu (•••) and select **Delete building**. 3. Confirm you want to delete the record by clicking **Delete**. # Units Source: https://docs.yorlet.com/real-estate/units Learn how to create units, manage their availability, and keep property details in one place. Units represent assets that will be leased to a customer, and they each sit under a Building record. Every unit has an availability that shows whether it is on the market, coming free, or held back — separately from whether a tenant currently lives there. ## Manage units Create a unit for every new property that you want to use within Yorlet. You can create and manage units from the [Units page](https://dashboard.yorlet.com/units). ### Create a unit To create a unit, follow these steps: 1. Click **New** in the top right of the [Units page](https://dashboard.yorlet.com/units). 2. Choose the building you want to attach the unit to. 3. Enter your unit information, you need to at least supply a **Name** and **Currency**. 4. If you plan to manage the unit on behalf of a third party, you can attach owners to the unit. Learn more about [Owners](/owners) and [Unit Ownership](/owners/unit-ownership). 5. Click **Create**. A vacant unit is released to the market as soon as you create it, so it shows as **To let**. If you are not ready to let it yet, [hold it back](#hold-a-unit-back-from-the-market). ### Edit a unit To edit a unit, follow these steps: 1. Navigate to the unit record you want to modify. 2. Click **Edit**. 3. Make the changes you want. 4. Click **Update**. ### Archive a unit To archive a unit, follow these steps: 1. Navigate to the unit record you want to archive. 2. Use the overflow menu (•••) and select **Archive unit**. ### Delete a unit To delete a unit, follow these steps: Units can’t be deleted once they have been used by another resource. If you’re no longer using the unit, you can archive it. 1. Navigate to the unit record you want to delete. 2. Use the overflow menu (•••) and select **Delete unit**. 3. Confirm you want to delete the record by clicking **Delete**. ## Availability Availability is the letting state of a unit. Occupancy stays **Occupied** for as long as a tenant lives there, even after they have given notice. Availability is what changes as you prepare the unit to let again: it can move to **Coming available**, then **To let** once you release it, without waiting for the tenant to leave. You can review availability from the [Units page](https://dashboard.yorlet.com/units), which has tabs for each letting state, or from the unit itself. While a unit is coming available, held, vacant, or to let, the unit page shows a banner with the next action, and a timeline of when it was created, released, held back, or is coming available. ### Letting states * **To let**: The unit is on the market. Applicants can apply, and you can copy an apply link if self-serve applications are enabled. A vacant unit is released automatically when you create it, and again when a [tenancy](/leasing/tenancies) ends, unless you have held it back. * **Coming available**: The unit is still occupied, you know when it will be free, and it is not yet on the market. Setting **Available from**, or scheduling a tenancy to end, puts the unit here so your team can decide when to release it. * **Held**: You have deliberately kept the unit off the market. Choose a reason: **Works required**, **Owner instruction**, **Eviction in progress**, or **Other**. A held unit is not released automatically when the tenancy ends. * **Available**: The unit is vacant and not on the market. Release it when you are ready to take applications. * **Under offer**: An application has reserved the unit. Cancel the application before you can release or hold it. * **Occupied**: A tenant is in occupation and no let date is set yet. * **Maintenance**, **Offline**, and **Unmanaged**: The unit is out of the letting pipeline. Change **Status** in **Edit** before you can release it. You cannot change the status of an occupied unit. ### Release a unit to the market You can release a vacant unit, a unit that is coming available, a held unit, or an occupied unit you want to market before the tenant leaves. To release a unit, follow these steps: 1. Open the unit. 2. Click **Release**, or click **Availability** and choose **Release to market**. 3. Set **Available from** if you know when a new tenancy can start. 4. Optionally update the **Advertised rent**. 5. Click **Release to market**. If compliance certificates are missing or expire before the available-from date, the sheet warns you so you can sort them before move-in. It does not block the release. Once released, the unit shows as **To let**. You can copy the **Apply link** from the banner or the **Availability** tab. Releasing an occupied unit does not end the tenancy. It only lists the unit so you can market it before the tenant moves out. ### Release a unit when creating an application You can also release a unit from a new letting, without opening the unit first. 1. [Create an application](/leasing/applications/create-an-application) and choose a **Standard** or **Let only** type. 2. Select the unit. The form shows its availability and **Available from** date. 3. Click **Release** to list it now, or turn on **Release when creating this application** to list it when you create the application. **Release when creating this application** is on by default for **Coming available** units. **Renewal**, **Active tenancy**, and revision applications do not release the unit. ### Hold a unit back from the market Hold a unit when it should not be let yet — for example while works are underway, the owner has asked you to wait, or an eviction is in progress. To hold a unit, follow these steps: 1. Open the unit. 2. Click **Hold**, or click **Availability** and choose **Hold back**. 3. Choose a **Reason**. 4. Click **Hold back**. Holding a unit takes it off the market. Release it later when it is ready to let. ### Automatically release coming available units You can skip the manual release for units that are coming available. When auto-release is on, Yorlet lists a unit as **To let** this many days before its **Available from** date — so a 12-month tenancy stays **Coming available** at the start, and is released as the end date approaches. To turn it on, follow these steps: 1. Go to [Settings → Leasing](https://dashboard.yorlet.com/settings/leasing). 2. Under **Availability**, turn on **Automatically release coming available units**. 3. Set how many days before **Available from** to release (between 1 and 120). 4. Click **Save**. A hold still wins: a unit you have held back is not released, even if its date is inside the window. Units that are under offer, or in **Maintenance**, **Offline**, or **Unmanaged**, are also skipped. ### Set when a unit is available from **Available from** is the date a new tenancy can start. For an occupied unit, setting this date is what moves it to **Coming available**. It does not put the unit on the market. To update the date without changing whether the unit is on the market: 1. Open the unit and click **Availability**. 2. Set **Available from**. 3. Leave **Market** as **Leave as-is**. 4. Click **Save**. ### How availability updates on its own You do not have to manage every transition by hand: * When a [tenancy](/leasing/tenancies) starts, the unit comes off the market. If the tenancy has an end date, it becomes **Coming available**. * If auto-release is on, a **Coming available** unit is listed as **To let** once **Available from** is within the number of days you set. * Scheduling a tenancy to end, or recording a move-out date, sets **Available from** and moves an occupied unit to **Coming available**. * When a tenancy ends, the unit is released as **To let**, unless you have held it back. * Stopping a scheduled cancellation clears **Available from** if you have not already released the unit, so it returns to **Occupied**. * When an application reserves the unit, it becomes **Under offer**. Completing or cancelling the application clears that. ## Unit records The Unit record has many useful properties for storing property information and providing an overview of other resources the unit is associated with. ### Summary section This section shows the summary of the property details for the unit. You can modify these details by clicking **Edit**. ### Availability section This section shows the current letting state, **Available from** date, occupying tenancy, whether the unit is on the market, and the apply link. Use **Hold**, **Release**, or **Manage** to change it. ### Pricing section This section shows the current default pricing for the unit. You can add the monthly rent price and deposit amount. Additionally, you can add other currencies if you plan to pursue a multi-currency pricing strategy. To modify these details, click **Edit**. ### Owner fees section This section show the current owner fees for the unit. You can add a **Management fee**, **Tenant find fee**, **Renewal fee**, and a **Tax rate** to use for these prices, all fees should be set exclusive of tax. To modify these details, click **Edit**. ### Compliance section This section shows the compliance details for this unit. You can add **EPC**, **Electric safety**, and **Gas safety** certificates along with their respective expiry dates. Once uploaded, you can view these documents by clicking on **View**. To modify these details, click **Edit**. ### Features section This sections shows the marketing features of this unit that you can use to filter units when matching customers to available units. To modify these details, click **Edit**. ### Owners section If the unit is owned by a landlord or leaseholder owner account, these ownership records will be listed here. ### Keys section This section shows the associated Keys records the unit. You can create a new key for the unit by clicking on **New**. ### Applications section This section shows the associated Application records for the unit. You can create a new application for the unit by clicking **Create**. The form shows the unit's availability so you can release it if it is not yet on the market. ### Tenancies section This section shows the associated Tenancy records for the unit. ### Viewing feedback section This section shows the associated Viewing Feedback records for the unit. # Basic reporting Source: https://docs.yorlet.com/reporting/basic-reporting Learn how to access and use basic reporting features in Yorlet. Basic reporting provides insights into your business performance, helping you track your business growth and make informed decisions. ## Report types Yorlet offers the following basic reports: Generate reports for your Yorlet account Generate reports for your Owner accounts # Account reports Source: https://docs.yorlet.com/reporting/basic-reporting/account-reports Learn how to generate reports for your Yorlet account. Account reports provide detailed information about your Yorlet account, including your earnings, payouts, and transactions. You can use these reports to track your revenue, expenses, and cash flow, and to reconcile your Yorlet payouts with your bank account. ## Generate account reports To generate an account report, follow these steps: 1. Go to the [Reports](https://dashboard.yorlet.com/reports/hub) section of the Dashboard. 2. Under **Financial reports**, select the report you want to generate. 3. Choose the date range for the report. # Owner reports Source: https://docs.yorlet.com/reporting/basic-reporting/owner-reports Learn how to generate reports for your Owner accounts. Owner reports provide detailed information about your Owner accounts. ## Generate Owner reports To generate an Owner report, follow these steps: 1. Go to the [Reports](https://dashboard.yorlet.com/reports/hub) section of the Dashboard. 2. Under **Owner reports**, select the report you want to generate. 3. Choose the date range for the report. # Dashboard reports Source: https://docs.yorlet.com/reporting/dashboard-reports Learn how to use Dashboard reports. Dashboard reports Dashboard reports are pre-built reports that provide insights into your business. You can use these reports to track your business performance, understand your customers, and make informed decisions. Dashboard reports are available on the Dashboard on the **Home** tab. ## Adding reports To add a report to the Dashboard, follow these steps: 1. Click the **Add** button. 2. Choose the reports you want to add. 3. Click **Add**. ## Customising reports You can customise reports to suit your business needs. To customise a report, follow these steps: 1. Click the **Edit** button. 2. You can drag and drop the reports to rearrange them. 3. Click **Done**. ## Removing reports To remove a report from the Dashboard, follow these steps: 1. Click the **Edit** button. 2. Click the **Remove** button next to the report you want to remove. 3. Click **Done**. ## Filter by date You can apply date filters to reports to view specific data. Some reports have predefined dates, while others allow you to customise the date range. # Exporting data Source: https://docs.yorlet.com/reporting/exporting-data Learn how to export data from Yorlet. You can export data from Yorlet to analyse it in your preferred tool or to share it with your accountant. You can export data in the following formats: * **CSV**: A comma-separated values file that stores tabular data in plain text. ## Export data To export data from Yorlet, follow these steps: 1. Navigate to the page where you want to export data. 2. Click the **Export** button. 3. Select the date range for the data you want to export. 4. Click **Export** to download the data in CSV format. Filters you apply to tables will be reflected in the exported file. # Yorlet Reporting Source: https://docs.yorlet.com/reporting/introduction Use reports and exports to understand how your business is performing. Reporting helps you understand how the business is performing. Use preconfigured reports for income, expenses, and owner payments, pin charts to the Dashboard, and download a CSV when you need the underlying rows. You can generate reports from the [Reports page](https://dashboard.yorlet.com/reports). ## Get started Generate account and owner reports for a date range Pin charts to the Dashboard so the numbers you care about stay visible Download CSVs, filter the rows, and share exports across your organisation Add your own fields to records so they appear in reports and exports # Metadata Source: https://docs.yorlet.com/reporting/metadata Learn how to add metadata to your Yorlet data. Metadata allows you to add structured information to your Yorlet data. This information can be used in various ways, such as filtering, sorting, and grouping data. Metadata is a key part of the Yorlet data model and is used to describe the data in a way that is meaningful to your business. ### How metadata works Metadata is a set of key-value pairs that describe the data in your Yorlet account. Each key-value pair is associated with a specific data object, such as a customer, building, or unit. You can add metadata to your data objects using the Yorlet API or the Dashboard. Metadata can be used to filter, sort, and group data in your Yorlet account. For example, you can use metadata to filter customers by their location, sort buildings by their size, or group units by their status. ### Adding metadata You can add metadata to your data objects using the Yorlet API or the Dashboard. To add metadata using the Yorlet API, you can use the `metadata` field in the request body of the API call. To add metadata using the Dashboard, you can use the metadata editor in the Dashboard. ### Using metadata Once you have added metadata to your data objects, you can use it to filter, sort, and group data in your Yorlet account. We include metadata in all [exports](/reporting/exporting-data) to help you analyse your data and make informed decisions. ### Best practices When adding metadata to your data objects, it is important to follow best practices to ensure that the metadata is accurate and meaningful. Some best practices for adding metadata include: * Use descriptive key names that are easy to understand * Use consistent key names across data objects * Use meaningful values for each key * Avoid adding unnecessary metadata By following these best practices, you can ensure that your metadata is accurate and meaningful, and that it provides valuable insights into your Yorlet data.