FAQ

Short answers to the questions integrators ask most often. Each answer links the page that covers it in full.

Getting set up

Why does POST /v1/account-owners fail with "No default filer is configured for this organization."?

Account owners and accounts can't be created until your organization has a filer marked as the default. Create the filer first, with is_default set to true. See Set up your filer.

What is the difference between an account owner and an account?

An account owner is the person or entity whose tax data you collect. An account is a container of that owner's activity: transactions attach to accounts, and tax documentation attaches to account owners. See Create account owners and accounts.

How long does a token last, and does the SDK need its own?

A tenant-scoped token lasts 24 hours; cache it and request a new one before it expires. The API calls an organization a tenant; tenant_id is your Organization ID. The React SDK uses a separate account owner token that lasts one hour, which your backend requests for the account owner, so your credentials never reach the browser. See Authenticate.

Why won't the SDK questionnaire load for an account owner?

The most common cause is that the account owner doesn't exist yet when the SDK loads. Create the account owner from your backend during signup, not when the account owner opens the form. See Get started. For other SDK questions, see the Tax documentation FAQ and the Tax documentation issues and warnings.

Sending and updating data

How do I update or correct data I have already sent?

It depends on what you're updating:

• Transactions. Resend the whole transaction with the same id. What you send replaces what is stored, fees included, so send the complete transaction. datetime is when the transaction occurred, not when you sent it. See Send payment transactions.
• Account owners, accounts, and filers. PATCH changes only the fields you send; fields you leave out keep their values. Send null to clear a field the reference marks as nullable. See Send recipient tax data for account owners, and the Accounts reference and Filers reference for the rest.
• Form data, sent as form items. PUT by your ID, or the batch endpoint, replaces the whole record, so send it complete. See the Form Items reference.

Should I send transactions or form items?

Send transactions if you want Taxbit to compute cost basis, gains, and form amounts; it's the only path for the Cost Basis features. Send form data if your platform already computes the amounts and needs Taxbit for filing and delivery. The choice is made once, in your kickoff. See Choose your data path.

Can I send the same transaction twice at once?

No. Send one request per transaction id at a time: two in flight together can fail with a 400 uniqueness error. Sent one after the other, the second updates the first. See Send payment transactions.

A create timed out or returned 409. Did it succeed?

Maybe. A create you retry after it already succeeded comes back 409, and the API has no idempotency keys. After a timeout or a 409, read the record back by your ID and check it's the one you meant to create. See Errors and rate limits.

How do I load historical data in bulk?

The Ingest page in the Taxbit Dashboard takes CSV and JSONL files, for historical loads instead of API calls, and offers each CSV template. Taxbit Support can walk you through it. See Choose your data path.

Does submitting a W-9 or W-8 overwrite the account owner's name and TIN?

No. A W-9 or W-8 submission is stored as separate tax documentation and doesn't change the account owner. When Taxbit builds the recipient's forms, the name and TIN come from a valid W-9 or W-8, and the address from whichever source has a valid address, or the newer source otherwise. See Send recipient tax data.

Forms and delivery

How do I know when a recipient's form is generated or filed?

Each entry from the tax documents endpoint, GET /v1/accounts/{id}/tax-documents, has is_filed, which says whether the form has been filed. To hear about it instead of polling, subscribe to the FORM_STATUS_UPDATE webhook, which is sent when a form is generated, filed, or deleted. See Retrieve US tax forms.

How long does a form download URL last?

Ten minutes by default. Pass url_expiration_time in seconds to extend it, up to one hour. Because every URL expires, request the list when the recipient opens their forms, rather than storing URLs. See Retrieve US tax forms.

How do I find a corrected or earlier version of a form?

A corrected or voided form is a new revision, with a revision_type of CORRECTION or VOID. The tax documents endpoint, GET /v1/accounts/{id}/tax-documents, returns only the latest revision unless you pass include_historical=true. See Retrieve US tax forms.

Can a filed form be deleted?

No. A form that has been filed can't be deleted; a change after filing goes through a correction instead. See Webhooks and Go live.

Cost basis and gains

Why don't gains reflect a recent transaction?

Taxbit calculates inventory and gains in the background, so a read right after a write can show the account as it was before; see how long the lag is. The INVENTORY_UPDATE webhook is the better signal that figures have changed.

How do I change an account's disposition method?

To change the cost-basis method (disposition_method), add an entry to the account's cost-basis method history with an effective_datetime. PATCH /v1/accounts/{id} ignores disposition_method. See Choose a cost-basis method.

Sandbox and production

Do sandbox and production use different hosts or credentials?

The same host, different credentials. Each organization has its own client_id, client_secret, and data; when one set of credentials covers more than one organization, tenant_id in the token request picks the organization. See Test in your sandbox.

How do I test without filing anything?

Use your sandbox organization. Nothing is filed with a tax authority from a sandbox organization, no paper copies are mailed, and TIN matching is simulated. See Test in your sandbox.

How do I delete test data?

Work with your implementation manager on the best approach to deleting account data, or to getting a new sandbox organization if you need one. See Test in your sandbox.

Webhooks and errors

Webhook events stopped arriving.

Most often the subscription has been deauthorized: your endpoint, or something in front of it, returned an authentication-class response; the Webhooks page lists the status codes. A deauthorized subscription doesn't recover on its own; contact Taxbit Support with the time you last received an event. See Webhooks.

Are there rate limits?

Yes. Over the limit you get a 429; wait for Retry-After, then retry. The Errors and rate limits page has the limits, how they apply, and the 429 bodies.

Where to go next

• Get started: the integration from the first call.
• Go live: the checks before your first production filing.

Questions? Contact Taxbit Support or [email protected].