Set up your filer

Your filer is your platform's own filing entity, the party that submits returns to tax authorities. The filer record holds its legal name, address, EIN or TIN, a contact person, settings for the regimes it files under (for example the Form 1099-K filer type, the Form 1042-S statuses, or the DAC7 receiving member state), and the default disposition method for the accounts under it. Set one up per filing entity. A tenant can hold several filers, and one carries is_default: true.

Do this before you create account owners and accounts. Until the tenant has a default filer, POST /v1/account-owners returns a 400 with this body:

{"message": "No default filer is configured for this organization.", "error": "Bad Request"}

POST /v1/accounts fails as well. Create the filer first, marked as the default (see below), then retry.

By the end of this page you have a filer in your tenant, marked as the default, and its UUID for the accounts that report under it.

Before you begin

• A bearer token. See Authenticate your tenant.
• The filer's legal name and address, plus its EIN for US filing or its TIN and tax country elsewhere.
• A contact person for the filer.
• The regime settings your implementation manager confirmed at kickoff, if the filer files 1099-K, 1042-S, or DAC7 returns.

You can also create filers in the Taxbit Dashboard. The API creates the same record.

Create the filer

Only name is required. Send the rest now, so the forms Taxbit files later carry the right filer details. Set disposition_method to the cost basis method accounts under this filer should use unless they set their own; Setting disposition methods explains the choice.

curl -X POST $BASE_URL/v1/filers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Northwind Exchange, Inc.",
    "ein": "82-1234567",
    "tax_country_code": "US",
    "address": {
      "first_line": "400 Pike Street",
      "city": "Seattle",
      "state_or_province": "WA",
      "postal_code": "98101",
      "country": "US"
    },
    "contact_name": "Priya Raman",
    "contact_title": "Head of Tax",
    "contact_email": "[email protected]",
    "disposition_method": "HIFO",
    "is_default": true
  }'

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "date_created": "2026-03-02T15:04:11.000Z",
    "date_modified": "2026-03-02T15:04:11.000Z",
    "name": "Northwind Exchange, Inc.",
    "ein": "821234567",
    "tax_country_code": "US",
    "address": {
      "first_line": "400 Pike Street",
      "city": "Seattle",
      "state_or_province": "WA",
      "postal_code": "98101",
      "country": "US"
    },
    "contact_name": "Priya Raman",
    "contact_title": "Head of Tax",
    "contact_email": "[email protected]",
    "disposition_method": "HIFO",
    "is_default": true
  }
}

The id in the response is the filer's UUID. The EIN comes back as nine digits: dashes are accepted on input and stripped on storage. When your tenant has more than one filer, pass it as filer_id when you create accounts, so each account reports under the right entity. Some parts of the product call a filer a payer; payer_id and filer_id mean the same thing.

Mark the default

One filer per tenant carries is_default: true. Set it when you create the filer, as above, and set disposition_method then too: PATCH /v1/filers/{id} updates the filer's details but accepts neither field. Create the default filer first if you have several, so the tenant is never without one.

List your filers

Confirm what the tenant holds before you move on. The list carries each filer's UUID and settings.

curl $BASE_URL/v1/filers \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "date_created": "2026-03-02T15:04:11.000Z",
      "date_modified": "2026-03-02T15:04:11.000Z",
      "name": "Northwind Exchange, Inc.",
      "ein": "821234567",
      "tax_country_code": "US",
      "address": {
        "first_line": "400 Pike Street",
        "city": "Seattle",
        "state_or_province": "WA",
        "postal_code": "98101",
        "country": "US"
      },
      "contact_name": "Priya Raman",
      "contact_title": "Head of Tax",
      "contact_email": "[email protected]",
      "disposition_method": "HIFO",
      "is_default": true
    }
  ]
}

If the request fails

• 400. A field failed validation. An EIN must be XX-XXXXXXX, XXX-XX-XXXX, or nine digits, and a TIN or VAT ID is validated together with its country code; the message names the field.
• 401. The bearer token is missing, invalid, or expired. Mint a new one and retry.

Parameters

Only the fields used above. The full schema, including the 1099-K, 1042-S, DAC7, CESOP, and Canadian MRDP settings, is in the API Reference.

Where to go next

Create account owners and accounts: a record for each user whose tax data you collect, and an account for their activity.