Imports

Import customers, vendors, accounts, opening balances and open items from CSV or Excel: dry run, all-or-nothing commit, templates.

POST /v1/entities/{entity}/imports

Import customers, vendors, accounts, balances or open items

Bring a customer's existing books into the ledger from a CSV or Excel file.

Start with a dry run (mode=dry_run, the default): it runs the same code as the import in a savepoint, rolls it back, and returns every problem of the file at once, each with its line (row of the file), column and message, plus a summary of what a commit would create. Fix the file, repeat, then send it again with mode=commit and an Idempotency-Key. A commit is all or nothing: it applies every row in one transaction, or, if any row has a problem, answers 422 with the same list of problems and changes nothing. A retry with the same key and file returns the first answer.

The six types go through the same services as the API does, so every control applies:

• customers, vendors: created like POST /v1/entities/{entity}/parties. A customer is active; a person's new vendor is a draft with an activation request, and a second person must approve it (GET /v1/approvals) before its bills can be posted or paid, unless the organization's approval policy allows activate_party for vendors.
• accounts: added like POST /v1/entities/{entity}/accounts (needs the admin scope and the policy's manage_accounts).
• opening_balances: the trial balance of the old books, one balanced opening entry per entity dated as_of (source opening), posted through the approval policy. Rows for the receivables and payables control accounts are not posted (their balances are the open items); the difference is booked to the account with the role opening_balance_clearing. A second opening entry is refused until the first is reversed: to correct an opening entry, reverse it (POST /v1/journal-entries/{id}/reverse; a second person approves the reversal), then import the balances again.
• open_receivables, open_payables: every open invoice, bill or credit note becomes a posted document with its original number, dates and open gross amount, booked against the clearing account (receivables or payables control account against clearing), so nothing is counted twice. The customer or vendor must exist and be active. Once the balances and both lists agree, the clearing account is zero (summary.clearing_balance).

An fx_rate more than 10% away from the reference rate (ECB) of the opening date is a problem of its row unless confirm_rates is true (see confirm_rates).

Agent keys are refused (403). Refused: 404 for an unknown entity, 422 for an unreadable file, a file over 5 MB or 2,000 rows, a missing as_of, and (on commit) any problem in the rows; 409 when the Idempotency-Key was used with another file. The commit is an audit event (import.commit) with the file's SHA-256 next to the audit events of everything it created.

Parameters

Request body

multipart/form-data (required): Body_import_file_v1_entities__entity__imports_post

Example request

curl -X POST "$ERP_URL/v1/entities/CH01/imports" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@customers.csv" \
  -F "type=accounts"

Responses

Example response (shape)

{
  "type": "accounts",
  "mode": "commit",
  "entity": "string",
  "format": "csv",
  "filename": "string",
  "sha256": "string",
  "as_of": "2026-09-21",
  "rows": 1,
  "ok": true,
  "committed": true,
  "errors": [
    {
      "line": 1,
      "column": "string",
      "message": "string"
    }
  ],
  "warnings": [
    {
      "line": 1,
      "column": "string",
      "message": "string"
    }
  ],
  "summary": {
    "created": 1,
    "waiting_for_activation": 1,
    "posted": 1,
    "waiting_for_approval": 1,
    "total_debit": "string",
    "total_credit": "string",
    "clearing_difference": "string",
    "amounts_by_currency": {},
    "clearing_balance": "string",
    "entry": {
      "entry_id": null,
      "status": null,
      "number": null,
      "approval_id": null
    }
  },
  "rates_to_confirm": 0
}

POST /v1/entities/{entity}/imports/salesforce

Import a Salesforce export

Bring a company's Salesforce data over, one object (one file) at a time: its users (linked to the people here by email), accounts (customers), products, price books and prices, opportunities (deals), and the tasks, events and notes about them.

Import the files in the order of object: each links to those before it (a deal to its account, a task to its deal, a price to its product and price book). Start with a dry run (the default): it returns every problem with its line and the file's column, the mapping of our fields to the file's columns (by Salesforce API name or report label), and a summary of what a commit would create. Name other columns in mapping where the file calls a field differently (a custom field), then send the file with mode=commit and an Idempotency-Key. A commit is all or nothing.

Re-imports create nothing twice: every record is kept with its Salesforce id, so the same file or a newer export imports only what is new (summary.already_imported counts the rest). An account whose code or name is already a customer here is linked to it, not doubled. Rows deleted in Salesforce (IsDeleted) are skipped.

Every record goes through the same controls as the API: customers under the approval policy, VAT numbers checked (one that fails is kept and marked unverified), products on the default revenue account. Agent keys are refused (403). Refused: 404 for an unknown entity, 422 for an unreadable file, a file over the limits, a bad mapping, and (on commit) any problem in the rows; 409 when the Idempotency-Key was used with another file. The commit is an audit event (import.salesforce) with the file's SHA-256.

Parameters

Request body

multipart/form-data (required): Body_import_salesforce_v1_entities__entity__imports_salesforce_post

Example request

curl -X POST "$ERP_URL/v1/entities/CH01/imports/salesforce" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@statement.xml" \
  -F "object=accounts"

Responses

Example response (shape)

{
  "object": "accounts",
  "mode": "commit",
  "entity": "string",
  "format": "csv",
  "filename": "string",
  "sha256": "string",
  "rows": 1,
  "ok": true,
  "committed": true,
  "columns": [
    "string"
  ],
  "mapping": [
    {
      "field": "string",
      "column": "string",
      "required": true,
      "description": "string",
      "label": "string"
    }
  ],
  "unused_columns": [
    "string"
  ],
  "errors": [
    {
      "line": 1,
      "column": "string",
      "message": "string"
    }
  ],
  "warnings": [
    {
      "line": 1,
      "column": "string",
      "message": "string"
    }
  ],
  "summary": {
    "created": 1,
    "already_imported": 1,
    "skipped": 1,
    "records": {}
  }
}

GET /v1/entities/{entity}/imports/templates/{type}

Download an import template

The columns of an import as a file you can fill in: csv or xlsx. The first row names the columns (the onboarding workflow lists them); amounts are plain decimals with a dot, dates YYYY-MM-DD, yes/no columns take yes or no. Every cell of the template is text a spreadsheet cannot run as a formula. The entity must be the caller's (404 otherwise).

Parameters

Example request

curl "$ERP_URL/v1/entities/CH01/imports/templates/vendors" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Schemas

Body_import_file_v1_entities__entity__imports_post

Body_import_salesforce_v1_entities__entity__imports_salesforce_post

DataImportResult

FieldMapping

Which column of the file one of our fields is read from.

ImportEntry

The opening entry an opening_balances import posted or queued.

ImportIssue

One problem found in the file, or one thing worth knowing.

ImportSummary

What the import created (or, in a dry run, would create).

SalesforceImportResult

SalesforceSummary

What the import created (or, in a dry run, would create).