CSV imports - Yorlet Documentation

CSV imports let you create records in bulk by uploading a spreadsheet as a CSV file. Go to 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.

Pick an 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.

Download a template

Click Download template to download a CSV with the correct column headers for the selected import type.

Upload your CSV

Click Upload CSV or drag a CSV file onto the import panel. Non-CSV files are rejected.

Review and fix rows

Yorlet checks every row before creating anything. Rows with issues are highlighted, with a message explaining what needs to be fixed.

Choose import options

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.

Run the import

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.<key> columns, such as metadata.external_id. For invoices you can also set per-line-item metadata with line_items.<index>.metadata.<key>.
Boolean columns accept true/false, yes/no, y/n, or 1/0.

Account collection CSV format

Use these headers for account collection imports:

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:

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:

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:

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

Unit CSV format

Use these headers for unit imports:

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

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:

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

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.<index>.description`	Description of the line item.
`line_items.<index>.amount`	Amount for the line item. How this is interpreted depends on the selected amount format.
`line_items.<index>.type`	Line item type. One of `charge`, `rent`, or `product`. Defaults to `charge`.
`line_items.<index>.tax_percent`	Tax percentage applied to the line item. Defaults to `0`.
`line_items.<index>.unit`	Optional unit related to the line item.
`line_items.<index>.transfer_behavior`	How funds are transferred. One of `automatic`, `owner`, or `none`. Defaults to `automatic`.
`line_items.<index>.transfer_destination`	The destination account for the transfer.
`line_items.<index>.metadata.example`	Example per-line-item metadata column. Add your own with `line_items.<index>.metadata.<key>`.

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.

​Permissions

​Run an import

​Fix issues inline

​Re-run an import

​CSV formatting basics

​Account collection CSV format

​Fields

​Amount format

​Expense and fee codes

​Customer CSV format

​Fields

​Unit CSV format

​Fields

​Currency

​Invoice CSV format

​Invoice fields

​Line items

​Amount format

Permissions

Run an import

Fix issues inline

Re-run an import

CSV formatting basics

Account collection CSV format

Fields

Amount format

Expense and fee codes

Customer CSV format

Fields

Unit CSV format

Fields

Currency

Invoice CSV format

Invoice fields

Line items

Amount format