Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.arcuserp.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

This guide explains how to migrate your existing data into Arcus using the public API. Whether you are migrating from another ERP, importing a CSV export, or writing a custom loader, the same principles apply: use the API endpoints your integration will use in production, include idempotency keys for safe retries, and import in dependency order. Estimated time: 2-4 hours for a typical dataset (under 100K records per resource type).

​
Prerequisites

Before starting:
  1. An Arcus entity provisioned by your account manager
  2. An API key with accounts:write, products:write, orders:write, inventory:write, purchasing:write, payments:write scopes
  3. Your source data exported to a structured format (CSV, JSON, or database dump)
  4. Node.js 20 or later installed locally (if using the reference migration scripts)

​
Migration order

Data must be imported in dependency order. Arcus enforces referential integrity; importing in the wrong order causes validation errors.
StepResourceDepends on
1Locations(none)
2Payment Terms(none)
3Units of Measure(none)
4Product Categories(none)
5Accounts (customers + vendors)Payment Terms
6ProductsCategories, UoM
7Inventory balancesProducts, Locations
8Purchase OrdersVendors, Products
9Sales Orders + InvoicesCustomers, Products
10PaymentsOrders
11ReturnsOrders

​
Step 1: Configure your environment

export ARCUS_API_KEY="ark_live_ent_acme_..."
export ARCUS_ENTITY_ID="your-entity-uuid"
export ARCUS_BASE_URL="https://api.arcuserp.com/v1"
Start with a test-mode key (ark_test_ent_...) against your test data before switching to live mode.

​
Step 2: Validate your source data

Before importing, validate your source records:
  • Required fields are non-null
  • Foreign key references can be resolved (e.g. account on orders)
  • Date formats are parseable (ISO 8601)
  • Numeric fields are within expected ranges
Fix validation errors before proceeding. Log a report to a file for tracking.

​
Step 3: Import records

Use the API endpoints directly. Always include Idempotency-Key on every POST so retries are safe: 
# Create an account
curl -X POST "$ARCUS_BASE_URL/entities/$ARCUS_ENTITY_ID/accounts" \
  -H "Authorization: Bearer $ARCUS_API_KEY" \
  -H "Idempotency-Key: import-account-$(echo $SOURCE_ID | md5)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "account_type": "business",
    "source_system": "legacy-erp",
    "source_id": "CUST-1234"
  }'
The source_system and source_id fields let you track the original record and detect duplicates across runs.

​
Step 4: Verify

After importing each resource type:
  1. Count records returned from GET /entities/{entity_id}/{resource} vs your source
  2. Spot-check random records for field accuracy
  3. Check inventory balances against your source totals
  4. Check AR balance against open invoices

​
Resuming an interrupted migration

Use the source_id field as a checkpoint: before inserting a record, query by source_id to check if it was already imported. If it exists, skip it. This makes your import script idempotent and safe to re-run. 
# Check if account was already imported
curl "$ARCUS_BASE_URL/entities/$ARCUS_ENTITY_ID/accounts?source_id=CUST-1234" \
  -H "Authorization: Bearer $ARCUS_API_KEY"

​
Rollback

If you need to start over, records tagged with your source_system value can be identified and deleted. Deletion is only safe before the entity goes live; contact your account manager for guidance on large-scale rollbacks.

​
Getting help

  • API errors: check request_id in error responses and include it in your support ticket
  • Data questions: your Arcus account manager can review your import plan
  • Use the in-app Help button for migration-specific support