> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yorlet.com/llms.txt
> Use this file to discover all available pages before exploring further.
# CSV 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`.