Skip to main content
POST
/
accounts
Create an account
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": "ap@acme.example",
  "phone": "+1-555-0100",
  "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": "jane@acme.example",
      "phone": "+1-555-0101",
      "is_primary": true,
      "role": "AP"
    },
    {
      "first_name": "John",
      "last_name": "Smith",
      "email": "john@acme.example",
      "role": "Operations"
    }
  ],
  "payment_methods": [
    {
      "stripe_payment_method_id": "pm_card_visa",
      "is_default": true
    }
  ],
  "tags": [
    "VIP",
    "Wholesale-Tier-1"
  ]
}
'
import requests

url = "https://api.arcuserp.com/v1/accounts"

payload = {
    "account_type": "business",
    "name": "Acme Wholesale",
    "email": "ap@acme.example",
    "phone": "+1-555-0100",
    "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": "jane@acme.example",
            "phone": "+1-555-0101",
            "is_primary": True,
            "role": "AP"
        },
        {
            "first_name": "John",
            "last_name": "Smith",
            "email": "john@acme.example",
            "role": "Operations"
        }
    ],
    "payment_methods": [
        {
            "stripe_payment_method_id": "pm_card_visa",
            "is_default": True
        }
    ],
    "tags": ["VIP", "Wholesale-Tier-1"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    account_type: 'business',
    name: 'Acme Wholesale',
    email: 'ap@acme.example',
    phone: '+1-555-0100',
    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: 'jane@acme.example',
        phone: '+1-555-0101',
        is_primary: true,
        role: 'AP'
      },
      {
        first_name: 'John',
        last_name: 'Smith',
        email: 'john@acme.example',
        role: 'Operations'
      }
    ],
    payment_methods: [{stripe_payment_method_id: 'pm_card_visa', is_default: true}],
    tags: ['VIP', 'Wholesale-Tier-1']
  })
};

fetch('https://api.arcuserp.com/v1/accounts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.arcuserp.com/v1/accounts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'account_type' => 'business',
    'name' => 'Acme Wholesale',
    'email' => 'ap@acme.example',
    'phone' => '+1-555-0100',
    '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' => 'jane@acme.example',
                'phone' => '+1-555-0101',
                'is_primary' => true,
                'role' => 'AP'
        ],
        [
                'first_name' => 'John',
                'last_name' => 'Smith',
                'email' => 'john@acme.example',
                'role' => 'Operations'
        ]
    ],
    'payment_methods' => [
        [
                'stripe_payment_method_id' => 'pm_card_visa',
                'is_default' => true
        ]
    ],
    'tags' => [
        'VIP',
        'Wholesale-Tier-1'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.arcuserp.com/v1/accounts"

	payload := strings.NewReader("{\n  \"account_type\": \"business\",\n  \"name\": \"Acme Wholesale\",\n  \"email\": \"ap@acme.example\",\n  \"phone\": \"+1-555-0100\",\n  \"credit_limit\": 25000,\n  \"addresses\": [\n    {\n      \"type\": \"billing\",\n      \"label\": \"HQ\",\n      \"is_default_billing\": true,\n      \"street1\": \"1 Acme Way\",\n      \"city\": \"Austin\",\n      \"region\": \"TX\",\n      \"postal_code\": \"78701\",\n      \"country\": \"US\"\n    },\n    {\n      \"type\": \"shipping\",\n      \"label\": \"Main Warehouse\",\n      \"is_default_shipping\": true,\n      \"street1\": \"100 Industrial Dr\",\n      \"city\": \"Austin\",\n      \"region\": \"TX\",\n      \"postal_code\": \"78702\",\n      \"country\": \"US\"\n    },\n    {\n      \"type\": \"shipping\",\n      \"label\": \"Branch Warehouse\",\n      \"street1\": \"200 Branch Rd\",\n      \"city\": \"Houston\",\n      \"region\": \"TX\",\n      \"postal_code\": \"77001\",\n      \"country\": \"US\"\n    }\n  ],\n  \"contacts\": [\n    {\n      \"first_name\": \"Jane\",\n      \"last_name\": \"Doe\",\n      \"email\": \"jane@acme.example\",\n      \"phone\": \"+1-555-0101\",\n      \"is_primary\": true,\n      \"role\": \"AP\"\n    },\n    {\n      \"first_name\": \"John\",\n      \"last_name\": \"Smith\",\n      \"email\": \"john@acme.example\",\n      \"role\": \"Operations\"\n    }\n  ],\n  \"payment_methods\": [\n    {\n      \"stripe_payment_method_id\": \"pm_card_visa\",\n      \"is_default\": true\n    }\n  ],\n  \"tags\": [\n    \"VIP\",\n    \"Wholesale-Tier-1\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.arcuserp.com/v1/accounts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"account_type\": \"business\",\n  \"name\": \"Acme Wholesale\",\n  \"email\": \"ap@acme.example\",\n  \"phone\": \"+1-555-0100\",\n  \"credit_limit\": 25000,\n  \"addresses\": [\n    {\n      \"type\": \"billing\",\n      \"label\": \"HQ\",\n      \"is_default_billing\": true,\n      \"street1\": \"1 Acme Way\",\n      \"city\": \"Austin\",\n      \"region\": \"TX\",\n      \"postal_code\": \"78701\",\n      \"country\": \"US\"\n    },\n    {\n      \"type\": \"shipping\",\n      \"label\": \"Main Warehouse\",\n      \"is_default_shipping\": true,\n      \"street1\": \"100 Industrial Dr\",\n      \"city\": \"Austin\",\n      \"region\": \"TX\",\n      \"postal_code\": \"78702\",\n      \"country\": \"US\"\n    },\n    {\n      \"type\": \"shipping\",\n      \"label\": \"Branch Warehouse\",\n      \"street1\": \"200 Branch Rd\",\n      \"city\": \"Houston\",\n      \"region\": \"TX\",\n      \"postal_code\": \"77001\",\n      \"country\": \"US\"\n    }\n  ],\n  \"contacts\": [\n    {\n      \"first_name\": \"Jane\",\n      \"last_name\": \"Doe\",\n      \"email\": \"jane@acme.example\",\n      \"phone\": \"+1-555-0101\",\n      \"is_primary\": true,\n      \"role\": \"AP\"\n    },\n    {\n      \"first_name\": \"John\",\n      \"last_name\": \"Smith\",\n      \"email\": \"john@acme.example\",\n      \"role\": \"Operations\"\n    }\n  ],\n  \"payment_methods\": [\n    {\n      \"stripe_payment_method_id\": \"pm_card_visa\",\n      \"is_default\": true\n    }\n  ],\n  \"tags\": [\n    \"VIP\",\n    \"Wholesale-Tier-1\"\n  ]\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.arcuserp.com/v1/accounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"account_type\": \"business\",\n  \"name\": \"Acme Wholesale\",\n  \"email\": \"ap@acme.example\",\n  \"phone\": \"+1-555-0100\",\n  \"credit_limit\": 25000,\n  \"addresses\": [\n    {\n      \"type\": \"billing\",\n      \"label\": \"HQ\",\n      \"is_default_billing\": true,\n      \"street1\": \"1 Acme Way\",\n      \"city\": \"Austin\",\n      \"region\": \"TX\",\n      \"postal_code\": \"78701\",\n      \"country\": \"US\"\n    },\n    {\n      \"type\": \"shipping\",\n      \"label\": \"Main Warehouse\",\n      \"is_default_shipping\": true,\n      \"street1\": \"100 Industrial Dr\",\n      \"city\": \"Austin\",\n      \"region\": \"TX\",\n      \"postal_code\": \"78702\",\n      \"country\": \"US\"\n    },\n    {\n      \"type\": \"shipping\",\n      \"label\": \"Branch Warehouse\",\n      \"street1\": \"200 Branch Rd\",\n      \"city\": \"Houston\",\n      \"region\": \"TX\",\n      \"postal_code\": \"77001\",\n      \"country\": \"US\"\n    }\n  ],\n  \"contacts\": [\n    {\n      \"first_name\": \"Jane\",\n      \"last_name\": \"Doe\",\n      \"email\": \"jane@acme.example\",\n      \"phone\": \"+1-555-0101\",\n      \"is_primary\": true,\n      \"role\": \"AP\"\n    },\n    {\n      \"first_name\": \"John\",\n      \"last_name\": \"Smith\",\n      \"email\": \"john@acme.example\",\n      \"role\": \"Operations\"\n    }\n  ],\n  \"payment_methods\": [\n    {\n      \"stripe_payment_method_id\": \"pm_card_visa\",\n      \"is_default\": true\n    }\n  ],\n  \"tags\": [\n    \"VIP\",\n    \"Wholesale-Tier-1\"\n  ]\n}"

response = http.request(request)
puts response.read_body
{
  "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"
  }
}
{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}
{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}
{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}
{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

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.

​
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.

​
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.

​
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

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).