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.

POST /entities/{entity_id}/migration/{resource}/bulk

Submit a bulk import job for a resource type

cURL

curl --request POST \
  --url https://api.arcuserp.com/v1/entities/{entity_id}/migration/{resource}/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "records": [
    {}
  ],
  "external_source": "<string>",
  "conflict_mode": "skip",
  "migration_batch_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "dry_run": false
}
'

200

{
  "object": "migration_dry_run_result",
  "dry_run": true,
  "resource": "<string>",
  "external_source": "<string>",
  "total_records": 123,
  "succeeded_records": 123,
  "failed_records": 123,
  "errors": [
    {}
  ]
}

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

200

application/json

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[]