Native collection developer guide

🚧

In development

Native Tax Documentation Collection is in development. If you're interested in using it, reach out to your Taxbit contact.

Read the sections that apply to you, in any order.

Add the questionnaire

The questionnaire is one native screen. Add it where your users complete their tax form:

TaxbitQuestionnaire(
    questionnaire: "W-FORM",
    onComplete: { receipt in saveReceipt(receipt.document_id) },
    onExit: { dismiss() }
)

• onComplete runs once, when Taxbit has stored the finished form. Save the document_id.
• onExit adds a way out on the first screen, so the user can leave the questionnaire.

Choosing the form

For W-forms, use "W-FORM". You don't need to know ahead of time which form a person owes. Taxbit asks a few short questions first, such as whether they're a US person and whether they're an individual or a business, then takes them to the right form: W-9, W-8BEN, W-8BEN-E or W-8IMY.

Name a specific form only if every user needs the same one. Taxbit then skips the questions that form already answers.

W-9 and self-certification come first. W-8 forms and DPS are in development. See Development status.

Match your brand

Pass a theme to set colors and shapes. Anything you leave out uses the default.

let brandTheme = QuestionnaireTheme(
    accent: .brandOrange,            // primary button
    accentForeground: .black,        // text on the primary button
    selection: .black,               // selected option, checkboxes
    focus: .brandOrange,             // focused field outline
    fieldBackground: .gray.opacity(0.1),
    fieldCornerRadius: 16,
    buttonCornerRadius: 28,
    showsOptionIndicator: false      // option cards without radio circles
)

TaxbitQuestionnaire(questionnaire: "W-FORM", theme: brandTheme)

Choose how it pages

Pick how many questions appear on each screen:

TaxbitQuestionnaire(questionnaire: "W-FORM", layout: .step)

The questions and rules are the same in every layout. Only the paging changes.

Add your own screens

You can place your own screen in the flow, shown after a specific answer. For example, you might show an explainer, or ask a question of your own:

let explainer = Interstitial(
    afterField: "account_holder.us_account_type",
    whenValue: "LLC",
    content: { proceed, finish in
        AnyView(LLCExplainer(onContinue: proceed, onCancel: finish))
    }
)

TaxbitQuestionnaire(questionnaire: "W-9", interstitials: [explainer])

Your screen gets two actions: proceed continues the questionnaire, and finish leaves it. Taxbit never sees your screen or its answers.

Pre-fill what you know

If you already have some of the person's information, pass it in answers. The questionnaire opens with those fields filled in:

TaxbitQuestionnaire(
    questionnaire: "W-9",
    answers: [
        "account_holder.name": "Robert Smith",
        "account_holder.address.country": "US"
    ]
)

Pre-filled answers are checked just like typed ones.

Ask only some questions

Sometimes you only need part of a form. Two common cases:

• Review and sign. You already have the person's W-9 details. Show them read-only, and ask only for the signature.
• Residencies only. You only need tax residencies for a self-certification.

The prototype supports showing only some questions and hiding the ones you've pre-filled. The option names for this are still being finalized.

📘

Show what people sign

If a user is certifying a form, show them the information they're certifying, even if they can't change it.

Authentication

Every request to Taxbit needs a short-lived token for the user filling in the form. In production, your server creates that token, never your app. How your app passes the token to the questionnaire is being finalized.

❗️

Keep your secret on your server

Your Taxbit client secret never goes into your app. Your app only receives the short-lived token from your server.

Going further: fully custom screens

If the theme and layouts aren't enough, the design lets you draw the questions yourself using the same form data the questionnaire uses (see Under the hood). Taxbit still decides the questions, and you decide how they look. The web prototype supports replacing individual fields with your own components. Native support for this is planned.

Development status

Nothing is published yet. Every item below refers to the prototype or to planned work.

Interested?

If native collection sounds like a fit, reach out to your Taxbit contact. We'd love to hear which platforms, forms and customizations matter most to you.