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_onboardingas 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 returnoptions: [], 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_onboardingacceptsnullfor every answer field, including enum answers, so clients can replayget_onboardinganswers 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. Theanswersobject, array items,submit, andnotify_when_syncedremain non-nullable.- Bank/card input enums include canonical provider slugs such as
boaandamerican_express, so schema-enforcing clients can replay answers after recognized “other” names are folded. New answers may use those slugs directly. Savedno_bank_yetandno_credit_cards_yetvalues are allowed only as unchanged echoes; new selections are rejected. See the accepted values. - Answers saved on the web can be replayed unchanged, 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: useconnect_integrationfor new OAuth and Plaid connections, including Chase and SVB. The user approves on the returned provider or Plaid Hosted Link page; then checkget_integration_connection. The last selected bank completing either flow starts the import automatically. For a Plaid reconnect, follow the web get-started page instructions innext_step.message, then callupdate_onboardingwith{"answers":{}}to continue setup. This applies before and during the first import: Hosted Link cannot reconnect an existing bank and returns409 integration_already_connected. OAuth reconnects still useconnect_integration. - At
start_import, every selected bank is connected but importing has not started. Callupdate_onboardingwith{"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; setnotify_when_syncedto 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_syncto open the environment’s login URL innext_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_onboardingagain only if they ask or come back.sync.check_again_in_secondsis 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 innext_step.messagein Finta first, then opennext_step.url, choose See dashboard, and callget_onboardingagain. Status stayssyncinguntil that click; the browser may have another company selected. - For a failed import, follow
next_step.message: reconnect only when reauthentication is required. Usecontact_supportand the returned email when the connection is still active; a new connection link cannot retry that import.
missing is available after answers_incomplete.
The connection stays connected and all tools remain listed while onboarding is incomplete. Outside the onboarding exceptions, 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.