Onboarding

Update onboarding

Saves answers to the onboarding questions, asks Finta to decide, and sets whether Finta emails the user when their books are ready. Returns the same object as GET /onboarding.

Only the answers you send change. Use what you can already reach (chat, local files, connected tools), within the permissions they’ve given you, to prefill sourced answers; name each source and confirm them together. Ask only what’s missing, two or three related questions at a time; save quietly. Never guess without a source; flag conflicts and ask.
One invalid answer, or an unknown field, rejects the whole request and saves nothing (400 invalid_request, with param naming it).
submit: true asks Finta to decide, which it does only once no required question is unanswered. If any is, the valid answers sent with the request are still saved and the response is 400 answers_incomplete, with the missing answer keys in missing.
Finta’s decision is final. Afterwards the eligibility answers can’t change (409 onboarding_locked); while Finta needs a call, the call follow-ups (incorporation_year, accounting_software, files_taxes_with, goals and subsidiary_countries) still can. Sending an answer that matches what’s saved isn’t a change, so repeating a request that already went through, submit included, returns 200 with the current state and changes nothing.
notify_when_synced: true is the web app’s “Email me when it’s ready”: Finta emails the user who sent it when the first sync finishes, or right away if it already has. false withdraws it. It can change until onboarding is complete, once at least one question is answered. Offer it at the import wait step once banks are connected, not during the questionnaire; honor a preference the user brings up at any time.
Once the company is onboarded, every request returns 409 onboarding_complete.

Needs Company: Manage and Integrations: Manage. This endpoint is free: it doesn’t count toward the monthly API limit and keeps answering after that limit is reached.

PATCH

onboarding

Update onboarding

curl --request PATCH \
  --url https://app.finta.com/api/v1/onboarding \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "answers": {
    "incorporation_year": 2024,
    "legal_entity_type": "c_corp",
    "legal_entity_state": "DE",
    "industry": "software",
    "international_subsidiaries": false,
    "banks": [
      "mercury",
      "chase"
    ],
    "credit_cards": [
      "ramp"
    ]
  },
  "submit": true,
  "notify_when_synced": true
}
'

import requests

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

payload = {
    "answers": {
        "incorporation_year": 2024,
        "legal_entity_type": "c_corp",
        "legal_entity_state": "DE",
        "industry": "software",
        "international_subsidiaries": False,
        "banks": ["mercury", "chase"],
        "credit_cards": ["ramp"]
    },
    "submit": True,
    "notify_when_synced": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    answers: {
      incorporation_year: 2024,
      legal_entity_type: 'c_corp',
      legal_entity_state: 'DE',
      industry: 'software',
      international_subsidiaries: false,
      banks: ['mercury', 'chase'],
      credit_cards: ['ramp']
    },
    submit: true,
    notify_when_synced: true
  })
};

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 => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'answers' => [
        'incorporation_year' => 2024,
        'legal_entity_type' => 'c_corp',
        'legal_entity_state' => 'DE',
        'industry' => 'software',
        'international_subsidiaries' => false,
        'banks' => [
                'mercury',
                'chase'
        ],
        'credit_cards' => [
                'ramp'
        ]
    ],
    'submit' => true,
    'notify_when_synced' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"answers\": {\n    \"incorporation_year\": 2024,\n    \"legal_entity_type\": \"c_corp\",\n    \"legal_entity_state\": \"DE\",\n    \"industry\": \"software\",\n    \"international_subsidiaries\": false,\n    \"banks\": [\n      \"mercury\",\n      \"chase\"\n    ],\n    \"credit_cards\": [\n      \"ramp\"\n    ]\n  },\n  \"submit\": true,\n  \"notify_when_synced\": true\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://app.finta.com/api/v1/onboarding")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"answers\": {\n    \"incorporation_year\": 2024,\n    \"legal_entity_type\": \"c_corp\",\n    \"legal_entity_state\": \"DE\",\n    \"industry\": \"software\",\n    \"international_subsidiaries\": false,\n    \"banks\": [\n      \"mercury\",\n      \"chase\"\n    ],\n    \"credit_cards\": [\n      \"ramp\"\n    ]\n  },\n  \"submit\": true,\n  \"notify_when_synced\": true\n}")
  .asString();

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::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"answers\": {\n    \"incorporation_year\": 2024,\n    \"legal_entity_type\": \"c_corp\",\n    \"legal_entity_state\": \"DE\",\n    \"industry\": \"software\",\n    \"international_subsidiaries\": false,\n    \"banks\": [\n      \"mercury\",\n      \"chase\"\n    ],\n    \"credit_cards\": [\n      \"ramp\"\n    ]\n  },\n  \"submit\": true,\n  \"notify_when_synced\": true\n}"

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

{
  "object": "onboarding",
  "status": "questionnaire",
  "answers": {
    "incorporation_year": 2024,
    "legal_entity_type": "c_corp",
    "legal_entity_state": "DE",
    "industry": "software",
    "international_subsidiaries": true,
    "banks": [
      "mercury"
    ],
    "other_bank": "<string>",
    "credit_cards": [
      "ramp"
    ],
    "other_credit_card": "<string>",
    "accounting_software": "<string>",
    "files_taxes_with": "<string>",
    "goals": "<string>",
    "subsidiary_countries": [
      "<string>"
    ]
  },
  "questions": [
    {
      "key": "legal_entity_type",
      "label": "What is your legal entity type?",
      "type": "single_select",
      "required": true,
      "options": [
        {
          "value": "c_corp",
          "label": "C Corporation"
        },
        {
          "value": "llc",
          "label": "LLC"
        },
        {
          "value": "pbc",
          "label": "Public benefit corporation"
        },
        {
          "value": "s_corp",
          "label": "S Corporation"
        }
      ]
    }
  ],
  "decision": {
    "outcome": "approved",
    "reason": "Unfortunately, Finta cannot support crypto startups.",
    "decided": 1792540579
  },
  "integrations": [
    {
      "key": "mercury",
      "name": "Mercury",
      "status": "not_connected"
    }
  ],
  "sync": {
    "stage": "downloading",
    "check_again_in_seconds": 30
  },
  "notify_when_synced": true,
  "next_step": {
    "action": "answer_questions",
    "message": "<string>",
    "url": "https://cal.com/finta/intro",
    "email": "support@finta.com"
  }
}

Authorizations

Authorization

string

header

required

API key prefixed with finta_

Body

application/json

answers

object

Only the answers to save, keyed as in questions. Answers left out keep their saved values. The enums below include accepted values hidden from the question's suggested choices. null clears an optional answer; a required one can't be cleared.

Show child attributes

submit

boolean

true asks Finta to decide once no required question is unanswered. Send it only after the user explicitly says yes to a recap of every answer in a later turn; stop and wait after the recap. A yes picked in the app's multiple-choice question tool after the recap counts. Earlier confirmations do not count; never recap and submit in the same turn. Repeating it after Finta decided changes nothing.

notify_when_synced

boolean

true to email the user who sends it when the first sync finishes; false to stop that email.

Response

The company's onboarding after the change

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

Update onboarding

curl --request PATCH \
  --url https://app.finta.com/api/v1/onboarding \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "answers": {
    "incorporation_year": 2024,
    "legal_entity_type": "c_corp",
    "legal_entity_state": "DE",
    "industry": "software",
    "international_subsidiaries": false,
    "banks": [
      "mercury",
      "chase"
    ],
    "credit_cards": [
      "ramp"
    ]
  },
  "submit": true,
  "notify_when_synced": true
}
'

import requests

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

payload = {
    "answers": {
        "incorporation_year": 2024,
        "legal_entity_type": "c_corp",
        "legal_entity_state": "DE",
        "industry": "software",
        "international_subsidiaries": False,
        "banks": ["mercury", "chase"],
        "credit_cards": ["ramp"]
    },
    "submit": True,
    "notify_when_synced": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    answers: {
      incorporation_year: 2024,
      legal_entity_type: 'c_corp',
      legal_entity_state: 'DE',
      industry: 'software',
      international_subsidiaries: false,
      banks: ['mercury', 'chase'],
      credit_cards: ['ramp']
    },
    submit: true,
    notify_when_synced: true
  })
};

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 => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'answers' => [
        'incorporation_year' => 2024,
        'legal_entity_type' => 'c_corp',
        'legal_entity_state' => 'DE',
        'industry' => 'software',
        'international_subsidiaries' => false,
        'banks' => [
                'mercury',
                'chase'
        ],
        'credit_cards' => [
                'ramp'
        ]
    ],
    'submit' => true,
    'notify_when_synced' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"answers\": {\n    \"incorporation_year\": 2024,\n    \"legal_entity_type\": \"c_corp\",\n    \"legal_entity_state\": \"DE\",\n    \"industry\": \"software\",\n    \"international_subsidiaries\": false,\n    \"banks\": [\n      \"mercury\",\n      \"chase\"\n    ],\n    \"credit_cards\": [\n      \"ramp\"\n    ]\n  },\n  \"submit\": true,\n  \"notify_when_synced\": true\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://app.finta.com/api/v1/onboarding")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"answers\": {\n    \"incorporation_year\": 2024,\n    \"legal_entity_type\": \"c_corp\",\n    \"legal_entity_state\": \"DE\",\n    \"industry\": \"software\",\n    \"international_subsidiaries\": false,\n    \"banks\": [\n      \"mercury\",\n      \"chase\"\n    ],\n    \"credit_cards\": [\n      \"ramp\"\n    ]\n  },\n  \"submit\": true,\n  \"notify_when_synced\": true\n}")
  .asString();

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::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"answers\": {\n    \"incorporation_year\": 2024,\n    \"legal_entity_type\": \"c_corp\",\n    \"legal_entity_state\": \"DE\",\n    \"industry\": \"software\",\n    \"international_subsidiaries\": false,\n    \"banks\": [\n      \"mercury\",\n      \"chase\"\n    ],\n    \"credit_cards\": [\n      \"ramp\"\n    ]\n  },\n  \"submit\": true,\n  \"notify_when_synced\": true\n}"

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

{
  "object": "onboarding",
  "status": "questionnaire",
  "answers": {
    "incorporation_year": 2024,
    "legal_entity_type": "c_corp",
    "legal_entity_state": "DE",
    "industry": "software",
    "international_subsidiaries": true,
    "banks": [
      "mercury"
    ],
    "other_bank": "<string>",
    "credit_cards": [
      "ramp"
    ],
    "other_credit_card": "<string>",
    "accounting_software": "<string>",
    "files_taxes_with": "<string>",
    "goals": "<string>",
    "subsidiary_countries": [
      "<string>"
    ]
  },
  "questions": [
    {
      "key": "legal_entity_type",
      "label": "What is your legal entity type?",
      "type": "single_select",
      "required": true,
      "options": [
        {
          "value": "c_corp",
          "label": "C Corporation"
        },
        {
          "value": "llc",
          "label": "LLC"
        },
        {
          "value": "pbc",
          "label": "Public benefit corporation"
        },
        {
          "value": "s_corp",
          "label": "S Corporation"
        }
      ]
    }
  ],
  "decision": {
    "outcome": "approved",
    "reason": "Unfortunately, Finta cannot support crypto startups.",
    "decided": 1792540579
  },
  "integrations": [
    {
      "key": "mercury",
      "name": "Mercury",
      "status": "not_connected"
    }
  ],
  "sync": {
    "stage": "downloading",
    "check_again_in_seconds": 30
  },
  "notify_when_synced": true,
  "next_step": {
    "action": "answer_questions",
    "message": "<string>",
    "url": "https://cal.com/finta/intro",
    "email": "support@finta.com"
  }
}

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

Update onboarding

Authorizations

Body

Response