Accounts¶

Accounts represent customers (buyers) in the Billtrust system. They are the top-level resource — documents, notes, representatives, and contacts all attach to an account.

POST /accounts/{account_number}¶

Creates a new account. Returns 409 if the account number already exists for this tenant. Use PUT for an idempotent upsert.

Path Parameters¶

Parameter	Description
`account_number`	Caller-defined unique identifier for this account within the tenant.

Request Body¶

Field	Type	Required	Description
name	string	Yes	Account display name. Must not be empty.
display_reference	string	No	Short reference shown in the UI. Also used as the CashApp location-level customer identifier for payment matching.
currency	string (ISO 4217)	Conditional	Required when the tenant uses the basic currency model. Locked on first write.
language	string (ISO 639-1)	No	Used for Collections communications.
billing_address	Address object	No	See Shared Schemas.
remit_to	Address object	No	Remittance address.
phone	string	No
mobile_phone	string	No
fax	string	No
email	string	No	Primary email. Used for Collections reminders.
payment_terms	string	No	e.g. `NET30`
credit_limit	number	No
account_group	string	No	Grouping/segment label.
parent_account_number	string	No	Groups accounts into a parent-child hierarchy.
is_parent_account	boolean	No	Marks this account as the parent. Required when `parent_account_number` is set.
branch_name	string	No	Controls virtual eInvoice Connect site assignment and PDF branding.
description	string	No
vat	string	No	VAT registration number.
company_registration_number	string	No
data_providers	object	No	Credit provider identifiers. Passthrough object — any keys accepted.
custom_fields	Custom Fields object	No	Collections typed custom fields. See Shared Schemas.

Status Codes¶

Status	Description
201	Account created.
409	Account already exists. Use PUT to replace or PATCH to update.
422	Validation failure.

Example Request¶

curl -X POST https://ext.arc-aegis.billtrust.com/api/v1/ingest/accounts/ACCT-001 \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "currency": "USD",
    "email": "billing@acme.com",
    "billing_address": {
      "address1": "123 Main St",
      "city": "Atlanta",
      "state": "GA",
      "zip": "30301",
      "country": "US"
    }
  }'

Example Response — 201¶

{
  "csrId": 12345,
  "accountNumber": "ACCT-001",
  "name": "Acme Corp",
  "currency": "USD",
  "email": "billing@acme.com",
  "billing_address": {
    "address1": "123 Main St",
    "city": "Atlanta",
    "state": "GA",
    "zip": "30301",
    "country": "US"
  },
  "createdAt": "2026-05-12T14:00:00.000Z",
  "updatedAt": "2026-05-12T14:00:00.000Z"
}

Example Response — 409¶

{
  "error": "account_already_exists",
  "account_number": "ACCT-001",
  "message": "Account 'ACCT-001' already exists. Use PUT to replace it or PATCH to update it."
}

PUT /accounts/{account_number}¶

Creates or replaces an account. Returns 201 on create and 200 on replace. Safe to retry.

Request Body¶

Same fields as POST.

Status Codes¶

Status	Description
201	Account created.
200	Account replaced.
422	Validation failure.

Example Request¶

curl -X PUT https://ext.arc-aegis.billtrust.com/api/v1/ingest/accounts/ACCT-001 \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "currency": "USD"
  }'

GET /accounts/{account_number}¶

Retrieves an account and its embedded notes.

Status Codes¶

Status	Description
200	Account found.
404	Account not found.

Example Request¶

curl https://ext.arc-aegis.billtrust.com/api/v1/ingest/accounts/ACCT-001 \
  -H "X-API-Key: <your-api-key>"

Example Response — 200¶

{
  "csrId": 12345,
  "accountNumber": "ACCT-001",
  "name": "Acme Corp",
  "currency": "USD",
  "createdAt": "2026-05-12T14:00:00.000Z",
  "updatedAt": "2026-05-12T14:00:00.000Z",
  "notes": [
    {
      "reference": "NOTE-001",
      "accountNumber": "ACCT-001",
      "body": "Customer on payment plan.",
      "effective_date": "2026-05-12T00:00:00.000Z",
      "createdAt": "2026-05-12T14:00:00.000Z"
    }
  ]
}

PATCH /accounts/{account_number}¶

Partially updates an account. Only fields present in the request body are modified.

Status Codes¶

Status	Description
200	Account updated. Returns the updated account.
404	Account not found.
422	Validation failure.

Example Request¶

curl -X PATCH https://ext.arc-aegis.billtrust.com/api/v1/ingest/accounts/ACCT-001 \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "credit_limit": 10000,
    "payment_terms": "NET60"
  }'

POST /accounts/{account_number}/notes¶

Creates an immutable note on an account. Notes cannot be updated or deleted (SOX requirement).

Request Body¶

Field	Type	Required	Description
reference	string	Yes	Caller-defined unique identifier for this note within the tenant.
body	string	Yes	Note content. Must not be empty.
subject	string	No	Note subject line.
note_type	string	No	Free-text classification (e.g. `credit`, `collections`).
effective_date	string	No	ISO 8601 datetime. Defaults to submission timestamp.

Status Codes¶

Status	Description
201	Note created.
404	Parent account not found.
409	A note with this reference already exists for this tenant.
422	Validation failure.

Example Request¶

curl -X POST https://ext.arc-aegis.billtrust.com/api/v1/ingest/accounts/ACCT-001/notes \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "NOTE-001",
    "body": "Customer agreed to payment plan.",
    "subject": "Payment arrangement confirmed",
    "note_type": "payment_arrangement",
    "effective_date": "2026-05-12T00:00:00Z"
  }'

Example Response — 201¶

{
  "reference": "NOTE-001",
  "account_number": "ACCT-001",
  "body": "Customer agreed to payment plan.",
  "subject": "Payment arrangement confirmed",
  "note_type": "payment_arrangement",
  "effective_date": "2026-05-12T00:00:00.000Z",
  "created_at": "2026-05-12T15:00:00.000Z"
}

GET /accounts/{account_number}/notes/{reference}¶

Retrieves a single note by its caller-defined reference.

Status Codes¶

Status	Description
200	Note found.
404	Account not found, or note reference not found on this account.

Example Request¶

curl https://ext.arc-aegis.billtrust.com/api/v1/ingest/accounts/ACCT-001/notes/NOTE-001 \
  -H "X-API-Key: <your-api-key>"