Create an account

Creates a new account with its complete B2B onboarding graph in a single atomic call.

Atomic create: supply addresses[], contacts[], payment_methods[], and tags[] inline. All children are written in one database transaction — any child failure rolls back the parent and every already-inserted child. The 201 response includes all children hydrated inline; no follow-up GETs required.

name is required. Accepted aliases: display_name, company_name, or first_name+last_name. Without a name the request returns 422.

entity_id is extracted from the API key and may NOT be supplied in the request body (Layer 1 isolation). Auto-assigns account_number, default_pricing_level_id, payment_term_id, and default_location_id from entity settings.

Address field aliases: street1/region/postal_code are accepted as Stripe-style aliases for line1/state/zip.

Contact field aliases: role is accepted as a public alias for the title field.

Tag auto-create: tags supplied by name are auto-created for the entity if they do not exist. Applying the same tag twice is idempotent.

Side effects:

• Shopify customer sync fires post-commit if entity.settings.shopify_sync.customer_sync = true.
• AvaTax recalc fires if tax_exempt or avatax_entity_code is set.

Idempotent when Idempotency-Key header is supplied (24-hour window).

Guide: Creating accounts with addresses

POST /accounts

Create an account

cURL

curl --request POST \
  --url https://api.arcuserp.com/v1/accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "account_type": "business",
  "name": "Acme Wholesale",
  "email": "[e-mail]",
  "phone": "[phone]",
  "credit_limit": 25000,
  "addresses": [
    {
      "type": "billing",
      "label": "HQ",
      "is_default_billing": true,
      "street1": "1 Acme Way",
      "city": "Austin",
      "region": "TX",
      "postal_code": "78701",
      "country": "US"
    },
    {
      "type": "shipping",
      "label": "Main Warehouse",
      "is_default_shipping": true,
      "street1": "100 Industrial Dr",
      "city": "Austin",
      "region": "TX",
      "postal_code": "78702",
      "country": "US"
    },
    {
      "type": "shipping",
      "label": "Branch Warehouse",
      "street1": "200 Branch Rd",
      "city": "Houston",
      "region": "TX",
      "postal_code": "77001",
      "country": "US"
    }
  ],
  "contacts": [
    {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "[e-mail]",
      "phone": "[phone]",
      "is_primary": true,
      "role": "AP"
    },
    {
      "first_name": "John",
      "last_name": "Smith",
      "email": "[e-mail]",
      "role": "Operations"
    }
  ],
  "payment_methods": [
    {
      "stripe_payment_method_id": "pm_card_visa",
      "is_default": true
    }
  ],
  "tags": [
    "VIP",
    "Wholesale-Tier-1"
  ]
}
'

201

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "object": "account",
    "entity_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "display_name": "<string>",
    "company_name": "<string>",
    "account_number": "<string>",
    "email": "<string>",
    "phone_main": "<string>",
    "phone_secondary": "<string>",
    "phone_mobile": "<string>",
    "website": "<string>",
    "payment_term_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "credit_limit": 123,
    "credit_balance": 123,
    "is_credit_hold": true,
    "tax_exempt": true,
    "avatax_entity_code": "<string>",
    "tax_number": "<string>",
    "default_pricing_level_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "default_location_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "default_shipping_method": "<string>",
    "enable_pro_portal": true,
    "is_active": true,
    "notes": "<string>",
    "metadata": {},
    "stripe_customer_id": "<string>",
    "source_platform": "<string>",
    "external_customer_id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  }
}

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

Optional idempotency key for safe retries.

Maximum string length: 255

Body

application/json

Creates a new account with its full onboarding graph in one atomic request.

Required fields: name (or display_name/company_name/first_name+last_name) and account_type.

Nested children (all optional, all atomic):

• addresses[]: billing and/or shipping addresses. Supports street1/region/postal_code (Stripe-style aliases) or line1/state/zip (canonical). First address of each type auto-becomes the default.
• contacts[]: person contacts. role is a public alias for the title field. At most one is_primary: true.
• payment_methods[]: Stripe payment methods via stripe_payment_method_id (the pm_* token from a completed SetupIntent). Requires Stripe to be configured for the entity.
• tags[]: tag names to apply. Tags are auto-created if they do not exist for the entity.

Transaction guarantee: all children are written in a single database transaction. Any child failure rolls back the parent account and every already-inserted child. You get a complete graph or nothing.

Hydrated response: the 201 body includes addresses, contacts, payment_methods, and tags arrays inline. No follow-up GETs required.

See also: Creating accounts with addresses guide

name · string · required

Human-readable name for the account. Required. Aliases: display_name (business), company_name (business), or first_name+last_name (individual). All are accepted; name is the canonical public API field.

account_type · enum<string> · required

Available options: business, individual, lead, vendor

display_name · string | null

Alias for name. Auto-derived from company_name or first+last if omitted.

company_name · string | null

first_name · string | null

For individual accounts.

last_name · string | null

For individual accounts.

email · string | null

phone · string | null

Maps to phone_main internally.

phone_main · string | null

phone_secondary · string | null

phone_mobile · string | null

website · string | null

payment_term_id · string<uuid> | null

Must reference an existing payment_terms row for this entity.

pricing_level_id · string<uuid> | null

Alias for default_pricing_level_id.

credit_limit · number | null

Credit ceiling in USD. Returned as a JS number (float), never a string.

tax_exempt · boolean

avatax_entity_code · string | null

tax_number · string | null

default_pricing_level_id · string<uuid> | null

default_location_id · string<uuid> | null

default_shipping_method · string | null

notes · string | null

metadata · object | null

addresses · object[]

Billing and/or shipping addresses to create atomically with the account. Supports street1/region/postal_code (Stripe-style) OR line1/state/zip (canonical). At most one address per type may have is_default_billing: true or is_default_shipping: true.

Show child attributes

contacts · object[]

Person contacts to create atomically with the account. If omitted, an auto-generated primary contact is created from account-level name/email/phone. At most one contact may have is_primary: true. role is the public API alias for the internal title field.

Show child attributes

payment_methods · object[]

Stripe payment methods to attach atomically with the account. Each item requires a stripe_payment_method_id (the pm_* token from a completed Stripe SetupIntent or test card). Requires Stripe to be configured for the entity.

Show child attributes

tags · string[]

Tag names to apply to the account. Tags are auto-created if they do not exist for the entity (using the name as the slug base). Idempotent: applying the same tag twice is a no-op.

Response

201

application/json

Account created

data · object

An Arcus ERP account. Represents a customer, vendor, lead, or individual. account_type drives AR vs AP behavior: business/individual/lead = customer (AR); vendor = supplier (AP). entity_id is always from the API key (Layer 1 isolation).

Show child attributes