Quickstart

1. Get an API key

Sign in to app.arcuserp.com, open Settings, then click Developers. On the API Keys tab, click Create API key.

Name: give it a descriptive label (e.g. My Integration)
Mode: choose Test for sandbox or Live for production
Scopes: select at minimum accounts:read to follow this guide

You will see the key once. Copy it now.

export ARCUS_API_KEY="ark_test_ent_acme_..."

API keys are entity-scoped. The entity is encoded in the key itself, so the everyday resource routes are flat (for example /v1/accounts and /v1/orders) and every request is automatically scoped to the entity that issued the key. You do not put the entity ID in the URL for these routes.

When you need your entity ID

A small set of platform endpoints, such as the reconciliation and migration routes, use the /v1/entities/{entity_id}/... form. For those you need your entity ID, a UUID that identifies your organization in Arcus. Easiest way: Go to Settings > Developers > API Keys. The Quick Reference panel at the top of the page shows your Entity ID with a copy button right next to it.

The Quick Reference panel also shows the correct API Base URL for your current mode (Test or Live). Toggle between modes using the Test / Live switcher at the top of the Developers page.

If you plan to call those platform endpoints, set the entity ID as an environment variable too:

export ARCUS_ENTITY_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

2. Make your first request

List the first five accounts in your entity:

curl "https://api.arcuserp.com/v1/accounts?limit=5" \
  -H "Authorization: Bearer $ARCUS_API_KEY"

import Arcus from '@arcuserp/sdk-node';

const arcus = new Arcus({
  apiKey: process.env.ARCUS_API_KEY,
  entityId: process.env.ARCUS_ENTITY_ID,
});

const accounts = await arcus.accounts.list({ limit: 5 });
console.log(accounts.data);

from arcuserp import Arcus
import os

arcus = Arcus(
    api_key=os.environ['ARCUS_API_KEY'],
    entity_id=os.environ['ARCUS_ENTITY_ID'],
)

accounts = arcus.accounts.list(limit=5)
for a in accounts.data:
    print(a.name)

import (
    "context"
    "fmt"
    "os"

    arcus "go.arcuserp.com/sdk"
)

client := arcus.NewClient(
    os.Getenv("ARCUS_API_KEY"),
    arcus.WithEntityID(os.Getenv("ARCUS_ENTITY_ID")),
)

accounts, err := client.Accounts.List(context.Background(), &arcus.AccountListParams{
    Limit: arcus.Int(5),
})
if err != nil {
    panic(err)
}
for _, a := range accounts.Data {
    fmt.Println(a.Name)
}

3. Understand the response

Every list endpoint returns the same envelope:

{
  "object": "list",
  "data": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "object": "account",
      "display_name": "Acme Corp",
      "account_type": "business",
      "entity_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "has_more": true,
  "url": "/v1/accounts"
}

To get the next page, pass starting_after with the id of the last record in data:

curl "https://api.arcuserp.com/v1/accounts?limit=5&starting_after=<last-id-in-data>" \
  -H "Authorization: Bearer $ARCUS_API_KEY"

See Pagination for the full cursor contract.

4. Create your first order

curl -X POST https://api.arcuserp.com/v1/orders \
  -H "Authorization: Bearer $ARCUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "sales_order",
    "account_id": "<account-id>",
    "line_items": [
      {
        "product_id": "<product-id>",
        "quantity": 10,
        "unit_price": 25.00
      }
    ]
  }'

Always include an Idempotency-Key on POST/PATCH/DELETE requests. If the request fails due to a network error, retrying with the same key returns the original response without creating a duplicate. See Idempotency.

Next steps

Authentication

Entity-scoped keys, scopes, and IP allowlists.

Concepts

Idempotency, pagination, expand, errors, and more.

API Reference

Every endpoint documented with try-it-now.

Webhooks

Subscribe to real-time order, payment, and fulfillment events.

Get Started

Concepts

Guides

SDKs

Collections

1. Get an API key

When you need your entity ID

2. Make your first request

3. Understand the response

4. Create your first order

Next steps

Authentication

Concepts

API Reference

Webhooks

​1. Get an API key

​When you need your entity ID

​2. Make your first request

​3. Understand the response

​4. Create your first order

​Next steps

Authentication

Concepts

API Reference

Webhooks

1. Get an API key

When you need your entity ID

2. Make your first request

3. Understand the response

4. Create your first order

Next steps