Team

Create invitation

Creates an invitation in the API key’s company as the key owner. Requires API access Manage and Team & access Manage. The caller cannot grant access they do not have. Requires JSON with nonblank first_name, last_name, email, and access_template. Unknown fields are rejected. Query parameters do not supply invitation fields.

Choose admin or read_only without permissions, or custom with every permission area and a supported level. Extra permission areas are rejected. API access supports only none or manage. Custom permissions matching a preset are labeled as that preset in responses. A permissions field is forbidden with a named preset even when its value is null.

Read-only and non-Admin permission sets require an active or trialing Growth subscription. Other plans may invite Admin only, subject to the caller’s grant permissions. When RBAC is disabled, only access_template admin is supported; other selections are rejected, never silently promoted. Existing API subscription and usage checks also apply. The plan rule compares actual permissions: custom matching Admin satisfies the plan rule when RBAC is enabled. Growth does not bypass the caller’s grant limits. Once feature availability is validated, creation preserves the submitted permissions; another feature-flag evaluation cannot silently replace them with Admin.

Returns 201 with changed=false for a new record, or 200 for an exact replay of a pending invitation with the same inviter, first and last names, case-insensitive email, and permissions. Same email alone is not a match. A replay may renew an expired invitation or retry pending delivery; changed is true when that work is requested, and false for an unchanged replay. Plan and permission checks still apply to replays. Success does not guarantee email arrival. No separate idempotency key is needed. Use the same body to retry an uncertain result.

The invitation is saved state with the same fields as GET /team, including the opaque version revision. Treat version as opaque; resend uses the current revision internally and does not accept it as input. It is not an acceptance credential. Public IDs may be null. A null ID means the public identifier is unavailable, not that the record is missing; a later backfill may populate it. Treat unknown future enum values as unsupported, never as additional access. Allow for new response fields when updating clients.

POST

team

invitations

Create invitation

curl --request POST \
  --url https://app.finta.com/api/v1/team/invitations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "first_name": "Sam",
  "last_name": "Rivera",
  "email": "sam@example.com",
  "access_template": "read_only"
}
'

import requests

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

payload = {
    "first_name": "Sam",
    "last_name": "Rivera",
    "email": "sam@example.com",
    "access_template": "read_only"
}
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({
    first_name: 'Sam',
    last_name: 'Rivera',
    email: 'sam@example.com',
    access_template: 'read_only'
  })
};

fetch('https://app.finta.com/api/v1/team/invitations', 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/team/invitations",
  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([
    'first_name' => 'Sam',
    'last_name' => 'Rivera',
    'email' => 'sam@example.com',
    'access_template' => 'read_only'
  ]),
  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/team/invitations"

	payload := strings.NewReader("{\n  \"first_name\": \"Sam\",\n  \"last_name\": \"Rivera\",\n  \"email\": \"sam@example.com\",\n  \"access_template\": \"read_only\"\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/team/invitations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"first_name\": \"Sam\",\n  \"last_name\": \"Rivera\",\n  \"email\": \"sam@example.com\",\n  \"access_template\": \"read_only\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"first_name\": \"Sam\",\n  \"last_name\": \"Rivera\",\n  \"email\": \"sam@example.com\",\n  \"access_template\": \"read_only\"\n}"

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

{
  "invitation": {
    "version": "2026-09-09T17:20:00.000000Z",
    "id": "invite_h8i9j0k1l2m3n4",
    "invited_by": "usr_a1b2c3d4e5f6g7",
    "expires": 1791568800,
    "object": "invitation",
    "email": "sam@example.com",
    "name": "Sam Rivera",
    "access_template": "admin",
    "permissions": {
      "dashboard": "none",
      "transactions": "none",
      "accounting_setup": "none",
      "reconciliation": "none",
      "invoices": "none",
      "reports": "none",
      "forecast": "none",
      "taxes": "none",
      "integrations": "none",
      "company": "none",
      "team_access": "none",
      "billing": "none",
      "ask_finta": "none",
      "api_access": "none"
    },
    "created": 1788976800
  },
  "changed": true
}

Authorizations

Authorization

string

header

required

API key prefixed with finta_

Body

application/json

Option 1
Option 2

access_template

enum<string>

required

The template matching stored permissions. Admin means all areas have manage access. Read_only means view access for every area except api_access, which is none. Custom means neither template matches exactly; inspect permissions for the actual access.

Available options:

admin,

read_only

first_name

string

required

Minimum string length: 1

Pattern: \S

last_name

string

required

Minimum string length: 1

Pattern: \S

string

required

A valid email address. Email validity and existing teammate checks are enforced by the invitation service.

Minimum string length: 1

permissions

object

Stored company permissions shown on the Settings team page. All areas are always included. None means no access to the area; view means read access; manage means management access. API access supports none or manage; other areas also support view.

Show child attributes

Response

An existing matching invitation was returned, possibly renewed or retried.

invitation

object

required

Show child attributes

changed

boolean

required

False for a newly created invitation (201) and an unchanged replay. True when an existing invitation is renewed, its permissions change, or delivery work is requested. Not a guarantee that email arrived; use HTTP 201 to identify creation.

Create invitation

curl --request POST \
  --url https://app.finta.com/api/v1/team/invitations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "first_name": "Sam",
  "last_name": "Rivera",
  "email": "sam@example.com",
  "access_template": "read_only"
}
'

import requests

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

payload = {
    "first_name": "Sam",
    "last_name": "Rivera",
    "email": "sam@example.com",
    "access_template": "read_only"
}
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({
    first_name: 'Sam',
    last_name: 'Rivera',
    email: 'sam@example.com',
    access_template: 'read_only'
  })
};

fetch('https://app.finta.com/api/v1/team/invitations', 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/team/invitations",
  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([
    'first_name' => 'Sam',
    'last_name' => 'Rivera',
    'email' => 'sam@example.com',
    'access_template' => 'read_only'
  ]),
  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/team/invitations"

	payload := strings.NewReader("{\n  \"first_name\": \"Sam\",\n  \"last_name\": \"Rivera\",\n  \"email\": \"sam@example.com\",\n  \"access_template\": \"read_only\"\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/team/invitations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"first_name\": \"Sam\",\n  \"last_name\": \"Rivera\",\n  \"email\": \"sam@example.com\",\n  \"access_template\": \"read_only\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"first_name\": \"Sam\",\n  \"last_name\": \"Rivera\",\n  \"email\": \"sam@example.com\",\n  \"access_template\": \"read_only\"\n}"

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

{
  "invitation": {
    "version": "2026-09-09T17:20:00.000000Z",
    "id": "invite_h8i9j0k1l2m3n4",
    "invited_by": "usr_a1b2c3d4e5f6g7",
    "expires": 1791568800,
    "object": "invitation",
    "email": "sam@example.com",
    "name": "Sam Rivera",
    "access_template": "admin",
    "permissions": {
      "dashboard": "none",
      "transactions": "none",
      "accounting_setup": "none",
      "reconciliation": "none",
      "invoices": "none",
      "reports": "none",
      "forecast": "none",
      "taxes": "none",
      "integrations": "none",
      "company": "none",
      "team_access": "none",
      "billing": "none",
      "ask_finta": "none",
      "api_access": "none"
    },
    "created": 1788976800
  },
  "changed": true
}

API Reference

Company

Team

Categories

Departments

Integrations

Aggregations

Transactions

Journal Entries

Parties

Reports

Create invitation

Authorizations

Body

Response