CSV Import
Bulk import multiple properties from a CSV file with column mapping, pre-validation, and undo option.
CSV Import
If you have an existing property inventory in a spreadsheet, you can bulk import them into Trochai using a CSV file. The import wizard guides you step by step: map columns, validate data before importing, and undo the import if needed.
CSV import is available only for users with the admin role. Agents and viewers cannot import properties.
Accessing the import
Navigate to Properties in the sidebar menu.
Click the Import CSV button next to the add property button.
The 3-step import wizard will open in a dialog.
Preparing the CSV file
File format and limits
| Requirement | Value |
|---|---|
| Format | CSV (comma-separated values) |
| First row | Column headers (field names) |
| Encoding | UTF-8 (compatible with Excel exports) |
| Extension | .csv |
| Maximum size | 2 MB |
| Maximum rows | 1,000 properties per file |
Download template
Inside the wizard, you can download a CSV template with the most common columns and 2 sample properties. Use this template as a starting point to prepare your file.
Supported columns
The import tool recognizes the following columns. Header names are flexible and accept variations in both Spanish and English:
| Field | Accepted headers | Required | Type | Valid values |
|---|---|---|---|---|
| Listing type | listing_type, listing_types, type, tipo, tipo_listado | Yes | Text | rent/alquiler/renta, sale/venta (separate multiple with ;) |
| Category | category, categoria | Yes | Text | apartment/apartamento/apto, house/casa, land/terreno/lote, commercial/comercial |
| Price | price, precio | Yes | Number | Greater than 0 |
| Title | title, titulo | No | Text | Maximum 200 characters |
| Currency | currency, moneda | No | Text | USD, CRC (default: USD) |
| Status | status, estado | No | Text | active, paused, sold, rented, draft, archived (default: draft) |
| Province | state, province, provincia | No | Text | Free text |
| Canton | city, canton | No | Text | Free text |
| District | neighborhood, district, distrito, zona | No | Text | Free text |
| Landmarks | landmarks, referencias | No | Text | Free text |
| Deposit | deposit, deposito | No | Number | Numeric amount |
| HOA fee | hoa_fee, hoafee | No | Number | Numeric amount |
| Bedrooms | bedrooms, beds, habitaciones, dormitorios | No | Integer | Integer >= 0 |
| Bathrooms | bathrooms, baths, banos | No | Integer | Integer >= 0 |
| Parking spots | parking_spots, parking, parqueos, estacionamientos | No | Integer | Integer >= 0 |
| Built area | built_area_m2, builtarea | No | Number | Square meters |
| Land area | land_area_m2, landarea | No | Number | Square meters |
| Amenities | amenities, amenidades | No | Text | Separated by ; (accepts Spanish names, e.g., piscina → pool) |
| Pet friendly | pet_friendly, petfriendly | No | Boolean | true, 1, yes, si, sí, verdadero |
| Furnished | furnished, amueblado | No | Boolean | Same boolean values |
| Availability | availability, disponibilidad | No | Boolean | Same boolean values |
| Available date | available_date, availabledate | No | Text | Date format |
| Description | short_description, description, descripcion | No | Text | Maximum 5,000 characters |
| Video URL | video_url, videourl | No | Text | Full URL |
| 3D tour URL | tour_3d_url, tour3durl | No | Text | Full URL |
CSV example
listing_type,category,price,currency,province,canton,district,bedrooms,bathrooms,amenities,description
sale,apartment,150000,USD,San Jose,Escazu,San Rafael,2,2,pool;gym;security_24_7,Modern apartment with valley view
rent,house,1200,USD,Heredia,Belen,La Asuncion,3,2,gardens;parking,Spacious house in quiet residential area
sale;rent,commercial,250000,USD,San Jose,Santa Ana,Pozos,0,1,elevator;lobby,Commercial space in business centerFor properties with multiple listing types (sale and rent), separate values with a semicolon (;), for example: sale;rent or venta;alquiler. The same applies for amenities.
Import process
Step 1: Upload file and map columns
Upload your CSV file by dragging it to the indicated area or clicking to select it. Only .csv files up to 2 MB and 1,000 rows are accepted.
The tool automatically detects the headers and maps them to Trochai fields. For each column, you'll see the first 3 sample values.
Review and adjust the mapping if needed. Each column has a dropdown where you can change which Trochai field it maps to, or select "Skip" to ignore that column.
The automatic mapping is smart: it normalizes headers (ignores capitalization, spaces, hyphens, and accents) and recognizes names in both Spanish and English.
You cannot map two CSV columns to the same Trochai field. If you try, the duplicate will be highlighted in red and you'll see the message "This field is already mapped to another column".
If you select Skip on one or more columns, an amber warning will appear listing exactly which columns will not be imported. This prevents accidental data loss.
Step 2: Review and import
When you advance to step 2, the tool automatically runs a pre-validation (dry-run) of all data without writing anything to the database:
- Valid rows (green badge): number of properties that passed all validations
- Error rows (red badge): number of rows with issues
- Preview: the first valid transformed rows, so you can see how they'll look in Trochai
Inline error editing
Instead of having to re-edit the CSV on your computer, you can now fix errors directly from the wizard. Each row with errors appears as a contextual card showing:
- Row number, property title, category, listing type, and location (province, canton, district)
- One input field per property with an error, with the current value pre-loaded
- Error messages grouped by field (if a field has multiple errors, they're concatenated separated by
·)
Edit values directly in the card's fields. Changes are marked as "unsaved".
When done, click Re-validate (appears in the bottom bar) to re-run validation with your fixes.
If errors remain, repeat the process. Once all rows are valid, click Import.
The bottom navigation bar (Back, Close, Re-validate, Import) is sticky while you scroll through the cards, so the buttons are always within reach. The dialog is also wider so the error cards are more comfortable to review.
Rows with errors are automatically skipped on import, but it's best to fix them inline before continuing.
Step 3: Results
After the import, you'll see a summary with:
- Imported (green badge): number of successfully created properties
- Skipped (gray badge): rows that could not be imported
- Errors (red badge): rows with validation errors
From this screen you have two options:
- Undo Import: delete all the properties just imported
- Close: dismiss the wizard and return to the properties list
Undo import
If you spot an error after importing, you can undo the entire import from the results screen (Step 3). This permanently deletes all properties that were imported in that batch.
The undo action cannot be reversed. Once the properties are deleted, you'll need to import them again. You'll be asked for confirmation before proceeding.
Data validation
The tool validates each row individually during the dry-run:
| Validation | Description |
|---|---|
| Required fields | listing_type, category, and price must be present |
| Listing type | Must be rent/alquiler, sale/venta, or both |
| Category | Must be apartment/apartamento, house/casa, land/terreno, or commercial/comercial |
| Status | If provided, must be active, paused, sold, rented, draft, or archived |
| Price | Must be a number greater than 0 |
| Numeric fields | Bedrooms, bathrooms, areas, etc. must be valid numbers |
| Text length | Title maximum 200 characters, description maximum 5,000 characters |
Rows with errors are skipped individually without affecting the import of valid rows.
Automatic defaults
If certain fields are not present in the CSV, default values are assigned:
| Field | Default value |
|---|---|
| Slug | Auto-generated from category and district |
| Status | draft (you must manually activate properties) |
| Currency | USD |
Imported properties are created with draft status. Review each property and change it to active when ready so the bot can find them in searches.
Best practices
- Use the downloadable CSV template as a starting point to avoid format errors.
- Review the column mapping in Step 1, especially if your spreadsheet has custom column names.
- Check the pre-validation in Step 2 before importing. Fix errors in your CSV and try again.
- Include at least the required fields --- listing type, category, and price.
- Add location and description whenever possible so the bot works correctly.
- Use predefined amenity names (like
pool/piscina,gym,security_24_7) for better bot integration. See the full list at Amenities. - Activate properties after importing --- properties in
draftstatus don't appear in bot searches.
Properties imported via CSV are created without photos. After importing, you can edit each property individually to add photos.