Integrations

Grant integration access

Records that the user has invited Finta as a user in the provider’s own app, for a grant_access connection method whose connect_via is provider_app in GET /integrations. Finta can’t see the invite, so it relies on this. Call it only once the user says the invite is sent.

Granting access also closes the Finta inbox item that asked for it, such as Mercury Treasury’s or Ramp Checking’s grant_access item. Calling it again once access is granted changes nothing and returns the same integration.

Carta and Pulley also need url, the company’s page at the provider, such as https://app.carta.com/corporations/12345 or https://pulley.com/companies/1234. Finta then checks the invite in the background (for Carta from that page, for Pulley once Pulley’s invite email arrives), and the integration’s status is connecting until it has. Other integrations reject url.

For Gusto and Rippling, granting access connects the payroll integration: its status and its grant_access method read connected, and Finta’s team is told to review it.

Any other integration, or Mercury and Ramp while Finta isn’t asking for access, returns 400 integration_not_grantable.

POST

integrations

{key}

grant_access

Grant integration access

curl --request POST \
  --url https://app.finta.com/api/v1/integrations/{key}/grant_access \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://app.carta.com/corporations/12345"
}
'

import requests

url = "https://app.finta.com/api/v1/integrations/{key}/grant_access"

payload = { "url": "https://app.carta.com/corporations/12345" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({url: 'https://app.carta.com/corporations/12345'})
};

fetch('https://app.finta.com/api/v1/integrations/{key}/grant_access', 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}/grant_access",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'url' => 'https://app.carta.com/corporations/12345'
  ]),
  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/integrations/{key}/grant_access"

	payload := strings.NewReader("{\n  \"url\": \"https://app.carta.com/corporations/12345\"\n}")

	req, _ := http.NewRequest("POST", 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.post("https://app.finta.com/api/v1/integrations/{key}/grant_access")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"url\": \"https://app.carta.com/corporations/12345\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.finta.com/api/v1/integrations/{key}/grant_access")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"url\": \"https://app.carta.com/corporations/12345\"\n}"

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

{
  "key": "ramp",
  "object": "integration",
  "name": "Ramp",
  "type": "banking",
  "status": "connected",
  "connection_methods": [
    {
      "type": "oauth",
      "status": "connected",
      "connect_via": "api"
    },
    {
      "type": "grant_access",
      "status": "granted",
      "connect_via": "provider_app"
    }
  ],
  "quality": "great",
  "signup_referral": null
}

Authorizations

Authorization

string

header

required

An API key prefixed with finta_, or the access token from a Finta CLI browser login (finta login), prefixed with finta_oat_. A CLI login's access token lasts one hour and the CLI renews it itself.

Path Parameters

key

string

required

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

Body

application/json

url

string

Carta and Pulley only, and required for them: the company's page URL at the provider, or just its numeric ID there.

Example:

"https://app.carta.com/corporations/12345"

Response

The integration, as GET /integrations lists it, with its grant_access method granted (connecting for Carta and Pulley, connected for Gusto and Rippling).

key

string

required

Stable identifier for the integration, e.g. mercury, ramp, carta.

Example:

"mercury"

object

enum<string>

required

Available options:

integration

name

string

required

Human-readable vendor name.

Example:

"Mercury"

type

enum<string>

required

What kind of integration this is.

Available options:

banking,

cap_table,

payroll,

revenue,

notifications,

legal

status

enum<string>

required

Connection state. connecting means Finta has the connection but isn't done setting it up, such as a Carta or Pulley connection whose invite Finta is still checking. requires_reconnect means a previously working connection needs the user to reauthenticate.

Available options:

not_connected,

connected,

connecting,

requires_reconnect

connection_methods

object[]

required

Each way this integration can be connected, with where it stands. Every integration has the method it connects with. Mercury and Ramp also list a grant_access method once Finta asks the company to invite Finta for Mercury Treasury or Ramp Checking, data their sign-in connection doesn't include. Order is not significant.

Show child attributes

quality

enum<string>

required

How reliable this integration's data is, the same rating the Finta web app shows. great is an OAuth or API connection with real-time updates, good is read-only access straight from the source that is not real-time, and third_party is a Plaid-based bank connection whose data can be incomplete or error-prone.

Available options:

great,

good,

third_party

A referral offer for opening an account with this provider. Present only while status is not_connected and the provider has a Finta referral; null otherwise.

Show child attributes

Grant integration access

curl --request POST \
  --url https://app.finta.com/api/v1/integrations/{key}/grant_access \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://app.carta.com/corporations/12345"
}
'

import requests

url = "https://app.finta.com/api/v1/integrations/{key}/grant_access"

payload = { "url": "https://app.carta.com/corporations/12345" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({url: 'https://app.carta.com/corporations/12345'})
};

fetch('https://app.finta.com/api/v1/integrations/{key}/grant_access', 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}/grant_access",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'url' => 'https://app.carta.com/corporations/12345'
  ]),
  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/integrations/{key}/grant_access"

	payload := strings.NewReader("{\n  \"url\": \"https://app.carta.com/corporations/12345\"\n}")

	req, _ := http.NewRequest("POST", 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.post("https://app.finta.com/api/v1/integrations/{key}/grant_access")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"url\": \"https://app.carta.com/corporations/12345\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.finta.com/api/v1/integrations/{key}/grant_access")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"url\": \"https://app.carta.com/corporations/12345\"\n}"

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

{
  "key": "ramp",
  "object": "integration",
  "name": "Ramp",
  "type": "banking",
  "status": "connected",
  "connection_methods": [
    {
      "type": "oauth",
      "status": "connected",
      "connect_via": "api"
    },
    {
      "type": "grant_access",
      "status": "granted",
      "connect_via": "provider_app"
    }
  ],
  "quality": "great",
  "signup_referral": null
}

API Reference

Onboarding

Sheets

Taxes

Files

Company

Plans & billing

Team

Categories

Rules

Tags

Departments

Integrations

Inbox

Aggregations

Transactions

Forms

Reconciliation

Journal Entries

Invoices

Parties

Metrics

Reports

Feedback

Tax Credits

Grant integration access

Authorizations

Path Parameters

Body

Response