Create account owners and accounts

An account owner is the person or entity whose tax data you collect: your end user. An account is a container of that account owner's activity: transactions attach to accounts, and tax documentation attaches to account owners. Create both from your backend as account owners onboard, before an account owner opens anything Taxbit renders.

Before you begin

• A bearer token. See Authenticate.
• A default filer in your organization. Filers are usually set up in the Taxbit Dashboard under Settings > Filer Setup (Filer Setup in the Help Center covers the fields each regime needs); to automate it, POST /v1/filers creates the same record. Mark one filer is_default: true when you create it, and set its cost-basis method (disposition_method) then if you use cost basis: PATCH /v1/filers/{id} accepts neither field later. Without a default filer, POST /v1/account-owners returns a 400 with {"message": "No default filer is configured for this organization.", "error": "Bad Request"}, and POST /v1/accounts fails as well.
• Your own identifiers for the account owner and the account. Taxbit stores yours and returns its own taxbit_id alongside.

1. Create an account owner, with its account

Send your identifier, the account owner type (INDIVIDUAL, ENTITY, or INTERMEDIARY), and the account. Nothing else is required to start; the names, TINs, and addresses used to file are collected later, through the Tax Documentation React SDK or Send recipient tax data. The account's id may equal the account owner's id when each account owner has exactly one account.

curl -X POST $BASE_URL/v1/account-owners \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "usr_8a3b1c9d",
    "account_owner_type": "INDIVIDUAL",
    "name": "Dana Whitfield",
    "email": "[email protected]",
    "account": {
      "id": "acct_5f2e7d10",
      "establishment_date": "2026-03-02"
    }
  }'

The response is the account owner. To read the account back, call GET /v1/accounts/{id} with the account's id.

This endpoint accepts 50 requests per second by default and returns 429 above that. If your onboarding volume needs more, ask your implementation manager.

2. Add more accounts

When an account owner holds more than one account, create the others with POST /v1/accounts, sending your identifier for the account and the account_owner_id you used above. The account owner must already exist. If your organization has more than one filer, pass filer_id to say which one this account reports under; with a single filer, accounts attach to it. The API's payer_id is the same as filer_id.

curl -X POST $BASE_URL/v1/accounts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "acct_9c41b2e8",
    "account_owner_id": "usr_8a3b1c9d",
    "establishment_date": "2026-03-02"
  }'

{
  "data": {
    "id": "acct_9c41b2e8",
    "taxbit_id": "0177df49-c1aa-4d0b-bbeb-67a0c1b33a94",
    "account_owner_id": "usr_8a3b1c9d",
    "date_created": "2026-03-02",
    "date_modified": "2026-03-02",
    "establishment_date": "2026-03-02",
    "prefers_physical_mail": false
  }
}

An account inherits its filer's default cost-basis method (disposition_method). To override it for this account, pass disposition_method (HIFO, FIFO, LIFO, LOFO, or AUSTRIA) when you create it. Changing it later works through the cost-basis method history, not through PATCH; see Choose a cost-basis method.

Country fields

Country fields on account owners and accounts, including address, mailing address, tax residency, and country of birth, take an ISO 3166-1 alpha-2 code such as US or DE, not a country name. These fields are not validated on these endpoints: a full name such as Germany returns a success response and is stored as sent, so send the code.

How owners and accounts relate

• One owner, one account. Common where an account owner can hold only one account, such as a marketplace or a payments platform.
• One owner, many accounts. Common where an account owner holds several account types, such as an individual with more than one IRA.
• Joint holders. An account can carry secondary account owners in secondary_account_owner_ids; see the Create account reference.

Account Owner & Accounts Overview in the Help Center has worked examples of each shape.

In every shape, the account owner comes first, and every account links to one account owner (account_owner_id) and one filer.

Parameters

Only the fields used above. Full schemas: Create account owner and Create account.

Account owner

Account

Where to go next

Transactions or form data: send transactions for Taxbit to compute from, or form data you compute yourself.