Bulk create and update clients, contacts, events, cases, and payments in your agency by uploading a CSV, TXT, or XLSX file.
Flat file uploads let you bulk create and update clients, contacts, events, cases, and payments in your agency from a CSV, TXT, or XLSX file. Every upload runs through an upload template, which stores the field mapping and the processing rules so you only set them up once per file format.
Overview
An upload has two parts. The upload template tells the platform how to read your file: which column maps to which system field, how rows are matched to existing records, and what defaults to apply. The upload itself is one file processed with that template. Templates are reusable, so once a template is correct, later files in the same format need no setup. One file can create clients, contacts, events, cases, payments, forms, and warrants at the same time.
Prerequisites
- A file saved as CSV, TXT, or XLSX
- Permissions
create_upload_templates and update_upload_templates to build and save a template
- Permissions
create_uploads and update_uploads to upload and process a file
- If your agency is live, build and test a new template in your staging agency first
Learn more about flat file uploads.
How-To Steps
Step 1: Create an upload template
- Log in to your eCourtDate production or staging agency.
- Click Uploads in the top navigation.
- Click the Upload Templates tab.
- Enter a name in the Name field of the Create Upload Template card.
- Click Create.
The new template opens so you can map it. You can change the name later.
Step 2: Map your columns from a sample file
- Choose your sample file in the Upload a Sample File (optional) card.
- Review the format and the column headers read from the file.
- Click Auto Map Fields to suggest a system field for every column.
- Select a system field in the Map to Field dropdown for any column that is still unmapped.
- Click Save.
Auto Map Fields uses AI, and the suggestions are not deterministic, so review every mapping before you save. The sample file is only used to read your headers, and nothing from it is imported.
Step 3: Confirm the Field Mapping card
The Field Mapping card is the source of truth for how every upload is read. Only the fields you map here are imported, and unmapped columns are ignored.
- Enter the column header from your file next to each system field you want to import.
- Copy and paste each header exactly, since mappings match your file's headers on an exact, case sensitive match.
- Click Map Default Fields to prefill mappings with each field's standard name, or Reset All Fields to clear every mapping.
- Check Map by Column Position if your file has no headers, which switches every mapping to the numerical position of the column (the first column is 0).
- Click Save.
Use the Search Fields box to jump to a field, or click the model badge next to a field name to show only that model's fields.
Step 4: Choose a processing method
In the Processing Settings card, select one of these options in Processing Method:
- Update by Matching Fields (incremental): each upload includes only records created or changed since the last upload. Records that are not in the file are left untouched.
- Full Replace: Across All Uploads: each upload is a complete snapshot of your data. Any record that is not in the file may be archived, including records another upload created.
- Full Replace: This Template Only: each upload is a complete snapshot of the records this template created. Records created by other templates are left alone.
If you select either full replace option, checkboxes appear for the record types to archive when they are missing from the file. Unchecked types are left untouched.
- Load and Replace Clients: existing clients not present in the upload are archived
- Load and Replace Contacts: existing contacts not present in the upload are archived
- Load and Replace Cases: existing cases not present in the upload are archived
Step 5: Set the match fields
The Match Existing Records settings decide how a row is matched to an existing record, and they apply regardless of the processing method you chose. Every selected field must match for a row to count as the same record, matching is case-insensitive, and a row with no match creates a new record.
- Select the fields that identify a client in Client Match Fields. At least one field is required to create clients.
- Select the fields that identify an event in Event Match Fields. Include Event Reference if your source system provides a stable ID for each event.
- Select the fields that identify a case in Case Match Fields. Case Number is usually the only stable identifier for a case across uploads.
- Select the fields that identify a payment in Payment Match Fields. Left empty, payments are matched on Payment Reference and Payment Amount together.
- Click Save.
The colored border on each selector shows the strength of the criteria: red is missing, yellow is weak, and green is recommended. Too few fields can collapse unrelated rows into one record, and too many can create duplicates when your source data varies slightly.
Step 6: Upload and preview the file
- Click Uploads in the top navigation.
- Click Choose File and select the file to upload.
- Select your template in Upload Template.
- Check Preview Upload.
- Click Create.
The upload opens with the status SKIPPED and no records are created yet. Check the red warning banners at the top, which list Unmapped file fields and Missing upload template fields, then read the row table below. Each column heading shows the mapped system field above the raw header from your file, so you can confirm the mapping row by row. If you change the template, refresh the upload page to load the latest mapping.
Step 7: Process the file
- Click Process Upload.
- Watch the status badge change to QUEUED while the upload waits for a worker.
- Wait for the status badge to reach COMPLETE.
- Review the count cards for file rows, clients, contacts, events, cases, payments, forms, and warrants, and click any count to open those records filtered to this upload.
- Enter a value in the search box on the upload and click Search to find the rows behind a count.
The Search Operator dropdown on the upload offers contains, =, <, <=, >, and >=, and the column dropdown narrows the search to one column or searches Any column. To search inside file data across every upload instead, check Search File Data on the Uploads page, then set Search Operator and Search Column.
What to Expect
While an upload runs, the upload page shows a progress bar with the current row, the process time, and the time per row. The status badge moves through QUEUED and PROCESSING to COMPLETE. If another upload in your agency is already processing when you create a new one, the new upload is created as DELAYED and waits its turn instead of running immediately.
If you entered addresses in the template's Notify Emails field, those addresses receive a summary with the record counts and any errors once processing finishes. Check the Notify Assigned Users option to also send an in-app notification to everyone assigned to the clients, cases, or events the upload touched.
Best Practices
- Preview the first upload with any new template so you catch mapping problems before records are created.
- Use Update by Matching Fields (incremental) unless your file is a full snapshot of your data every time.
- Include a stable reference (such as a client reference, Event Reference, or Case Number) in every file and select it in Match Existing Records so rows update instead of duplicating.
- Build and test new templates in your staging agency before you point them at production data.
- Remove blank rows and stray columns from your file, and set Field Delimiter and Cell Separator to match how your source system exports.
Frequently Asked Questions
Q: Do I have to preview every upload?
A: No. Preview Upload only skips processing so you can check the mapping first. Once you trust the template, leave it unchecked and the upload starts processing as soon as you click Create.
Q: How do I set a default value for a field?
A: Use the Default Values section of the upload template. You can set Default Client Status, Default Client Group, Default Event Status, Default Location, Default Flow, Default Portal, Default Payment Status, and Default Payment Amount. Each one applies when the matching column is unmapped or the row's value is blank.
Q: My dates and times are not processed correctly. How do I fix this?
A: Open the Parsing Formats section of the template and set Date Format and Time Format to match your file. Both default to automatic detection.
Q: The preview shows no data. What should I check?
A: Check File Format in Parsing Formats. It defaults to CSV, and auto detects the format from the file extension, so a TXT or XLSX file will not be read while the template is set to CSV. Also confirm Field Delimiter matches the character your file uses to split columns.
Q: Do I have to build every template from scratch?
A: No. Open the File Templates tab under Uploads, then click Import on a sample to create an upload template from it, or click Sample to download a CSV with that template's column headers.
Q: How do I create statuses from the values in my file?
A: Check Auto Create Statuses in the template's Post Processing Settings. Client, event, and payment statuses found in the file are created if they do not already exist. Go to Admin > Settings > Statuses afterwards to configure them.
Q: What can I do with an upload once it completes?
A: Click Create Bulk Action on the upload to start a bulk action scoped to that upload's records. You can also open the Tools menu for Download File, Replay Upload, Sync Upload, and Trash Upload.
Troubleshooting
Issue: The upload page shows a warning about mapped fields.
Symptoms: A red banner reads Unmapped file fields or Missing upload template fields followed by a list of column names.
Solution: Unmapped file fields lists columns in your file that no mapping uses, which is fine if you do not need them. Missing upload template fields lists mappings whose column is absent from this file, which usually means a header was renamed or misspelled. Open the template's Field Mapping card, correct the header text, then reprocess the upload.
Issue: Records are duplicated after processing.
Symptoms: You see two copies of the same client, event, or case in your agency after an upload.
Solution: Review Match Existing Records in the template. Choose the smallest set of fields that uniquely identifies each record type, and confirm those fields are mapped and present in every file. A missing or unstable match field creates a new record instead of updating the existing one.
Issue: An upload processed with the wrong template settings.
Symptoms: Data landed in the wrong fields, or record counts on the upload are far from what you expected.
Solution: Fix the template first, then open the upload and click Tools > Replay Upload. The upload returns to QUEUED and the same file is processed again with your corrected settings. If the records are right but their scheduled messages are not, click Tools > Sync Upload to re-sync the events that upload created with your latest message settings.
Issue: The upload is rejected before it is created.
Symptoms: An error reports that the upload already exists.
Solution: An upload cannot reuse the name or the file of another upload that has not been trashed. Rename the file before uploading it again, or trash the earlier upload from its Tools menu.
Issue: No upload can be created from the Uploads page.
Symptoms: A warning reads that no upload templates were found, and the file form is missing.
Solution: Create an upload template first. Click the Upload Templates tab and follow Step 1, or import one from the File Templates tab.
Related Articles
Flat file uploads let you bulk create and update clients, contacts, events, cases, and payments in your agency from a CSV, TXT, or XLSX file. Every upload runs through an upload template, which stores the field mapping and the processing rules so you only set them up once per file format.
### Overview
An upload has two parts. The upload template tells the platform how to read your file: which column maps to which system field, how rows are matched to existing records, and what defaults to apply. The upload itself is one file processed with that template. Templates are reusable, so once a template is correct, later files in the same format need no setup. One file can create clients, contacts, events, cases, payments, forms, and warrants at the same time.
### Prerequisites
- A file saved as CSV, TXT, or XLSX
- Permissions `create_upload_templates` and `update_upload_templates` to build and save a template
- Permissions `create_uploads` and `update_uploads` to upload and process a file
- If your agency is live, build and test a new template in your staging agency first
Learn more about [flat file uploads](https://ecourtdate.com/flat-file-uploads).
### How-To Steps
#### Step 1: Create an upload template
1. Log in to your eCourtDate [production](https://app.ecourtdate.com) or [staging](https://staging.ecourtdate.com) agency.
2. Click **Uploads** in the top navigation.
3. Click the **Upload Templates** tab.
4. Enter a name in the **Name** field of the **Create Upload Template** card.
5. Click **Create**.
The new template opens so you can map it. You can change the name later.
#### Step 2: Map your columns from a sample file
1. Choose your sample file in the **Upload a Sample File (optional)** card.
2. Review the format and the column headers read from the file.
3. Click **Auto Map Fields** to suggest a system field for every column.
4. Select a system field in the **Map to Field** dropdown for any column that is still unmapped.
5. Click **Save**.
**Auto Map Fields** uses AI, and the suggestions are not deterministic, so review every mapping before you save. The sample file is only used to read your headers, and nothing from it is imported.
#### Step 3: Confirm the Field Mapping card
The **Field Mapping** card is the source of truth for how every upload is read. Only the fields you map here are imported, and unmapped columns are ignored.
1. Enter the column header from your file next to each system field you want to import.
2. Copy and paste each header exactly, since mappings match your file's headers on an exact, case sensitive match.
3. Click **Map Default Fields** to prefill mappings with each field's standard name, or **Reset All Fields** to clear every mapping.
4. Check **Map by Column Position** if your file has no headers, which switches every mapping to the numerical position of the column (the first column is 0).
5. Click **Save**.
Use the **Search Fields** box to jump to a field, or click the model badge next to a field name to show only that model's fields.
#### Step 4: Choose a processing method
In the **Processing Settings** card, select one of these options in **Processing Method**:
- **Update by Matching Fields (incremental)**: each upload includes only records created or changed since the last upload. Records that are not in the file are left untouched.
- **Full Replace: Across All Uploads**: each upload is a complete snapshot of your data. Any record that is not in the file may be archived, including records another upload created.
- **Full Replace: This Template Only**: each upload is a complete snapshot of the records this template created. Records created by other templates are left alone.
If you select either full replace option, checkboxes appear for the record types to archive when they are missing from the file. Unchecked types are left untouched.
- **Load and Replace Clients**: existing clients not present in the upload are archived
- **Load and Replace Contacts**: existing contacts not present in the upload are archived
- **Load and Replace Cases**: existing cases not present in the upload are archived
#### Step 5: Set the match fields
The **Match Existing Records** settings decide how a row is matched to an existing record, and they apply regardless of the processing method you chose. Every selected field must match for a row to count as the same record, matching is case-insensitive, and a row with no match creates a new record.
1. Select the fields that identify a client in **Client Match Fields**. At least one field is required to create clients.
2. Select the fields that identify an event in **Event Match Fields**. Include **Event Reference** if your source system provides a stable ID for each event.
3. Select the fields that identify a case in **Case Match Fields**. **Case Number** is usually the only stable identifier for a case across uploads.
4. Select the fields that identify a payment in **Payment Match Fields**. Left empty, payments are matched on **Payment Reference** and **Payment Amount** together.
5. Click **Save**.
The colored border on each selector shows the strength of the criteria: red is missing, yellow is weak, and green is recommended. Too few fields can collapse unrelated rows into one record, and too many can create duplicates when your source data varies slightly.
#### Step 6: Upload and preview the file
1. Click **Uploads** in the top navigation.
2. Click **Choose File** and select the file to upload.
3. Select your template in **Upload Template**.
4. Check **Preview Upload**.
5. Click **Create**.
The upload opens with the status **SKIPPED** and no records are created yet. Check the red warning banners at the top, which list **Unmapped file fields** and **Missing upload template fields**, then read the row table below. Each column heading shows the mapped system field above the raw header from your file, so you can confirm the mapping row by row. If you change the template, refresh the upload page to load the latest mapping.
#### Step 7: Process the file
1. Click **Process Upload**.
2. Watch the status badge change to **QUEUED** while the upload waits for a worker.
3. Wait for the status badge to reach **COMPLETE**.
4. Review the count cards for **file rows**, **clients**, **contacts**, **events**, **cases**, **payments**, **forms**, and **warrants**, and click any count to open those records filtered to this upload.
5. Enter a value in the search box on the upload and click **Search** to find the rows behind a count.
The **Search Operator** dropdown on the upload offers contains, =, <, <=, >, and >=, and the column dropdown narrows the search to one column or searches **Any column**. To search inside file data across every upload instead, check **Search File Data** on the **Uploads** page, then set **Search Operator** and **Search Column**.
### What to Expect
While an upload runs, the upload page shows a progress bar with the current row, the process time, and the time per row. The status badge moves through **QUEUED** and **PROCESSING** to **COMPLETE**. If another upload in your agency is already processing when you create a new one, the new upload is created as **DELAYED** and waits its turn instead of running immediately.
If you entered addresses in the template's **Notify Emails** field, those addresses receive a summary with the record counts and any errors once processing finishes. Check the **Notify Assigned Users** option to also send an in-app notification to everyone assigned to the clients, cases, or events the upload touched.
### Best Practices
- Preview the first upload with any new template so you catch mapping problems before records are created.
- Use **Update by Matching Fields (incremental)** unless your file is a full snapshot of your data every time.
- Include a stable reference (such as a client reference, **Event Reference**, or **Case Number**) in every file and select it in **Match Existing Records** so rows update instead of duplicating.
- Build and test new templates in your staging agency before you point them at production data.
- Remove blank rows and stray columns from your file, and set **Field Delimiter** and **Cell Separator** to match how your source system exports.
### Frequently Asked Questions
**Q: Do I have to preview every upload?**
A: No. **Preview Upload** only skips processing so you can check the mapping first. Once you trust the template, leave it unchecked and the upload starts processing as soon as you click **Create**.
**Q: How do I set a default value for a field?**
A: Use the **Default Values** section of the upload template. You can set **Default Client Status**, **Default Client Group**, **Default Event Status**, **Default Location**, **Default Flow**, **Default Portal**, **Default Payment Status**, and **Default Payment Amount**. Each one applies when the matching column is unmapped or the row's value is blank.
**Q: My dates and times are not processed correctly. How do I fix this?**
A: Open the **Parsing Formats** section of the template and set **Date Format** and **Time Format** to match your file. Both default to automatic detection.
**Q: The preview shows no data. What should I check?**
A: Check **File Format** in **Parsing Formats**. It defaults to CSV, and **auto** detects the format from the file extension, so a TXT or XLSX file will not be read while the template is set to CSV. Also confirm **Field Delimiter** matches the character your file uses to split columns.
**Q: Do I have to build every template from scratch?**
A: No. Open the **File Templates** tab under **Uploads**, then click **Import** on a sample to create an upload template from it, or click **Sample** to download a CSV with that template's column headers.
**Q: How do I create statuses from the values in my file?**
A: Check **Auto Create Statuses** in the template's **Post Processing Settings**. Client, event, and payment statuses found in the file are created if they do not already exist. Go to **Admin** > **Settings** > **Statuses** afterwards to configure them.
**Q: What can I do with an upload once it completes?**
A: Click **Create Bulk Action** on the upload to start a bulk action scoped to that upload's records. You can also open the **Tools** menu for **Download File**, **Replay Upload**, **Sync Upload**, and **Trash Upload**.
### Troubleshooting
**Issue:** The upload page shows a warning about mapped fields.
**Symptoms:** A red banner reads **Unmapped file fields** or **Missing upload template fields** followed by a list of column names.
**Solution:** **Unmapped file fields** lists columns in your file that no mapping uses, which is fine if you do not need them. **Missing upload template fields** lists mappings whose column is absent from this file, which usually means a header was renamed or misspelled. Open the template's **Field Mapping** card, correct the header text, then reprocess the upload.
**Issue:** Records are duplicated after processing.
**Symptoms:** You see two copies of the same client, event, or case in your agency after an upload.
**Solution:** Review **Match Existing Records** in the template. Choose the smallest set of fields that uniquely identifies each record type, and confirm those fields are mapped and present in every file. A missing or unstable match field creates a new record instead of updating the existing one.
**Issue:** An upload processed with the wrong template settings.
**Symptoms:** Data landed in the wrong fields, or record counts on the upload are far from what you expected.
**Solution:** Fix the template first, then open the upload and click **Tools** > **Replay Upload**. The upload returns to **QUEUED** and the same file is processed again with your corrected settings. If the records are right but their scheduled messages are not, click **Tools** > **Sync Upload** to re-sync the events that upload created with your latest message settings.
**Issue:** The upload is rejected before it is created.
**Symptoms:** An error reports that the upload already exists.
**Solution:** An upload cannot reuse the name or the file of another upload that has not been trashed. Rename the file before uploading it again, or trash the earlier upload from its **Tools** menu.
**Issue:** No upload can be created from the **Uploads** page.
**Symptoms:** A warning reads that no upload templates were found, and the file form is missing.
**Solution:** Create an upload template first. Click the **Upload Templates** tab and follow Step 1, or import one from the **File Templates** tab.
### Related Articles
- [How to create upload templates](/how-to-create-upload-templates)
- [How to Assign Organizations via Uploads](/how-to-assign-organizations-via-uploads)
- [How Bulk Actions Work](/how-bulk-actions-work)
- [How to Manage Clients](/how-to-manage-clients)
- [How to manage statuses](/how-to-manage-statuses)