Skip to main content

​
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_..."
export ARCUS_ENTITY_ID="your-entity-uuid"
API keys are entity-scoped. The entity ID is part of the URL path: /v1/entities/{entity_id}/{resource}. Every request is automatically scoped to the entity that issued the key.

​
Where to find your entity ID

Your entity ID is a UUID that identifies your organization in Arcus. You need it for every API request. 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.
Once you have both values, set them as environment variables: 
export ARCUS_API_KEY="ark_test_ent_acme_..."
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/entities/$ARCUS_ENTITY_ID/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 "github.com/arcuserp/sdk-go"
)

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": "acc_01H...",
      "object": "account",
      "name": "Acme Corp",
      "account_type": "business",
      "entity_id": "ent_01H...",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "has_more": true,
  "url": "/v1/entities/{entity_id}/accounts"
}
To get the next page, pass starting_after with the last ID in data: 
curl "https://api.arcuserp.com/v1/entities/$ARCUS_ENTITY_ID/accounts?limit=5&starting_after=acc_01H..." \
  -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/entities/$ARCUS_ENTITY_ID/orders \
  -H "Authorization: Bearer $ARCUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "sales_order",
    "account_id": "acc_01H...",
    "line_items": [
      {
        "product_id": "prod_01H...",
        "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.