Skip to main content
After connecting Finta, 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.
  • 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: 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; 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, 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.