Integrations

Connect integration

Returns a link that a person opens to connect this integration to the company. The API cannot connect a provider by itself: the provider requires the account holder to sign in and approve access in a browser. This endpoint starts that flow and hands you the link. Only integrations with api_connectable: true in GET /integrations are supported; any other returns 400 integration_not_connectable.

What to do with the link

Show url to the user, or open it in their browser with their permission.
They must open it in a browser where they are signed in to Finta as the owner of this API key. The connection is rejected if a different Finta user completes it.
They approve access on the provider’s page. Do not fill in, click through, or otherwise automate that page. The approval has to come from the person.
Poll GET /integrations/{key}/connect and follow its instructions.

One request at a time

A company has at most one open request per integration. Calling this endpoint again returns it with 200, so retries are safe. After it fails or expires, the next call starts a new one with 201. While another user holds the open request, this returns 409 connect_link_in_progress.

POST

integrations

{key}

connect

Connect integration

curl --request POST \
  --url https://app.finta.com/api/v1/integrations/{key}/connect \
  --header 'Authorization: Bearer <token>'

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

fetch('https://app.finta.com/api/v1/integrations/{key}/connect', 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/integrations/{key}/connect",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  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/integrations/{key}/connect"

	req, _ := http.NewRequest("POST", 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/integrations/{key}/connect")

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

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

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

{
  "object": "connect_request",
  "integration": "mercury",
  "intent": "connect",
  "status": "pending",
  "url": "https://oauth2.mercury.com/oauth2/auth?client_id=example&redirect_uri=https%3A%2F%2Fapp.finta.com%2Fintegrations%2Fmercury%2Fcallback&response_type=code&scope=offline_access+read&state=example",
  "expires_at": 1790170200,
  "failure_code": "access_denied",
  "instructions": "<string>"
}

Authorizations

Authorization

string

header

required

API key prefixed with finta_

Path Parameters

key

string

required

The integration's key from GET /integrations, e.g. mercury.

Response

The company's open connection request for this integration was returned again.

object

enum<string>

required

Available options:

connect_request

integration

string

required

The integration's key.

Example:

"mercury"

intent

enum<string>

required

reconnect re-authenticates an existing connection whose status is requires_reconnect.

Available options:

connect,

reconnect

status

enum<string>

required

pending until the provider sends the user back, then authorizing while Finta finishes the connection, then complete or failed. expired when nobody finished the link before expires_at. A request already authorizing when expires_at passes stays authorizing while Finta finishes it.

Available options:

pending,

authorizing,

complete,

failed,

expired

Example:

"pending"

url

string<uri> | null

required

The provider's authorization page. A person opens it in a browser signed in to Finta as the API key's owner. Single use. null unless status is pending.

Example:

"https://oauth2.mercury.com/oauth2/auth?client_id=example&redirect_uri=https%3A%2F%2Fapp.finta.com%2Fintegrations%2Fmercury%2Fcallback&response_type=code&scope=offline_access+read&state=example"

expires_at

integer

required

Unix timestamp (seconds) after which the link stops working.

Example:

1790170200

failure_code

enum<string> | null

required

Why a failed request failed; null for every other status. access_denied: the user declined at the provider. provider_admin_required: the provider account that approved is not an administrator. provider_error: the provider returned an error or no authorization code. connection_failed: Finta could not finish the connection.

Available options:

access_denied,

provider_admin_required,

provider_error,

connection_failed

instructions

string

required

Plain-language next steps for the current status, including how often to poll.

Connect integration

curl --request POST \
  --url https://app.finta.com/api/v1/integrations/{key}/connect \
  --header 'Authorization: Bearer <token>'

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

fetch('https://app.finta.com/api/v1/integrations/{key}/connect', 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/integrations/{key}/connect",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  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/integrations/{key}/connect"

	req, _ := http.NewRequest("POST", 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/integrations/{key}/connect")

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

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

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

{
  "object": "connect_request",
  "integration": "mercury",
  "intent": "connect",
  "status": "pending",
  "url": "https://oauth2.mercury.com/oauth2/auth?client_id=example&redirect_uri=https%3A%2F%2Fapp.finta.com%2Fintegrations%2Fmercury%2Fcallback&response_type=code&scope=offline_access+read&state=example",
  "expires_at": 1790170200,
  "failure_code": "access_denied",
  "instructions": "<string>"
}

API Reference

Company

Team

Categories

Rules

Departments

Integrations

Aggregations

Transactions

Journal Entries

Parties

Reports

Connect integration

What to do with the link

One request at a time

Authorizations

Path Parameters

Response