Onboarding

Retrieve onboarding

Returns where the company is in onboarding and what to do next. A new company answers a short questionnaire, Finta decides whether it can onboard the company, the company connects the banks and cards it selected, and Finta imports their transactions and sets up the books. Until that’s complete, every other endpoint except GET /integrations, POST /team/invitations and POST /feedback returns 403 onboarding_incomplete. POST /integrations/{key}/connect and GET /integrations/{key}/connect work once Finta has approved the company (status connect_banks or syncing), and return onboarding_incomplete before then.

For a new setup, open with: “Welcome to Finta! A few company questions, then connect your banks and we’ll set up your books.” Follow next_step.message for how to ask and next_step.action for what to do:

Action	What to do
`answer_questions`	Follow `next_step.message`: save what you can already answer from sources you may use, without asking or guessing, and ask only what’s still missing. For questions with options, use the app’s multiple-choice question tool if available; otherwise ask in plain text without numbered lists, showing options only if asked. Map answers to options and save answered keys with `PATCH /onboarding`.
`confirm_and_submit`	Recap every answer, saying where any found answer came from, then stop and wait for the user’s reply. Send `submit: true` only in a later turn after the user explicitly says yes to that recap (a yes picked in the app’s multiple-choice question tool counts); earlier confirmations do not count, and never recap and submit in the same turn.
`book_call`	Share `next_step.url` so the user can book a call.
`contact_support`	Explain `next_step.message` (ineligibility or a failed import with an active connection) and share `next_step.email`.
`connect_banks`	Follow `next_step.message`: use `POST /integrations/{key}/connect` for OAuth and Plaid banks, including Chase and SVB, and let the user approve on the returned provider or Plaid Hosted Link page. Poll the connect request afterwards; Plaid reconnects still require the web app.
`start_import`	Every selected bank is connected, but importing has not started. Send `PATCH /onboarding` with `answers: {}`, then follow the returned `next_step`.
`wait_for_sync`	Wait `sync.check_again_in_seconds` (30 seconds when `sync` is null) before checking again; no tight loop.
`finish_in_web`	The import started in the web app and has finished. Ask the user to switch to the API company in Finta first, then open `next_step.url` and choose See dashboard there; check onboarding again afterwards.
`none`	Onboarding is complete and every endpoint is available.

Onboarding needs the Company: Manage and Integrations: Manage permissions, as it does in the Finta web app; with less, this returns 403 insufficient_permission. This endpoint is free: it doesn’t count toward the monthly API limit and keeps answering after that limit is reached.

GET

onboarding

Retrieve onboarding

curl --request GET \
  --url https://app.finta.com/api/v1/onboarding \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.finta.com/api/v1/onboarding', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.finta.com/api/v1/onboarding",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.finta.com/api/v1/onboarding"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://app.finta.com/api/v1/onboarding")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "object": "onboarding",
  "status": "connect_banks",
  "answers": {
    "incorporation_year": 2024,
    "legal_entity_type": "c_corp",
    "legal_entity_state": "DE",
    "industry": "software",
    "international_subsidiaries": false,
    "banks": [
      "mercury",
      "chase"
    ],
    "other_bank": null,
    "credit_cards": [
      "ramp"
    ],
    "other_credit_card": null,
    "accounting_software": null,
    "files_taxes_with": null,
    "goals": null,
    "subsidiary_countries": []
  },
  "questions": [],
  "decision": {
    "outcome": "approved",
    "reason": null,
    "decided": 1792540579
  },
  "integrations": [
    {
      "key": "mercury",
      "name": "Mercury",
      "status": "connected"
    },
    {
      "key": "ramp",
      "name": "Ramp",
      "status": "connected"
    },
    {
      "key": "chase",
      "name": "Chase",
      "status": "not_connected"
    }
  ],
  "sync": null,
  "notify_when_synced": false,
  "next_step": {
    "action": "connect_banks",
    "message": "Help them connect Chase with POST /integrations/{key}/connect, one call each. Once connected, Finta will import transactions and set up their books."
  }
}

Authorizations

Authorization

string

header

required

API key prefixed with finta_

Response

The company's onboarding

object

enum<string>

required

Available options:

onboarding

status

enum<string>

required

Where the company is in onboarding. questionnaire: required questions are unanswered. ready_to_submit: every required question is answered and Finta hasn't decided yet. call_required: Finta needs a call with the company before it can onboard it. not_eligible: Finta can't onboard the company. connect_banks: approved, and the selected banks and cards are being connected. syncing: Finta is importing transactions and setting up the books, or a completed web-started import awaits finish_in_web. complete: the company is onboarded and every endpoint is available.

Available options:

questionnaire,

ready_to_submit,

call_required,

not_eligible,

connect_banks,

syncing,

complete

answers

object

required

The answers saved so far; null (or an empty list) when unanswered. accounting_software, files_taxes_with, goals and subsidiary_countries are asked only when Finta needs a call.

Show child attributes

questions

object[]

required

The questions still to ask at this stage, in order: the required ones unanswered, and credit_cards, which is optional, until a card is chosen. Empty once there is nothing to ask. Once an answer means Finta can't onboard the company, later questions aren't asked. Entity and industry questions show short choice lists. Bank and card questions have empty options; gather answers from context or plain text. Accepted values are in OnboardingUpdate.answers and the MCP update_onboarding input enums.

Show child attributes

decision

object | null

required

Finta's eligibility decision. null until Finta has decided.

Show child attributes

integrations

object[]

required

The banks and cards the company selected that onboarding waits on, in this order: Mercury, Brex, Ramp, Rho, SVB, Chase. A bank or card typed in as "other" isn't listed. Follow next_step.message for connecting them: OAuth and Plaid banks, including Chase and SVB, through the API. Plaid reconnects still require the web app.

Show child attributes

sync

object | null

required

The first sync's progress while status is syncing; null otherwise.

Show child attributes

notify_when_synced

boolean

required

Whether Finta emails the user when the first sync finishes, as the web app's "Email me when it's ready" sets.

next_step

object

required

What to do now. See GET /onboarding for what each action means.

Show child attributes

Retrieve onboarding

curl --request GET \
  --url https://app.finta.com/api/v1/onboarding \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.finta.com/api/v1/onboarding', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.finta.com/api/v1/onboarding",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.finta.com/api/v1/onboarding"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://app.finta.com/api/v1/onboarding")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "object": "onboarding",
  "status": "connect_banks",
  "answers": {
    "incorporation_year": 2024,
    "legal_entity_type": "c_corp",
    "legal_entity_state": "DE",
    "industry": "software",
    "international_subsidiaries": false,
    "banks": [
      "mercury",
      "chase"
    ],
    "other_bank": null,
    "credit_cards": [
      "ramp"
    ],
    "other_credit_card": null,
    "accounting_software": null,
    "files_taxes_with": null,
    "goals": null,
    "subsidiary_countries": []
  },
  "questions": [],
  "decision": {
    "outcome": "approved",
    "reason": null,
    "decided": 1792540579
  },
  "integrations": [
    {
      "key": "mercury",
      "name": "Mercury",
      "status": "connected"
    },
    {
      "key": "ramp",
      "name": "Ramp",
      "status": "connected"
    },
    {
      "key": "chase",
      "name": "Chase",
      "status": "not_connected"
    }
  ],
  "sync": null,
  "notify_when_synced": false,
  "next_step": {
    "action": "connect_banks",
    "message": "Help them connect Chase with POST /integrations/{key}/connect, one call each. Once connected, Finta will import transactions and set up their books."
  }
}

API Reference

Onboarding

Sheets

Taxes

Files

Company

Plans & billing

Team

Categories

Rules

Tags

Departments

Integrations

Inbox

Aggregations

Transactions

Forms

Journal Entries

Invoices

Parties

Reports

Feedback

Tax Credits

Retrieve onboarding

Authorizations

Response