Skip to main content
POST
Submit a bulk import job for a resource type

Authorizations

Authorization
string
header
required

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

Idempotency-Key
string

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 --.

Maximum string length: 255

Path Parameters

entity_id
string<uuid>
required
resource
enum<string>
required
Available options:
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

dry_run
boolean

If true, runs validation synchronously and returns results without any DB writes.

Body

application/json
records
object[]
required
Required array length: 1 - 1000 elements
external_source
string
required

Source 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.

Maximum string length: 60
conflict_mode
enum<string>
default:skip

How 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)
Available options:
skip,
update,
replace,
error
migration_batch_id
string<uuid>

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.

dry_run
boolean
default:false

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)

Dry-run result (200 response for ?dry_run=true). No DB writes made.

object
enum<string>
Available options:
migration_dry_run_result
dry_run
enum<boolean>
Available options:
true
resource
string
external_source
string
total_records
integer
succeeded_records
integer
failed_records
integer
errors
object[]