> ## Documentation Index
> Fetch the complete documentation index at: https://www.finta.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboarding

> Set up a new company in Finta from your AI assistant

After [connecting Finta](https://www.finta.com/docs/mcp/introduction.md#connect), your assistant can set up a new company: answer the onboarding questions, submit them, connect banks and cards, and follow the first import.

Call `get_onboarding` when setting up Finta or after another tool returns `onboarding_incomplete`. Do not poll it or call it once setup is complete. Re-check only after the user reports an action, asks about status or comes back later. It returns `status`, saved answers, remaining questions, the eligibility decision, selected integrations, sync progress, and `next_step`. Do not read it again immediately after `update_onboarding`, which returns the full object. Tool descriptions stay brief; `next_step.message` carries the workflow and names the tools to use.

* Save answers with `update_onboarding` as the user gives them. Saves are drafts and can be changed until Finta decides, so there is no need to confirm before saving. Banks and cards return `options: []`, so gather those from context or plain text and map to the accepted input values.
* Submitting is final. Before sending `submit: true`, show the user their answers and submit once they confirm.
* `update_onboarding` accepts `null` for every answer field, including enum answers, so clients can replay `get_onboarding` answers or clear optional answers, for example `{"answers":{"incorporation_year":null}}` while that follow-up is editable. Omitted answers keep their saved values. Clearing required answers is rejected, and answer locks still apply. The `answers` object, array items, `submit`, and `notify_when_synced` remain non-nullable.
* Bank/card input enums include canonical provider slugs such as `boa` and `american_express`, so schema-enforcing clients can replay answers after recognized "other" names are folded. New answers may use those slugs directly. Saved `no_bank_yet` and `no_credit_cards_yet` values are allowed only as unchanged echoes; new selections are rejected. See the [accepted values](https://www.finta.com/docs/api-reference/onboarding.md#answers).
* Answers saved on the web can be [replayed unchanged](https://www.finta.com/docs/api-reference/onboarding.md#replay-answers-saved-on-the-web), including saved no-bank/no-card choices. An unchanged echo preserves web ranges, legacy states and additional industries; real changes still obey validation and answer locks.
* Only connect banks after approval, when the returned step is `connect_banks`. Follow its message: use `connect_integration` for new OAuth and Plaid connections, including Chase and SVB. The user approves on the returned provider or Plaid Hosted Link page; then check `get_integration_connection`. The last selected bank completing either flow starts the import automatically. For a Plaid reconnect, follow the web get-started page instructions in `next_step.message`, then call `update_onboarding` with `{"answers":{}}` to continue setup. This applies before and during the first import: Hosted Link cannot reconnect an existing bank and returns `409 integration_already_connected`. OAuth reconnects still use `connect_integration`.
* At `start_import`, every selected bank is connected but importing has not started. Call `update_onboarding` with `{"answers":{}}`, then follow the returned step. Reading onboarding alone does not start an import.
* At `wait_for_sync`, explain that Finta is importing transactions and setting up the books, and that it can take a while; never call this "sync" or "syncing" in the conversation. Offer the ready email once if not already discussed; set `notify_when_synced` to the user's choice. Honor a volunteered preference at any time.
* If you created the user's Finta account, tell them once at `wait_for_sync` to open the environment's login URL in `next_step.message`, choose **Forgot password**, and set a password for later browser access.
* Do not wait or poll during the import; the ready email lets the user know when the books are ready. Call `get_onboarding` again only if they ask or come back. `sync.check_again_in_seconds` is the soonest a later check is useful, not a polling interval. API-started onboarding finishes automatically.
* At `finish_in_web`, the web-started import has finished. Ask the user to switch to the company named in `next_step.message` in Finta first, then open `next_step.url`, choose **See dashboard**, and call `get_onboarding` again. Status stays `syncing` until that click; the browser may have another company selected.
* For a failed import, follow `next_step.message`: reconnect only when reauthentication is required. Use `contact_support` and the returned email when the connection is still active; a new connection link cannot retry that import.

Both tools need **Company: Manage**, **Integrations: Manage**, and **API access: Manage**. Updates also need a connection with write access. They return the same onboarding object as the [API](https://www.finta.com/docs/api-reference/onboarding.md); update errors include the API's error body, so `missing` is available after `answers_incomplete`.

The connection stays connected and all tools remain listed while onboarding is incomplete. Outside the [onboarding exceptions](https://www.finta.com/docs/api-reference/onboarding.md#endpoints-available-during-onboarding), calls return `onboarding_incomplete` as a tool error. Follow onboarding instead of repeatedly retrying another tool. A call-required or not-eligible company is held by the same gate.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.