--- updatedAt: 2026-08-03T16:15:16.000Z agentTools: projectIndex: https://apidocs.taxbit.com/llms.txt --- # Create an Account Create accounts associated with an account owner in Taxbit's system. Accounts enable sending transactions, accessing inventory details, and retrieving tax-related documents associated with these accounts. # OpenAPI definition ```json { "openapi": "3.0.0", "paths": { "/v1/accounts": { "post": { "description": "Create accounts associated with an account owner in Taxbit's system. Accounts enable sending transactions, accessing inventory details, and retrieving tax-related documents associated with these accounts.", "operationId": "AccountsController_createAccount", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountDto" }, "examples": { "default": { "summary": "Example", "value": { "id": "37480283", "account_owner_id": "JohnDoe864", "establishment_date": "2020-02-21", "closest_intermediary_account_id": "sample-intermediary-account-id", "mailing_address": { "first_line": "123 Pine St", "second_line": "Apt 456", "city": "Seattle", "state_or_province": "WA", "postal_code": "98000", "country": "US" }, "prefers_physical_mail": false } } } } } }, "responses": { "201": { "description": "Account Successfully Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponseDto" }, "examples": { "default": { "summary": "Example", "value": { "data": { "id": "37480283", "taxbit_id": "0177df49-c1aa-4d0b-bbeb-67a0c1b33a94", "tenant_id": "8d0bd177-dd48-4bea-b89e-c4ce038375e7", "account_owner_id": "JohnDoe864", "date_created": "2023-08-19", "date_modified": "2023-10-19", "establishment_date": "2020-08-19", "closest_intermediary_account_id": "sample-intermediary-account-id", "mailing_address": { "first_line": "123 Pine St", "second_line": "Apt 456", "city": "Seattle", "state_or_province": "WA", "postal_code": "98000", "country": "US" }, "prefers_physical_mail": false } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponseDto" }, "examples": { "default": { "summary": "Example", "value": { "error": "Bad Request", "message": "Invalid request" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponseDto" }, "examples": { "default": { "summary": "Example", "value": { "Message": "User is not authorized to access this resource with an explicit deny" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundErrorResponseDto" }, "examples": { "default": { "summary": "Example", "value": { "error": "Not Found", "message": "Object with id cannot be found" } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictErrorResponseDto" }, "examples": { "default": { "summary": "Example", "value": { "error": "Conflict", "message": "Object with id already exists" } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsErrorResponseDto" }, "examples": { "default": { "summary": "Example", "value": { "error": "rate_limit_exceeded", "message": "Rate limit exceeded. Please retry after 30 seconds." } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Create an Account", "tags": [ "Accounts" ] } } }, "info": { "title": "API", "description": "", "version": "1.2.0", "contact": {} }, "servers": [ { "url": "https://api.multi1.enterprise.taxbit.com" }, { "url": "https://api.eutax1.enterprise.taxbit.com" } ], "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http" } }, "schemas": { "BadRequestErrorResponseDto": { "type": "object", "properties": { "error": { "description": "Error message describing the validation failure", "type": "string", "example": "Bad Request" }, "message": { "description": "Details of why the request was rejected", "type": "string", "example": "Invalid request" }, "issues": { "description": "Per-field validation failures, present when the request body failed schema validation.", "type": "array", "items": {} } }, "required": [ "error", "message" ], "additionalProperties": false }, "ForbiddenErrorResponseDto": { "type": "object", "properties": { "Message": { "description": "Explicit-deny message returned when the caller is not authorized for the resource.", "type": "string", "example": "User is not authorized to access this resource with an explicit deny" } }, "required": [ "Message" ], "additionalProperties": false }, "ConflictErrorResponseDto": { "type": "object", "properties": { "error": { "description": "Error message indicating the object already exists", "type": "string", "example": "Conflict" }, "message": { "description": "Which object is already present", "type": "string", "example": "Object with id already exists" } }, "required": [ "error", "message" ], "additionalProperties": false }, "TooManyRequestsErrorResponseDto": { "type": "object", "properties": { "error": { "description": "Error code emitted when the caller exceeds its rate limit", "type": "string", "example": "rate_limit_exceeded" }, "message": { "description": "How long to wait before retrying", "type": "string", "example": "Rate limit exceeded. Please retry after 30 seconds." } }, "required": [ "error", "message" ], "additionalProperties": false }, "NotFoundErrorResponseDto": { "type": "object", "properties": { "error": { "description": "Error message indicating the object was not found", "type": "string", "example": "Not Found" }, "message": { "description": "Which object could not be found", "type": "string", "example": "Object with id cannot be found" } }, "required": [ "error", "message" ], "additionalProperties": false }, "CreateAccountDto": { "type": "object", "properties": { "id": { "type": "string", "title": "AccountId", "description": "Your system's unique identifier for the Account.", "example": "37480283" }, "alternate_id": { "type": "string", "title": "AlternateAccountId", "description": "A secondary identifier for the Account in your system, for callers that key the same account by more than one id. Returned alongside `id` when it is set.", "example": "alt-37480283" }, "account_owner_id": { "type": "string", "title": "AccountOwnerId", "description": "Your system's unique identifier for the Account Owner.", "example": "JohnDoe864" }, "payer_id": { "title": "PayerId", "description": "The Payer/Filer UUID. This is a version 4 UUID.", "format": "uuid", "deprecated": true, "type": "string", "example": "11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000" }, "filer_id": { "title": "FilerId", "description": "The Payer/Filer UUID. This is a version 4 UUID.", "format": "uuid", "type": "string", "example": "11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000" }, "account_type": { "type": "string", "enum": [ "US_IRA_TRADITIONAL", "US_IRA_ROTH", "US_IRA_SIMPLE", "US_IRA_SEP", "US_EMPLOYER_PLAN", "US_ANNUITY_INSURANCE", "US_TRUMP_ACCOUNT", "DEPOSITORY", "DEPOSITORY_SEMP_ONLY", "CUSTODIAL", "CASH_VALUE_INSURANCE_CONTRACT", "ANNUITY_CONTRACT", "INVESTMENT_ENTITY_ACCOUNT" ], "title": "AccountType", "description": "Account type for the user." }, "establishment_date": { "type": "string", "format": "date", "description": "ISO-8601 date when the account was established.", "example": "2022-08-19" }, "closure_date": { "type": "string", "format": "date", "description": "ISO-8601 date when the account was closed. A closed account stops accruing age for reporting purposes and is excluded from action-needed reports.", "example": "2022-08-19" }, "year_end_fair_market_value": { "type": "array", "items": { "type": "object", "properties": { "year_end": { "type": "integer", "description": "Four digit year of the last tax year as of 12/31.", "minimum": 1000, "maximum": 9999, "example": 2023 }, "fair_market_value": { "type": "string", "description": "The total value of assets within the account at year-end, expressed in the currency given by `currency`.", "example": "500" }, "currency": { "type": "string", "enum": [ "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BOV", "BRL", "BSD", "BTN", "BWP", "BYN", "BYR", "BZD", "CAD", "CDF", "CHE", "CHF", "CHW", "CLF", "CLP", "CNY", "COP", "COU", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LTL", "LVL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRO", "MRU", "MUR", "MVR", "MWK", "MXN", "MXV", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SOS", "SRD", "SSP", "STD", "STN", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "USN", "USS", "UYI", "UYU", "UYW", "UZS", "VEF", "VES", "VND", "VUV", "WST", "XAF", "XAG", "XAU", "XBA", "XBB", "XBC", "XBD", "XCD", "XDR", "XFU", "XOF", "XPD", "XPF", "XPT", "XSU", "XUA", "XXX", "YER", "ZAR", "ZMW", "ZWL" ], "title": "CurrencyCode", "description": "The ISO 4217 currency code the fair market value is expressed in. Defaults to `USD` when omitted.", "example": "USD" } }, "required": [ "year_end", "fair_market_value" ], "title": "YearEndFairMarketValue", "additionalProperties": false } }, "disposition_method": { "type": "string", "enum": [ "HIFO", "FIFO", "LIFO", "LOFO", "AUSTRIA" ], "title": "DispositionMethod", "description": "The disposition method for the account. Overrides the Filer default. Supported disposition methods are HIFO, FIFO, LIFO, LOFO, and AUSTRIA.", "example": "FIFO" }, "secondary_account_owner_ids": { "type": "array", "items": { "type": "string", "title": "AccountOwnerId", "description": "Your system's unique identifier for the Account Owner.", "example": "JohnDoe864" }, "description": "A list of additional (secondary) account owner IDs associated with the account." }, "closest_intermediary_account_id": { "type": "string", "description": "The account Id of the immediate upstream intermediary, the account directly above the current one in the intermediary hierarchy. This is the closest intermediary with respect to the account's position in the chain.", "example": "sample-intermediary-account-id" }, "mailing_address": { "type": "object", "properties": { "first_line": { "description": "First line of the Account's mailing address.", "type": "string", "example": "123 Pine St" }, "second_line": { "description": "Second line of the Account's mailing address.", "type": "string", "example": "Apt 456" }, "city": { "description": "City of the Account's mailing address.", "type": "string", "example": "Seattle" }, "state_or_province": { "description": "State or province of the Account's mailing address.", "type": "string", "example": "WA" }, "postal_code": { "description": "Postal code of the Account's mailing address.", "type": "string", "example": "98000" }, "country": { "description": "Country of the Account's mailing address.", "type": "string", "example": "US" } }, "additionalProperties": false, "title": "address", "description": "The Account's mailing address. When present and valid, it takes precedence over the Account Owner's mailing address in tax reporting profiles.", "example": { "first_line": "123 Pine St", "second_line": "Apt 456", "city": "Seattle", "state_or_province": "WA", "postal_code": "98000" } }, "prefers_physical_mail": { "type": "boolean", "description": "Whether the Account's tax forms are sent through physical mail instead of electronically. When set it takes precedence over the Account Owner's preference.", "example": false } }, "required": [ "id", "account_owner_id" ], "title": "Create Account Request", "additionalProperties": false }, "AccountResponseDto": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "title": "AccountId", "description": "Your system's unique identifier for the Account.", "example": "37480283" }, "alternate_id": { "type": "string", "title": "AlternateAccountId", "description": "A secondary identifier for the Account in your system, for callers that key the same account by more than one id. Returned alongside `id` when it is set.", "example": "alt-37480283" }, "taxbit_id": { "title": "TaxbitId", "description": "The Taxbit ID for this object. This is a version 4 UUID.", "format": "uuid", "type": "string", "example": "0177df49-c1aa-4d0b-bbeb-67a0c1b33a94" }, "tenant_id": { "title": "TenantId", "description": "Tenant ID for your organization.", "format": "uuid", "type": "string", "example": "0177df49-c1aa-4d0b-bbeb-67a0c1b33a94" }, "date_created": { "description": "The date when the account was created in Taxbit's system.", "format": "date", "type": "string", "example": "2023-08-19" }, "date_modified": { "description": "The date when the account was last modified in Taxbit's system.", "format": "date", "type": "string", "example": "2023-10-19" }, "account_owner_id": { "type": "string", "title": "AccountOwnerId", "description": "Your system's unique identifier for the Account Owner.", "example": "JohnDoe864" }, "filer_id": { "title": "FilerId", "description": "The Payer/Filer UUID. This is a version 4 UUID.", "format": "uuid", "type": "string", "example": "11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000" }, "payer_id": { "title": "PayerId", "description": "The Payer/Filer UUID. This is a version 4 UUID.", "format": "uuid", "deprecated": true, "type": "string", "example": "11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000" }, "account_type": { "type": "string", "enum": [ "US_IRA_TRADITIONAL", "US_IRA_ROTH", "US_IRA_SIMPLE", "US_IRA_SEP", "US_EMPLOYER_PLAN", "US_ANNUITY_INSURANCE", "US_TRUMP_ACCOUNT", "DEPOSITORY", "DEPOSITORY_SEMP_ONLY", "CUSTODIAL", "CASH_VALUE_INSURANCE_CONTRACT", "ANNUITY_CONTRACT", "INVESTMENT_ENTITY_ACCOUNT" ], "title": "AccountType", "description": "Account type for the user." }, "establishment_date": { "description": "ISO-8601 date when the account was established.", "format": "date", "type": "string", "example": "2022-08-19" }, "closure_date": { "description": "ISO-8601 date when the account was closed. A closed account stops accruing age for reporting purposes and is excluded from action-needed reports.", "format": "date", "type": "string", "example": "2024-06-30" }, "year_end_fair_market_value": { "type": "array", "items": { "type": "object", "properties": { "year_end": { "type": "integer", "description": "Four digit year of the last tax year as of 12/31.", "minimum": 1000, "maximum": 9999, "example": 2023 }, "fair_market_value": { "type": "string", "description": "The total value of assets within the account at year-end, expressed in the currency given by `currency`.", "example": "500" }, "currency": { "type": "string", "enum": [ "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BOV", "BRL", "BSD", "BTN", "BWP", "BYN", "BYR", "BZD", "CAD", "CDF", "CHE", "CHF", "CHW", "CLF", "CLP", "CNY", "COP", "COU", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LTL", "LVL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRO", "MRU", "MUR", "MVR", "MWK", "MXN", "MXV", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SOS", "SRD", "SSP", "STD", "STN", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "USN", "USS", "UYI", "UYU", "UYW", "UZS", "VEF", "VES", "VND", "VUV", "WST", "XAF", "XAG", "XAU", "XBA", "XBB", "XBC", "XBD", "XCD", "XDR", "XFU", "XOF", "XPD", "XPF", "XPT", "XSU", "XUA", "XXX", "YER", "ZAR", "ZMW", "ZWL" ], "title": "CurrencyCode", "description": "The ISO 4217 currency code the fair market value is expressed in. Defaults to `USD` when omitted.", "example": "USD" } }, "required": [ "year_end", "fair_market_value" ], "title": "YearEndFairMarketValue", "additionalProperties": false } }, "disposition_method": { "type": "string", "enum": [ "HIFO", "FIFO", "LIFO", "LOFO", "AUSTRIA" ], "title": "DispositionMethod", "description": "The disposition method for the account. Overrides the Filer default. Supported disposition methods are HIFO, FIFO, LIFO, LOFO, and AUSTRIA.", "example": "FIFO" }, "secondary_account_owner_ids": { "type": "array", "items": { "type": "string", "title": "AccountOwnerId", "description": "Your system's unique identifier for the Account Owner.", "example": "JohnDoe864" }, "description": "A list of additional (secondary) account owner IDs associated with the account." }, "closest_intermediary_account_id": { "type": "string", "description": "The account Id of the immediate upstream intermediary, the account directly above the current one in the intermediary hierarchy. This is the closest intermediary with respect to the account's position in the chain.", "example": "sample-intermediary-account-id" }, "mailing_address": { "type": "object", "properties": { "first_line": { "description": "First line of the Account's mailing address.", "type": "string", "example": "123 Pine St" }, "second_line": { "description": "Second line of the Account's mailing address.", "type": "string", "example": "Apt 456" }, "city": { "description": "City of the Account's mailing address.", "type": "string", "example": "Seattle" }, "state_or_province": { "description": "State or province of the Account's mailing address.", "type": "string", "example": "WA" }, "postal_code": { "description": "Postal code of the Account's mailing address.", "type": "string", "example": "98000" }, "country": { "description": "Country of the Account's mailing address.", "type": "string", "example": "US" } }, "additionalProperties": false, "title": "address", "description": "The Account's mailing address. When present and valid, it takes precedence over the Account Owner's mailing address in tax reporting profiles.", "example": { "first_line": "123 Pine St", "second_line": "Apt 456", "city": "Seattle", "state_or_province": "WA", "postal_code": "98000" } }, "prefers_physical_mail": { "type": "boolean", "description": "Whether the Account's tax forms are sent through physical mail instead of electronically. When set it takes precedence over the Account Owner's preference.", "example": false } }, "required": [ "id", "taxbit_id", "tenant_id", "date_created", "date_modified", "account_owner_id" ], "additionalProperties": false, "title": "Account" } }, "required": [ "data" ], "title": "Account Response", "additionalProperties": false } } }, "security": [ { "bearer": [] } ] } ``` # Sibling pages * [Update an Account](https://apidocs.taxbit.com/reference/patch_accounts-id.md) * [Get an existing Account](https://apidocs.taxbit.com/reference/get_accounts-id.md)