Submit a bulk import job for a resource type
Accepts up to 1000 records for one of 17 supported resource types (accounts, products, orders, journal-entries, vendor-bills, ap-payments, product-categories, product-variants, product-pricing-policies, product-vendors, product-prepackaged-presets, customer-payments, inventory-balances-opening-stock, inventory-balances-set-opening-stock, inventory-transactions, order-tax-lines, account-addresses). Returns 202 + job_id for async processing. Returns 200 + dry_run result if ?dry_run=true (no DB writes made). Idempotency-Key header deduplicates concurrent submissions. THE ONE RULE: this endpoint is a thin loop over canonical handlers; it does NOT write directly to any resource table.
Authorizations
API key issued per entity via Settings > Developers > API Keys.
Each key carries scopes (e.g. orders:read, products:write).
Bearer token format: Authorization: Bearer ark_live_ent_Test keys use ark_test_ent_. Both are issued per entity
via Settings > Developers > API Keys.
Headers
Client-generated unique key for idempotent POST/PATCH/DELETE operations. Max 255 chars. On retry with the same key, the original response is returned without re-executing the operation. Keys expire after 24 hours. Pattern: or --.
255Path Parameters
accounts, products, orders, journal-entries, vendor-bills, ap-payments, product-categories, product-variants, product-pricing-policies, product-vendors, product-prepackaged-presets, customer-payments, inventory-balances-opening-stock, inventory-balances-set-opening-stock, inventory-transactions, inventory-movements, order-tax-lines, account-addresses, account-contacts, purchase-orders, returns, vendor-credits Query Parameters
If true, runs validation synchronously and returns results without any DB writes.
Body
1 - 1000 elementsSource system identifier (e.g. "versa_cloud", "quickbooks_online", "netsuite", "shopify_export"). Required. Persisted on every record's external_source column. Used by GET /v1/entities/{entity_id}/reconciliation/counts?external_source= to filter counts to a specific source.
60How to handle a record whose (external_source, external_id) already exists in Arcus.
- skip: leave the existing record unchanged, count as success
- update: call the canonical UPDATE handler with the incoming payload
- replace: NULL out the existing record's provenance UNIQUE, then INSERT new record
- error: abort the entire batch on the first collision (default if not specified: skip)
skip, update, replace, error Optional batch identifier you generate once per logical migration "wave" and pass on every record. Persisted on every record's migration_batch_id column. Used to group records that were imported together for later reconciliation or rollback.
If true, the records are validated end-to-end but no DB writes occur. Useful for catching missing required fields and FK violations before committing a real import.
Response
Dry-run result (no writes made)

