Batch Import Data

Post

/v1/import

Imports a batch of records based on the specified type. This endpoint uses a Partial Success model - if some records fail validation, valid records are still imported.

Batch Limits: Maximum 100 records per request.

Import Types

Type	Required Fields	Description
`Suppliers`	`id`, `name`	Vendor/supplier master data
`Items`	`id`, `name`	Item/product master data
`PurchaseOrders`	`supplierId`, (`id` or `ref`)	Purchase order records
`ItemReceipts`	`supplierId`, `receiptDate`, (`id` or `ref`)	Item receipt records

Suppliers

Import vendor/supplier master data.

Required fields: id, name

Field	Type	Description
id	string	Vendor ID. Required.
name	string	Vendor name. Required.
created	string	Timestamp (YYYY-MM-DD HH:mm:ss). Defaults to current time.
modified	string	Timestamp (YYYY-MM-DD HH:mm:ss). Defaults to current time.
parentId	string	Reference to parent record ID.
legalName	string	Legal business name. Defaults to vendor name.
contacts	array	List of contacts (firstName, lastName, email, phone).
address	object	Address (addr1, addr2, city, state, zipcode, country).
accountNumber	string	Account number with the vendor.
website	string	Vendor website URL.
notes	string	Notes about the vendor.
currency	string	3-digit currency code (e.g., USD).
taxId	string	Vendor tax ID.
is1099	boolean	Report 1099. Defaults to false.
active	boolean	Record is active. Defaults to true.

Items

Import item/product master data.

Required fields: id, name

Field	Type	Description
id	string	Item ID. Required.
name	string	Item display name. Required.
created	string	Timestamp (YYYY-MM-DD HH:mm:ss).
modified	string	Timestamp (YYYY-MM-DD HH:mm:ss).
parentId	string	Reference to parent item ID.
description	string	Item description.
sku	string	Item SKU.
type	string	`Inventory`, `NonInventory`, or `Service`.
expenseAccountId	string	GL expense account ID.
incomeAccountId	string	GL income account ID.
assetAccountId	string	GL asset account ID.
active	integer	0 = inactive, 1 = active.

Purchase Orders

Import purchase order records.

Required fields: supplierId, and either id or ref

Field	Type	Description
id	string	Internal ID. Either `id` or `ref` required.
ref	string	External reference. Either `id` or `ref` required.
supplierId	string	Vendor ID. Required.
created	string	Timestamp (YYYY-MM-DD HH:mm:ss).
modified	string	Timestamp (YYYY-MM-DD HH:mm:ss).
apAccountId	string	AP account reference ID.
classId	string	Accounting class reference ID.
date	string	Issue date (YYYY-MM-DD).
dueDate	string	Payment due date (YYYY-MM-DD).
description	string	PO memo or description.
notes	string	Notes to the vendor.
isClosed	integer	0 = open, 1 = closed.
isReceived	integer	0 = no, 1 = yes.
amount	number	Total amount.
lineItems	array	Line items (see below).

Line Item fields:

id (string) - Line item identifier.
itemId (string) - Reference to item master record.
accountId (string) - GL account reference ID.
customerId (string) - Customer reference for billable items.
classId (string) - Accounting class reference ID.
description (string) - Item description.
qty (number) - Quantity.
price (number) - Unit price.
total (number) - Line total.

Item Receipts

Import item receipt records.

Required fields: supplierId, receiptDate, and either id or ref

Field	Type	Description
id	string	Internal ID. Either `id` or `ref` required.
ref	string	External reference. Either `id` or `ref` required.
supplierId	string	Vendor ID. Required.
receiptDate	string	Date received (YYYY-MM-DD). Required.
created	string	Timestamp (YYYY-MM-DD HH:mm:ss).
modified	string	Timestamp (YYYY-MM-DD HH:mm:ss).
apAccountId	string	AP account reference ID.
classId	string	Accounting class reference ID.
date	string	Issue date (YYYY-MM-DD).
dueDate	string	Payment due date (YYYY-MM-DD).
description	string	Receipt memo or description.
notes	string	Notes to the vendor.
isClosed	integer	0 = open, 1 = closed.
isReceived	integer	0 = no, 1 = yes.
amount	number	Total amount.
lineItems	array	Line items (see below).

Line Item fields:

id (string) - Line item identifier.
itemId (string) - Reference to item master record.
accountId (string) - GL account reference ID.
customerId (string) - Customer reference for billable items.
classId (string) - Accounting class reference ID.
description (string) - Item description.
qty (number) - Quantity ordered.
price (number) - Unit price.
total (number) - Line total.
receivedQty (number) - Quantity received.
receivedTotal (number) - Received line total.

Handling Responses

Your code must check the rejected array in the response. If present and not empty, those records failed to import.

Security

HTTP

Type bearer

Enter your API token.

Body parameters

suppliers

Import Suppliers

{
  "type": "Suppliers",
  "data": [
    {
      "id": "SUP-001",
      "name": "Acme Corporation",
      "created": "2025-01-15T10:00:00Z",
      "modified": "2025-01-15T10:00:00Z",
      "legalName": "Acme Corporation Inc.",
      "contacts": [
        {
          "firstName": "John",
          "lastName": "Smith",
          "email": "john.smith@acme.com",
          "phone": "555-123-4567"
        }
      ],
      "address": {
        "addr1": "123 Main Street",
        "addr2": "Suite 100",
        "city": "New York",
        "state": "NY",
        "zipcode": "10001",
        "country": "US"
      },
      "accountNumber": "ACC-12345",
      "website": "https://acme.com",
      "notes": "Preferred vendor for office supplies",
      "currency": "USD",
      "taxId": "12-3456789",
      "is1099": true,
      "active": true
    }
  ]
}

items

Import Items

{
  "type": "Items",
  "data": [
    {
      "id": "ITEM-001",
      "name": "PLC Controller",
      "created": "2025-06-01T10:00:00Z",
      "modified": "2025-06-03T14:25:00Z",
      "description": "Programmable Logic Controller",
      "sku": "PLC-123",
      "type": "NonInventory",
      "expenseAccountId": "EXP-100",
      "incomeAccountId": "INC-200",
      "active": 1
    }
  ]
}

purchaseOrders

Import Purchase Orders

{
  "type": "PurchaseOrders",
  "data": [
    {
      "id": "PO-001",
      "ref": "PO-2024-001",
      "supplierId": "SUP-123",
      "created": "2025-01-15T10:00:00Z",
      "modified": "2025-01-15T10:00:00Z",
      "apAccountId": "AP-001",
      "classId": "CLASS-100",
      "date": "2024-01-15",
      "dueDate": "2024-02-15",
      "amount": 1500.0,
      "description": "Office supplies order",
      "notes": "Deliver before noon",
      "isClosed": 0,
      "isReceived": 0,
      "lineItems": [
        {
          "id": "LINE-001",
          "itemId": "ITEM-001",
          "accountId": "EXP-100",
          "classId": "CLASS-100",
          "description": "Paper",
          "qty": 100,
          "price": 10.0,
          "total": 1000.0
        },
        {
          "id": "LINE-002",
          "itemId": "ITEM-002",
          "accountId": "EXP-100",
          "classId": "CLASS-100",
          "description": "Pens",
          "qty": 50,
          "price": 10.0,
          "total": 500.0
        }
      ]
    }
  ]
}

itemReceipts

Import Item Receipts

{
  "type": "ItemReceipts",
  "data": [
    {
      "id": "PO-1001",
      "created": "2025-06-01T10:00:00Z",
      "modified": "2025-06-03T14:25:00Z",
      "ref": "PO-INV-001",
      "receiptDate": "2025-06-03",
      "supplierId": "SUP-456",
      "apAccountId": "AP-001",
      "classId": "CLASS-100",
      "date": "2025-06-01",
      "dueDate": "2025-06-10",
      "description": "Office supply restock",
      "notes": "Deliver before noon",
      "isClosed": 1,
      "isReceived": 1,
      "amount": 305.0,
      "lineItems": [
        {
          "id": "PO-LI-001",
          "itemId": "ITEM-001",
          "accountId": "EXP-100",
          "customerId": "CUST-001",
          "classId": "CLASS-100",
          "qty": 5,
          "price": 20,
          "total": 100,
          "description": "Printer paper (500 sheets)",
          "receivedQty": 5,
          "receivedTotal": 100
        },
        {
          "id": "PO-LI-002",
          "itemId": "ITEM-002",
          "accountId": "EXP-200",
          "customerId": null,
          "classId": "CLASS-100",
          "qty": 1,
          "price": 205,
          "total": 205,
          "description": "Office chair",
          "receivedQty": 1,
          "receivedTotal": 205
        }
      ]
    }
  ]
}

Expand All

object

type

string Required

The type of records to import.

Valid values[ "Suppliers", "Items", "PurchaseOrders", "ItemReceipts" ]

data

Array of object Required

Array of records to import. Maximum 100 items per request.

Max items100

object

Responses

200

Batch processed (Check body for partial failures)

allAccepted

All Records Accepted

{
  "status": "OK",
  "msg": "Data imported",
  "result": {
    "accepted": 2,
    "rejected": []
  }
}

partialSuccess

Partial Success (Some Rejected)

{
  "status": "OK",
  "msg": "Data imported",
  "result": {
    "accepted": 1,
    "rejected": [
      {
        "index": 1,
        "msg": "Missing Supplier ID"
      }
    ]
  }
}

Expand All

object

status

string

Result status.

Valid values[ "OK", "Error" ]

msg

string

Result message.

result

object | null

accepted

integer

Number of records successfully imported.

rejected

Array of object

Records that failed validation.

object

index

integer

Zero-based index of the failed record.

msg

string

Validation error message.

400

Bad Request (Invalid JSON or Type)

invalidType

Invalid Import Type

{
  "status": "Error",
  "msg": "Invalid import type",
  "result": null
}

Expand All

object

status

string

Result status.

Valid values[ "OK", "Error" ]

msg

string

Result message.

result

object | null

accepted

integer

Number of records successfully imported.

rejected

Array of object

Records that failed validation.

object

index

integer

Zero-based index of the failed record.

msg

string

Validation error message.

401

Unauthorized

415

Unsupported Media Type