Accounts

Every balance at Augustus is an account. A product is defined by the program the account sits in, who holds it, and how many addresses point at it. This page explains the four objects, how the three products are composed from them, and where the API stops short of the model today.

Account structure

Object	What it is	Resource `type`
Account program	The container for accounts. It sets what the accounts inside it can do and how their holders are onboarded, and it can hold accounts in more than one currency; an FBO program holds one. Augustus configures programs for you; there is no endpoint to create one.	`account_program`
Account holder	The business or individual that owns the funds in an account. A holder is onboarded onto a program and screened against that program’s policy. Your own business is registered as a holder when you open your relationship with Augustus.	`account_holder`
Account	A balance in the Augustus ledger, owned by one holder inside one program. Every account has its own balance and its own account ID.	`account`
Address	The identifier a sender uses to reach the account on a payment rail: IBAN, UK sort code and account number, ABA routing and account number, or a wallet address. Funds arriving at an address are booked to its account. An address has no balance of its own.	`financial_addresses[]` on the account

Account program

List the programs Augustus has configured for you. A program is active or frozen; closed programs are not returned.

curl "https://api.sandbox.augustus.com/v1/account_programs" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY"

import Augustus from '@augustusbank/typescript-sdk'

const client = new Augustus()
for await (const program of client.accountPrograms.list()) {
  // process account program
}

{
  "id": "a55d55bd-c8c4-44f4-b86f-a3af26ba7028",
  "type": "account_program",
  "label": "Customer USD program",
  "status": "active",
  "created_at": "2026-09-04T15:20:50.784Z",
  "updated_at": "2026-09-04T15:20:50.784Z"
}

Operation	Endpoint
List programs	GET `/v1/account_programs`
Retrieve program	GET `/v1/account_programs/{id}`
Retrieve program balance	GET `/v1/account_programs/{id}/balance`, the sum of the balances of the accounts in the program. FBO programs only

Account holder

Register a holder by passing the program ID, the holder type, and the identity data for that type. The data is screened against the program’s policy. On a positive decision the holder becomes active and the account_holder.active event fires. A holder is pending, active or closed.

natural_person
business

legal_name
residential_address
date_of_birth
identification, ssn or itin for US persons, id (generic government-issued ID) for non-US
country_of_citizenship

legal_business_name and doing_business_as
registered_address and physical_address
registration_number, ein or ssn
state_of_incorporation, year_of_incorporation, country_of_incorporation
beneficial_owners, at least one, each with the same fields as a natural person
control_person, the individual with primary responsibility for controlling, managing, or directing the business, with the same fields as a natural person plus their title (e.g. CEO, President)

curl -X POST "https://api.sandbox.augustus.com/v1/account_holders" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "account_program_id": "a55d55bd-c8c4-44f4-b86f-a3af26ba7028",
    "holder_type": "natural_person",
    "beneficiary_data": {
      "legal_name": "Jane Doe",
      "date_of_birth": "1990-04-12",
      "country_of_citizenship": "US",
      "identification": { "type": "ssn", "value": "123-45-6789" },
      "residential_address": {
        "line_1": "123 Market St",
        "line_2": null,
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country_code": "US"
      }
    }
  }'

import Augustus from '@augustusbank/typescript-sdk'

const client = new Augustus()
const holder = await client.accountHolders.create({
  account_program_id: 'a55d55bd-c8c4-44f4-b86f-a3af26ba7028',
  holder_type: 'natural_person',
  beneficiary_data: {
    legal_name: 'Jane Doe',
    date_of_birth: '1990-04-12',
    country_of_citizenship: 'US',
    identification: { type: 'ssn', value: '123-45-6789' },
    residential_address: {
      line_1: '123 Market St',
      line_2: null,
      city: 'San Francisco',
      state: 'CA',
      postal_code: '94105',
      country_code: 'US',
    },
  },
})

{
  "id": "6aa40a7ff035bf741bc7c96a",
  "type": "account_holder",
  "holder_type": "natural_person",
  "status": "pending",
  "beneficiary_data": {
    "legal_name": "Jane Doe",
    "residential_address": {
      "line_1": "123 Market St",
      "line_2": null,
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country_code": "US"
    },
    "date_of_birth": "1990-04-12",
    "identification": { "type": "ssn", "value": "123-45-6789" },
    "country_of_citizenship": "US"
  },
  "metadata": {},
  "created_at": "2026-09-11T14:04:47.503Z"
}

To onboard an existing holder onto another program, register them again against that program ID. This triggers a separate screening and may require additional information.

Operation	Endpoint
List holders	GET `/v1/account_holders`
Create holder	POST `/v1/account_holders`
Retrieve holder	GET `/v1/account_holders/{id}`
Update holder	POST `/v1/account_holders/{id}`

Account

Where the program allows it, you open an account by passing the program ID and the holder ID. The account opens in pending with one address allocated, and Augustus activates it once verification clears. Where the program does not allow self-service, Augustus opens the accounts for you.

curl -X POST "https://api.sandbox.augustus.com/v1/accounts" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "account_program_id": "a55d55bd-c8c4-44f4-b86f-a3af26ba7028",
    "account_holder_id": "6aa40a7ff035bf741bc7c96a"
  }'

import Augustus from '@augustusbank/typescript-sdk'

const client = new Augustus()
const account = await client.accounts.create({
  account_program_id: 'a55d55bd-c8c4-44f4-b86f-a3af26ba7028',
  account_holder_id: '6aa40a7ff035bf741bc7c96a',
})

{
  "id": "667eecf1-ef16-4d27-949b-5cf30ca51dc9",
  "type": "account",
  "currency": "USD",
  "status": "pending",
  "asset_type": "fiat",
  "label": "Jane Doe",
  "financial_addresses": [
    {
      "type": "aba",
      "routing_number": "021000021",
      "account_number": "91478035",
      "account_holder_name": "Jane Doe"
    }
  ],
  "created_at": "2026-09-08T10:12:22.406Z",
  "updated_at": "2026-09-08T10:12:22.406Z",
  "metadata": {}
}

Operation	Endpoint
List accounts	GET `/v1/accounts`, filter by `account_program_id` or `status`
Create account	POST `/v1/accounts`
Retrieve account	GET `/v1/accounts/{id}`
Retrieve balance	GET `/v1/accounts/{id}/balance`
Freeze account	POST `/v1/accounts/{id}/freeze`
Unfreeze account	POST `/v1/accounts/{id}/unfreeze`
Close account	POST `/v1/accounts/{id}/close`, requires a `reason` of `aml_risk_fraud` or `client_request`

Address

Every entry in financial_addresses carries a type and the fields a sender needs on that rail. account_holder_name is the name the address carries on the rail: yours on an operating account, your customer’s on an FBO account.

`type`	Fields	Rails
`aba`	`routing_number`, `account_number`, `account_holder_name`	ACH, Fedwire, SWIFT (USD)
`iban`	`iban`, `account_holder_name`, `bic`	SEPA
`sort_code`	`sort_code`, `account_number`, `account_holder_name`	Faster Payments
`crypto_wallet`	`address`, `blockchain`	Blockchain

An address is allocated when the account opens. Additional addresses are requested from Augustus based on the program’s policy and supported rails.

How the products are built

Operating, FBO and correspondent are product names. The API has one account type, account, and a product is defined by the program an account belongs to and how many addresses point at it. The example names below run through all three guides: Acme Inc is the Augustus customer, Acme Bank is that customer when it is a bank, and Jane Doe, John Roe and Globex LLC are its customers.

Three panels side by side. A, operating account: one account program containing one account for Acme Inc with one address. B, FBO accounts: one account program held for the benefit of Acme Inc's customers, containing separate accounts for Jane Doe, John Roe and Globex LLC, each with its own address. C, correspondent account: one account program containing a single Acme Bank account carrying three addresses, one per bank customer. — How the three products are composed from the four objects

	Operating account (DDA)	FBO account	Correspondent account
Program	Configured by Augustus, in your name	Configured by Augustus, titled for the benefit of your customers	Configured by Augustus, in your name
Holder	You	One per customer, registered by you	You
Accounts	One or more, opened by Augustus	One or more per customer, opened by you	One, opened by Augustus
Addresses per account	One, in your name	One, in the customer’s name	Many, each in a customer’s name
Program balance	No total	Readable total across the program	No total

Operating accounts (DDA)

Accounts in your own name for operations and treasury.

FBO accounts

Accounts you open for your customers, each with its own balance and account number.

Correspondent accounts

One account with many addresses, for banks paying and collecting in their customers’ names.

Account status

Status	Behaviour
`pending`	Newly opened, not yet activated. Augustus typically activates within minutes. Some accounts require additional information (e.g. enhanced due diligence) before activation.
`active`	Ready to hold, send and receive funds. Balance and transaction reporting available.
`frozen`	Can hold funds. Cannot send or receive. Reversible: call POST `/v1/accounts/{id}/unfreeze` to return to `active`.
`closed`	Cannot hold, send or receive funds. Terminal: the account must be `frozen` first, and cannot be reopened. The account record itself remains retrievable.

The optional status filter on GET /v1/accounts accepts pending, active, and frozen only. You cannot filter for closed accounts; they are still returned by an unfiltered list, and closed is a valid value on the account resource.

What the API does not show yet

The structure above is how accounts are organised. The API exposes it only in part today:

Program and holder are write-only on the account. account_program_id and account_holder_id are supplied on create and are not returned on the account resource. To find the accounts in a program, filter GET /v1/accounts by account_program_id. To find one customer’s account, store the account ID against your customer record when you create it.
One address per account. financial_addresses is an array and holds one entry. Additional addresses cannot be requested through the API yet.
Programs are read-only. Augustus creates and configures them. In the sandbox, POST /v1/simulations/account_programs creates one so you can test the FBO flow end to end.
No address endpoints. Addresses exist only as the financial_addresses field on the account.
Program balance for FBO programs only. Other programs hold their accounts side by side without a total, and the program balance endpoint returns an error for them. Read the balance of each account instead.
Two balance shapes. The account balance resource keys on account_id; the program balance resource keys on id.

Basics

Transactions

Payments

Conversions

Loans

Accounts

Account structure

How the products are built

Operating accounts (DDA)

FBO accounts

Correspondent accounts

Account status

What the API does not show yet

​Account structure

​How the products are built

Operating accounts (DDA)

FBO accounts

Correspondent accounts

​Account status

​What the API does not show yet

Account structure

How the products are built

Account status

What the API does not show yet