---
title: "Pre Import CSV data"
method: POST
path: "/api/v1/preimport"
tags: ["imports"]
---

# Pre Import CSV data

`POST /api/v1/preimport`

## Request

- Base URL: `https://demo.invoiceninja.com`
- URL: `https://demo.invoiceninja.com/api/v1/preimport`
- Auth: none declared. Required headers: `X-API-TOKEN`, `X-Requested-With`
- TypeScript: <https://skmtc.dev/invoiceninja/apis/invoice-ninja-api-reference/docs/api/v1/preimport/post.ts> (a function with typed inputs; its response is checked against the schema)

The preimport endpoint is the first step when importing CSV data into Invoice Ninja. It validates your file(s) and returns the column headers found in each CSV, allowing you to map them to system fields before performing the actual import.

**How it works**

1. Set `import_type` to indicate the entity type (e.g. `invoice`, `quote`, `client`, `product`, `payment`, `vendor`, `expense`).
2. Attach one or more CSV files using the `files[]` parameter, keyed by entity type:
   - `files[invoice]` — invoice records
   - `files[client]` — client records
   - `files[product]` — product records
   - `files[payment]` — payment records
   - `files[vendor]` — vendor records
   - `files[expense]` — expense records
3. The response returns the detected column headers for each uploaded file so you can build a field mapping for the subsequent `/api/v1/import` call.

You may upload multiple entity files in a single request. Only include the entity types relevant to your import.

**Example**

```bash
curl -X POST 'https://invoiceninja.com/api/v1/preimport' \
  -H 'X-API-TOKEN: YOUR_API_TOKEN_HERE' \
  -H 'Accept: application/json' \
  -F 'import_type=invoice' \
  -F 'files[invoice]=@invoices.csv' \
  -F 'files[client]=@clients.csv'
```

## Query parameters

- `include` string

## Headers

- `X-API-TOKEN` string, required
- `X-Requested-With` string, required

## Request body `multipart/form-data`

- object
  - `import_type` string, required: The type of import being performed
  - `files[invoice]` string, binary: CSV file for invoices
  - `files[client]` string, binary: CSV file for clients
  - `files[product]` string, binary: CSV file for products
  - `files[payment]` string, binary: CSV file for payments
  - `files[vendor]` string, binary: CSV file for vendors
  - `files[expense]` string, binary: CSV file for expenses

## Response `200`

Returns a hash identifying the uploaded file(s) and a mappings object for each entity type submitted.

- **hash** — A unique reference to the uploaded file(s). Pass this to `/api/v1/import` when executing the import.
- **mappings** — An object keyed by entity type (e.g. `invoice`, `client`). Each entity contains:
  - **available** — The system fields that can be mapped to for this entity (e.g. `invoice.number`, `client.name`, `item.cost`).
  - **headers** — A two-dimensional array. The first element contains the column headers detected from your CSV. The second element contains a sample data row, useful for previewing values during field mapping.
  - **hints** — An array of suggested mappings, one per CSV column. Each value is an index into the `available` array representing the best-guess system field for that column, or `null` when no match could be determined.

- object
  - `hash` string: Unique reference to the uploaded file(s), required for the subsequent import call.
  - `mappings` object: An object keyed by entity type containing field mapping data for each uploaded CSV.

## Other responses

- `401`: Authentication error
- `403`: Authorization error
- `422`: Validation error
- `default`: Unexpected Error

## Changes

> 110 revisions in range; 1 not diffed.

- **2026-03-03** `db27eff432ca`: 2 breaking, 7 info
  - added the new required request property `import_type`
  - the request's body type changed from `string` to `object`, and format from `binary` to no format
  - added the new optional request property `files[client]`
  - added the new optional request property `files[expense]`
  - …5 more
- **2024-06-06** `8e82a2bd77e0`: 1 breaking, 2 info
  - the response's body type changed from no type to `object` for status `default`
  - added the optional property `code` to the response with the `default` status
  - added the optional property `message` to the response with the `default` status
- **2024-06-05** `e61df65649e2`: 1 breaking, 2 warning
  - the response's body type changed from `object` to no type for status `default`
  - removed the optional property `code` from the response with the `default` status
  - removed the optional property `message` from the response with the `default` status
- **2024-03-07** `71171a40d629`: 4 breaking, 7 info
  - the response's body type changed from no type to `object` for status `401`
  - the response's body type changed from no type to `object` for status `403`
  - the response's body type changed from no type to `object` for status `422`
  - the response's body type changed from no type to `object` for status `default`
  - …7 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/invoiceninja/apis/invoice-ninja-api-reference/changes/api/v1/preimport/post.md)

---

[API](https://skmtc.dev/invoiceninja/apis/invoice-ninja-api-reference.md) - [All operations](https://skmtc.dev/invoiceninja/apis/invoice-ninja-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/invoiceninja/apis/invoice-ninja-api-reference/revisions/bcda1f823746?raw)