---
title: Imports
summary: 'A background job that creates or updates records in bulk from an uploaded CSV / XLSX file. The Imports page is the history and status panel for every import your tenant has run.'
section: features
tags:
  - crud
  - telephony
  - background-jobs
  - bulk-operations
updated: '2026-08-12'
---

> An **import** is a background job that creates or updates records in bulk from an uploaded CSV / XLSX / XLS file. You upload a spreadsheet, map its columns to fields, and the platform processes the rows asynchronously.

## Overview

An import is started from the entity's own page (*Users -> Import*, *Contacts -> Import*). The Imports page is where you check status, open an import to see what it touched, complete one that was uploaded but never confirmed, or delete old rows (which does not undo imported data). Imports are supported for four entity types:

| Entity | Use case |
|---|---|
| **[Users](users.md)** | Bulk onboard new users or update existing ones. |
| **[Contacts](contacts.md)** | Import an external contact list into the PBX address book. |
| **[Keywords](keywords.md)** | Bulk-load AI call-classification keywords with their prompts. |
| **[SIP devices](sip_devices.md)** | Bulk-provision SIP devices, for example a fleet of hardware phones. |

## What it does

An import runs in two phases. You upload a file (status *Incomplete*), then confirm a column mapping plus per-entity options like *skip on error*, which queues the background job. If you never confirm the mapping, the import stays *Incomplete* and the list shows a **Complete import** action to resume.

| Status | Meaning |
|---|---|
| **Incomplete** | File uploaded but mapping not confirmed. Use *Complete import* to resume. |
| **Pending** | Job queued and waiting for a worker. |
| **Processing** | Worker is reading and inserting / updating rows. |
| **Completed** | All rows processed successfully. |
| **Completed with errors** | Some rows failed validation. Open the detail view for the error list. |
| **Failed** | The job aborted (catastrophic error, malformed file). |

The detail view shows the inserted and updated records, each linking to its edit page, plus an error list giving the row number, failed attribute, validation messages, and original row data. The *Skip on error* option (on by default) controls what happens when a row fails. When on, bad rows are dropped and the rest proceed (*Completed with errors*). When off, the first bad row aborts the import (*Failed*).

> [!IMPORTANT]
> Imports cannot be undone in one click. To roll back, bulk-delete the records yourself. Always test on a small subset first.

> [!CAUTION]
> Column mapping is per file with no saved template, so keep your headers consistent. Uploaded files stay on the server until you delete the import row, so delete imports of sensitive data once verified.

## How to bulk-create users from a spreadsheet

1. Start from the entity, not this page: *Users -> Import*. The Imports page is the history and status view.
2. Cut a test file of three or four rows first. An import cannot be undone in one click, so a wrong mapping on a thousand rows means deleting a thousand records by hand.
3. Upload it, then confirm the column mapping. Nothing is created until you do: an import sits at *Incomplete* until the mapping is confirmed, and **Complete import** on the list resumes one you walked away from.
4. Leave *Skip on error* on for the test run, then open the import and read the error list. It gives you the row number, the attribute that failed, and the original row.
5. Fix the spreadsheet and run the full file, keeping the headers identical to the test file. The mapping is per file and nothing is saved between runs.
6. Verify against the inserted and updated lists in the detail view, each row linking to the record it created.
7. Delete the import row afterwards if the file held personal data. Uploaded files stay on the server until the row is deleted.

## See also

- [Exports](exports.md) - the outbound companion to imports.
- [Users](users.md), [Contacts](contacts.md), [Keywords](keywords.md), [SIP devices](sip_devices.md) - the four supported import targets.
- [Events](events.md) - the operational log where import job lifecycle is also recorded.

```yaml fields
owner:
  label: User
  tab: General
  hint: 'The user who started this import.'
model:
  label: 'Resource type'
  tab: General
  hint: 'The type of records being imported (for example, User or Contact).'
status:
  label: Status
  tab: General
  hint: 'The current state of the import: Incomplete, Pending, Processing, Completed, Failed, or Completed with errors.'
duration:
  label: Duration
  tab: General
  hint: 'How long the import took to finish, in seconds. Only shown after the import completes.'
created_at:
  label: 'Created at'
  tab: General
  hint: 'When the import file was uploaded.'
started_at:
  label: 'Started at'
  tab: General
  hint: 'When background processing began.'
completed_at:
  label: 'Completed at'
  tab: General
  hint: 'When the import finished processing.'
errors:
  label: Errors
  tab: General
  hint: 'A list of validation or processing errors that came up during the import, showing the row number, attribute, error messages, and original row data.'
errors_count:
  label: 'Number of errors'
  tab: General
  hint: 'The total number of errors encountered during processing.'
records_count:
  label: 'Number of records inserted and updated'
  tab: General
  hint: 'The total number of records that were inserted or updated by this import.'
records_inserted:
  label: 'Records inserted'
  tab: General
  hint: 'Links to the individual records that were newly created by this import.'
records_updated:
  label: 'Records updated'
  tab: General
  hint: 'Links to the individual records that were updated by this import.'
complete_import:
  label: 'Complete import'
  tab: General
  hint: 'An action button that lets you finish configuring an import that was uploaded but not yet started.'
```