Import CSV data

POST 
/api/v1/import

The import endpoint executes the actual data import. Call this after /api/v1/preimport has returned the file hash, available fields, and column headers.

Using the data from the preimport response, construct a column_map that tells the system how each CSV column maps to a system field. The import runs asynchronously — you will receive an email notification once it completes.

Request body

• hash — The unique file reference returned by /api/v1/preimport.
• import_type — The source format (e.g. csv, freshbooks, invoice2go, invoicely).
• skip_header — Set to true to skip the first row of the CSV (the header row).
• column_map — An object keyed by entity type (e.g. invoice, client). Each entity contains:
  • mapping — An object where each key is the CSV column index (as a string) and each value is the target system field from the available array, or an empty string "" to skip that column.

---

Available mapping fields

Each mapping value uses the format entity.property. The tables below list every available field per entity type.

Data Matching:

Client Matching:

Matching a record to a client is performed by using the clients email address (first) or the clients (exact) name. If no match is found, a new client is created.

Multi line item invoice/quote/credits/recurring invoice Matching:

If you need to import multiple line items into an invoice (other other entity) you will want to assign the same (unique) invoice number to each row in the csv file, the system will group together lines where the invoice number is the same and create line items for each row.

Invoice fields (files[invoice])

Field	Description
invoice.number	Invoice number
invoice.user_id	Assigned user
invoice.amount	Invoice amount
invoice.balance	Outstanding balance
invoice.discount	Discount value
invoice.po_number	Purchase order number
invoice.date	Invoice date
invoice.due_date	Due date
invoice.terms	Invoice terms
invoice.status	Invoice status
invoice.public_notes	Public notes (visible to client)
invoice.is_sent	Whether the invoice has been sent
invoice.private_notes	Private notes (internal only)
invoice.uses_inclusive_taxes	Whether tax amounts are inclusive
invoice.tax_name1	Tax name (tier 1)
invoice.tax_rate1	Tax rate (tier 1)
invoice.tax_name2	Tax name (tier 2)
invoice.tax_rate2	Tax rate (tier 2)
invoice.tax_name3	Tax name (tier 3)
invoice.tax_rate3	Tax rate (tier 3)
invoice.is_amount_discount	Whether discount is a fixed amount
invoice.footer	Invoice footer
invoice.partial	Partial/deposit amount
invoice.partial_due_date	Partial payment due date
invoice.custom_value1	Custom field 1
invoice.custom_value2	Custom field 2
invoice.custom_value3	Custom field 3
invoice.custom_value4	Custom field 4
invoice.custom_surcharge1	Custom surcharge 1
invoice.custom_surcharge2	Custom surcharge 2
invoice.custom_surcharge3	Custom surcharge 3
invoice.custom_surcharge4	Custom surcharge 4
invoice.exchange_rate	Currency exchange rate
client.name	Client name
client.email	Client email
payment.date	Payment date
payment.amount	Payment amount
payment.transaction_reference	Payment transaction reference
item.quantity	Line item quantity
item.cost	Line item unit cost
item.product_key	Line item product key
item.notes	Line item description
item.discount	Line item discount
item.is_amount_discount	Whether line item discount is a fixed amount
item.tax_name1	Line item tax name (tier 1)
item.tax_rate1	Line item tax rate (tier 1)
item.tax_name2	Line item tax name (tier 2)
item.tax_rate2	Line item tax rate (tier 2)
item.tax_name3	Line item tax name (tier 3)
item.tax_rate3	Line item tax rate (tier 3)
item.custom_value1	Line item custom field 1
item.custom_value2	Line item custom field 2
item.custom_value3	Line item custom field 3
item.custom_value4	Line item custom field 4
item.type_id	Line item type

Client fields (files[client])

Field	Description
client.name	Client name
client.user_id	Assigned user
client.balance	Account balance
client.paid_to_date	Total paid to date
client.currency_id	Currency
client.website	Website URL
client.private_notes	Private notes
client.industry_id	Industry
client.size_id	Company size
client.address1	Address line 1
client.address2	Address line 2
client.city	City
client.state	State/province
client.postal_code	Postal code
client.country_id	Country
client.custom_value1	Custom field 1
client.custom_value2	Custom field 2
client.custom_value3	Custom field 3
client.custom_value4	Custom field 4
client.shipping_address1	Shipping address line 1
client.shipping_address2	Shipping address line 2
client.shipping_city	Shipping city
client.shipping_state	Shipping state/province
client.shipping_postal_code	Shipping postal code
client.shipping_country_id	Shipping country
client.payment_terms	Default payment terms
client.vat_number	VAT/tax number
client.id_number	ID number
client.public_notes	Public notes
client.phone	Phone number
contact.first_name	Contact first name
contact.last_name	Contact last name
contact.email	Contact email
contact.phone	Contact phone
contact.custom_value1	Contact custom field 1
contact.custom_value2	Contact custom field 2
contact.custom_value3	Contact custom field 3
contact.custom_value4	Contact custom field 4

Product fields (files[product])

Field	Description
product.product_key	Product key/name
product.notes	Product description
product.cost	Product cost
product.price	Product price
product.quantity	Default quantity
product.tax_name1	Tax name (tier 1)
product.tax_rate1	Tax rate (tier 1)
product.tax_name2	Tax name (tier 2)
product.tax_rate2	Tax rate (tier 2)
product.tax_name3	Tax name (tier 3)
product.tax_rate3	Tax rate (tier 3)
product.custom_value1	Custom field 1
product.custom_value2	Custom field 2
product.custom_value3	Custom field 3
product.custom_value4	Custom field 4
product.image_url	Product image URL
product.in_stock_quantity	In-stock quantity
product.tax_category	Tax category
product.max_quantity	Maximum quantity

Payment fields (files[payment])

Field	Description
payment.number	Payment number
payment.user_id	Assigned user
payment.amount	Payment amount
payment.refunded	Refunded amount
payment.applied	Applied amount
payment.transaction_reference	Transaction reference
payment.private_notes	Private notes
payment.custom_value1	Custom field 1
payment.custom_value2	Custom field 2
payment.custom_value3	Custom field 3
payment.custom_value4	Custom field 4
payment.client_id	Client
payment.invoice_number	Invoice number
payment.date	Payment date
payment.method	Payment method

Vendor fields (files[vendor])

Field	Description
vendor.name	Vendor name
vendor.phone	Phone number
vendor.id_number	ID number
vendor.vat_number	VAT/tax number
vendor.website	Website URL
vendor.first_name	First name
vendor.last_name	Last name
vendor.email	Email address
vendor.currency_id	Currency
vendor.public_notes	Public notes
vendor.private_notes	Private notes
vendor.address1	Address line 1
vendor.address2	Address line 2
vendor.city	City
vendor.state	State/province
vendor.postal_code	Postal code
vendor.country_id	Country
vendor.custom_value1	Custom field 1
vendor.custom_value2	Custom field 2
vendor.custom_value3	Custom field 3
vendor.custom_value4	Custom field 4
contact.first_name	Contact first name
contact.last_name	Contact last name
contact.email	Contact email
contact.phone	Contact phone
contact.custom_value1	Contact custom field 1
contact.custom_value2	Contact custom field 2
contact.custom_value3	Contact custom field 3
contact.custom_value4	Contact custom field 4

Expense fields (files[expense])

Field	Description
expense.vendor	Vendor name
expense.client	Client name
expense.project	Project name
expense.category	Expense category
expense.amount	Expense amount
expense.currency	Currency
expense.date	Expense date
expense.payment_type	Payment type
expense.payment_date	Payment date
expense.transaction_reference	Transaction reference
expense.public_notes	Public notes
expense.private_notes	Private notes
expense.tax_name1	Tax name (tier 1)
expense.tax_rate1	Tax rate (tier 1)
expense.tax_name2	Tax name (tier 2)
expense.tax_rate2	Tax rate (tier 2)
expense.tax_name3	Tax name (tier 3)
expense.tax_rate3	Tax rate (tier 3)
expense.uses_inclusive_taxes	Whether tax amounts are inclusive
expense.custom_value1	Custom field 1
expense.custom_value2	Custom field 2
expense.custom_value3	Custom field 3
expense.custom_value4	Custom field 4

Quote fields (files[quote])

Field	Description
quote.number	Quote number
quote.user_id	Assigned user
quote.amount	Quote amount
quote.balance	Outstanding balance
quote.discount	Discount value
quote.po_number	Purchase order number
quote.date	Quote date
quote.due_date	Valid until date
quote.terms	Quote terms
quote.status	Quote status
quote.public_notes	Public notes
quote.is_sent	Whether the quote has been sent
quote.private_notes	Private notes
quote.uses_inclusive_taxes	Whether tax amounts are inclusive
quote.tax_name1	Tax name (tier 1)
quote.tax_rate1	Tax rate (tier 1)
quote.tax_name2	Tax name (tier 2)
quote.tax_rate2	Tax rate (tier 2)
quote.tax_name3	Tax name (tier 3)
quote.tax_rate3	Tax rate (tier 3)
quote.is_amount_discount	Whether discount is a fixed amount
quote.footer	Quote footer
quote.partial	Partial/deposit amount
quote.partial_due_date	Partial payment due date
quote.custom_value1	Custom field 1
quote.custom_value2	Custom field 2
quote.custom_value3	Custom field 3
quote.custom_value4	Custom field 4
quote.custom_surcharge1	Custom surcharge 1
quote.custom_surcharge2	Custom surcharge 2
quote.custom_surcharge3	Custom surcharge 3
quote.custom_surcharge4	Custom surcharge 4
quote.exchange_rate	Currency exchange rate
client.name	Client name
client.email	Client email
payment.date	Payment date
payment.amount	Payment amount
payment.transaction_reference	Transaction reference
item.*	Same line item fields as invoices

Recurring invoice fields (files[recurring_invoice])

Supports all invoice fields above, plus:

Field	Description
invoice.frequency_id	Recurrence frequency
invoice.remaining_cycles	Remaining billing cycles
invoice.auto_bill	Auto-bill setting
invoice.next_send_date	Next send date (replaces invoice.date)

Task fields (files[task])

Field	Description
task.number	Task number
task.user_id	Assigned user
task.rate	Hourly rate
task.description	Task description
task.billable	Whether the task is billable
task.status	Task status
task.start_date	Start date
task.end_date	End date
task.start_time	Start time
task.end_time	End time
task.duration	Duration
task.custom_value1	Custom field 1
task.custom_value2	Custom field 2
task.custom_value3	Custom field 3
task.custom_value4	Custom field 4
task.notes	Task notes
project.name	Project name
client.name	Client name
client.email	Client email

Bank transaction fields (files[bank_transaction])

Field	Description
transaction.transaction_id	Transaction ID
transaction.amount	Transaction amount
transaction.currency	Currency
transaction.account_type	Account type
transaction.category	Category
transaction.category_type	Category type
transaction.date	Transaction date
transaction.bank_account	Bank account
transaction.description	Description
transaction.base_type	Base type
transaction.payment_type_Credit	Credit amount
transaction.payment_type_Debit	Debit amount
transaction.participant	Participant reference
transaction.participant_name	Participant name

---

Example

curl -X POST 'https://invoiceninja.com/api/v1/import' \
  -H 'X-API-TOKEN: YOUR_API_TOKEN_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "hash": "MvKeSwMnhAfgkzdYKgxM5ummxGbLIdNm",
    "import_type": "csv",
    "skip_header": true,
    "column_map": {
      "invoice": {
        "mapping": {
          "0": "client.name",
          "1": "client.email",
          "2": "",
          "3": "invoice.number",
          "4": "invoice.amount"
        }
      }
    }
  }'

Request

Responses

200

The import has been queued. A notification email will be sent upon completion.

Response Headers

X-MINIMUM-CLIENT-VERSION

The API version

X-RateLimit-Remaining

The number of requests left for the time window.

X-RateLimit-Limit

The total number of requests in a given time window.

401

Authentication error

403

Authorization error

422

Validation error

default

Unexpected Error