Custom CSV & JSON Imports
Bulk import personal spreadsheets, custom databases, or notes using our standardized schema.
Download official starter templates
Get pre-formatted examples with all supported columns and fields.
1. How to Import a Custom File
Whether you keep an Excel spreadsheet, a Notion database, or custom JSON records, you can import your library in 4 steps:
Download the Starter Template
Download our or to inspect the column names and formatting.
Format Your Data
Paste or export your titles into the template. Make sure every row has a type (such as movie or tv) and a title or ID.
Upload in Migration Assistant
Open Account Settings > Import Data, select Custom File, and drag and drop your .csv or .json file into the dropzone.
Preview & Confirm
Review your parsed movies, shows, seasons, episodes, and custom collections, then click Confirm Import to sync.
2. Supported Columns & Schema
The table below describes all available fields you can include in your spreadsheet or JSON object:
| Field Name | Required? | Type / Format | Description |
|---|---|---|---|
| type | Required | movie | tv | season | episode | Identifies the media level. Use movie for films, tv for full shows, season or episode for granular TV logs. |
| title | Required if no ID | String (e.g. "Interstellar") | The name of the movie or television show. |
| year | Optional | Integer (e.g. 2014) | Release year. Recommended when matching titles with multiple versions. |
| tmdb_id | Recommended | Integer (e.g. 157336) | Direct TMDB identifier for instant 100% accurate title resolution. |
| imdb_id | Optional | String (e.g. "tt0816692") | IMDb Const ID used as an alternative matching identifier. |
| season_number | For seasons/episodes | Integer (e.g. 1) | Season index. Required when type is season or episode. |
| episode_number | For episodes | Integer (e.g. 9) | Episode index. Required when type is episode. |
| rating | Optional | Number (1.0 to 5.0) | Your rating. Accepts 1-5 scale with half-stars. If 1-10 is provided, it is automatically converted. |
| review | Optional | String | Your written review or journal notes. |
| watched_date | Optional | ISO 8601 or YYYY-MM-DD | Date the title was watched. Defaults to upload date if omitted. |
| status | Optional | watched | watchlist | watching | dropped | Library status. Defaults to watched if a rating or review is present. |
| progress | Optional | completed or S2E3 | For TV shows: specify completed or current progress shorthand (e.g. S2E3). |
| favorite | Optional | Boolean (true | false) | Marks the movie or show as a favorite. |
| spoiler | Optional | Boolean (true | false) | Hides review text behind a spoiler warning on your profile. |
| list_name | Optional | String (e.g. "Top Sci-Fi") | Adds the item to a private custom Collection of this name. |
3. Frequently Asked Questions
Can I upload a spreadsheet exported from Excel or Google Sheets?
Yes. In Excel or Google Sheets, choose File > Download > Comma Separated Values (.csv), and upload that .csv file directly into the Migration Assistant.
What is the advantage of including TMDB IDs?
Including tmdb_id guarantees instantaneous 100% matching without ambiguity, especially for common titles, remakes, or foreign films that share names.
How does the Migration Assistant handle unrecognized titles?
If a title in your file cannot be matched automatically by title and year, it will appear on your import review screen so you can pick and confirm the correct title with one click.
Will this import overwrite titles I already have in my library?
No. FlixNChill respects your existing records. Any ratings or logs already present in your account stay intact, while unlogged watch dates or progress are merged in.
Was this article helpful?
Your feedback helps improve our official documentation.