Create category

Adds one of Finta’s standard categories to the company’s chart of accounts: the same templates people add themselves under Settings -> Categories in the Finta web app. You name a template, never a category name or parent, and each template always goes under the same parent, so nothing outside this list can be created. Requires API access and Accounting setup: Manage.

`template`	Adds	Under
`fulfillment`	Fulfillment	Cost of Revenue
`cost_of_services`	Cost of Services	Cost of Revenue
`rd_expenses`	R&D Expenses, with Consumables, Biologicals, Chemicals and R&D services beneath it. Needs the Startup plan or higher.	Expenses
`equipment`	Equipment and Accumulated Depreciation. Transactions categorized as Equipment are depreciated over 5 years.	Assets
`inventory`	Inventory	Assets
`intercompany_expenses`	Intercompany Expenses. Only Finta adds it.	Expenses
`investments`	Investments. Only Finta adds it.	Assets
`shareholder_dividends`	Shareholder Dividends. Only Finta adds it.	Equity

Returns every category of the template in the GET /categories shape, so you can use the IDs right away: 201 when this call added any of them or repaired one, 200 when they all already existed. Repairing means an existing category with the template’s name that wasn’t yet linked to the template becomes the template’s category (for Equipment, that turns on depreciation). Retrying is safe without an idempotency key; a template’s categories are never created twice. Check GET /categories first.

A template only Finta adds is never created here. It returns 403 request_required: ask for it from Settings -> Categories in the web app, and Finta adds it. Once Finta has added it, this returns it with 200. On a plan below Startup, rd_expenses and the templates only Finta adds return 403 plan_upgrade_required instead.

POST

categories

Create category

curl --request POST \
  --url https://app.finta.com/api/v1/categories \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "template": "equipment"
}
'

import requests

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

payload = { "template": "equipment" }
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({template: 'equipment'})
};

fetch('https://app.finta.com/api/v1/categories', 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/categories",
  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([
    'template' => 'equipment'
  ]),
  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/categories"

	payload := strings.NewReader("{\n  \"template\": \"equipment\"\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/categories")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"template\": \"equipment\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"template\": \"equipment\"\n}"

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

{
  "object": "list",
  "url": "/api/v1/categories",
  "data": [
    {
      "id": "cat_abc123",
      "object": "category",
      "name": "Software & SaaS",
      "description": "Recurring subscriptions to software and SaaS tools, such as GitHub, Slack, or Figma.",
      "account_type": "expense",
      "point_in_time": false,
      "tier": 1,
      "position": 3,
      "accounting_treatment": "Depreciated straight-line over 5 years: the purchase is recorded as an asset and expensed monthly as depreciation.",
      "created": 1688053841,
      "parent_id": "cat_parent123"
    }
  ]
}

Authorizations

Authorization

string

header

required

API key prefixed with finta_

Body

application/json

template

enum<string>

required

The standard category to add; see POST /categories for what each adds. rd_expenses needs the Startup plan or higher. intercompany_expenses, investments, and shareholder_dividends are added only by Finta and return 403 request_required.

Available options:

fulfillment,

cost_of_services,

rd_expenses,

intercompany_expenses,

equipment,

inventory,

investments,

shareholder_dividends

Example:

"equipment"

Response

The template's categories all already existed. Returns them unchanged.

object

enum<string>

required

Available options:

list

url

string

required

The canonical path of the collection, relative to the API host.

Example:

"/api/v1/categories"

data

object[]

required

Show child attributes

Create category

curl --request POST \
  --url https://app.finta.com/api/v1/categories \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "template": "equipment"
}
'

import requests

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

payload = { "template": "equipment" }
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({template: 'equipment'})
};

fetch('https://app.finta.com/api/v1/categories', 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/categories",
  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([
    'template' => 'equipment'
  ]),
  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/categories"

	payload := strings.NewReader("{\n  \"template\": \"equipment\"\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/categories")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"template\": \"equipment\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"template\": \"equipment\"\n}"

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

{
  "object": "list",
  "url": "/api/v1/categories",
  "data": [
    {
      "id": "cat_abc123",
      "object": "category",
      "name": "Software & SaaS",
      "description": "Recurring subscriptions to software and SaaS tools, such as GitHub, Slack, or Figma.",
      "account_type": "expense",
      "point_in_time": false,
      "tier": 1,
      "position": 3,
      "accounting_treatment": "Depreciated straight-line over 5 years: the purchase is recorded as an asset and expensed monthly as depreciation.",
      "created": 1688053841,
      "parent_id": "cat_parent123"
    }
  ]
}

API Reference

Sheets

Taxes

Files

Company

Plans & billing

Team

Categories

Rules

Tags

Departments

Integrations

Aggregations

Transactions

Forms

Journal Entries

Invoices

Parties

Reports

Feedback

Tax Credits

Create category

Authorizations

Body

Response