Rules

Create rule

Saves a company automation rule and returns its complete definition. Requires API access: Manage and Accounting setup: Manage. Historical application additionally requires Transactions: Manage, rechecked at execution. apply_to_existing_transactions is a strict boolean defaulting to true; false saves a future-only rule. A 201 confirms saving, not completion of historical application. Requested work is saved durably and recovered after enqueue failures. No public job, polling endpoint, or Idempotency-Key is required. The application flag is never returned as saved state. Historical eligibility is approved uncategorized transactions; department actions additionally consider missing-department transactions and never replace assigned departments. Existing priority, automation limits and rollback behavior apply. Accounting-date offsets apply only on import; mixed rules can apply other actions historically. No bulk transaction cap or split exclusion applies. A pending run is cancelled by a successful edit or delete before it starts. Running work is serialized against edits/deletes; callers can retry a busy mutation. Failed historical application does not delete the saved rule. There is no feature flag. Exact duplicates in the same company return 409 rule_already_exists with the accessible existing rule ID in the message, without another run. Condition and action order and case-insensitive text condition casing do not distinguish definitions; the application flag does not distinguish them. After an uncertain response, an identical retry may return that conflict: retrieve the existing rule instead of requesting another run. Different actions are not exact duplicates. Unknown keys, legacy write fields, null actions, wrong types, reversed ranges and unsupported combinations return 400. Unavailable references return 404 without revealing foreign resources.

POST

rules

Create rule

curl --request POST \
  --url https://finta.lol/api/v1/rules \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "conditions": [
    {
      "field": "merchant",
      "operator": "contains",
      "value": "Cursor"
    }
  ],
  "actions": {
    "merchant": "Cursor AI"
  },
  "apply_to_existing_transactions": true
}
'

import requests

url = "https://finta.lol/api/v1/rules"

payload = {
    "conditions": [
        {
            "field": "merchant",
            "operator": "contains",
            "value": "Cursor"
        }
    ],
    "actions": { "merchant": "Cursor AI" },
    "apply_to_existing_transactions": True
}
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({
    conditions: [{field: 'merchant', operator: 'contains', value: 'Cursor'}],
    actions: {merchant: 'Cursor AI'},
    apply_to_existing_transactions: true
  })
};

fetch('https://finta.lol/api/v1/rules', 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://finta.lol/api/v1/rules",
  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([
    'conditions' => [
        [
                'field' => 'merchant',
                'operator' => 'contains',
                'value' => 'Cursor'
        ]
    ],
    'actions' => [
        'merchant' => 'Cursor AI'
    ],
    'apply_to_existing_transactions' => 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://finta.lol/api/v1/rules"

	payload := strings.NewReader("{\n  \"conditions\": [\n    {\n      \"field\": \"merchant\",\n      \"operator\": \"contains\",\n      \"value\": \"Cursor\"\n    }\n  ],\n  \"actions\": {\n    \"merchant\": \"Cursor AI\"\n  },\n  \"apply_to_existing_transactions\": true\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://finta.lol/api/v1/rules")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"conditions\": [\n    {\n      \"field\": \"merchant\",\n      \"operator\": \"contains\",\n      \"value\": \"Cursor\"\n    }\n  ],\n  \"actions\": {\n    \"merchant\": \"Cursor AI\"\n  },\n  \"apply_to_existing_transactions\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://finta.lol/api/v1/rules")

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  \"conditions\": [\n    {\n      \"field\": \"merchant\",\n      \"operator\": \"contains\",\n      \"value\": \"Cursor\"\n    }\n  ],\n  \"actions\": {\n    \"merchant\": \"Cursor AI\"\n  },\n  \"apply_to_existing_transactions\": true\n}"

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

{
  "id": "<string>",
  "object": "rule",
  "conditions": [
    {
      "field": "merchant",
      "operator": "equals",
      "value": "<string>"
    }
  ],
  "actions": {
    "merchant": "<string>",
    "category_id": "<string>",
    "department_id": "<string>",
    "spread": 19,
    "accounting_date_offset_months": 0
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "<string>",
    "doc_url": "https://finta.lol/docs/api-reference/errors#invalid_api_key",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "<string>",
    "doc_url": "https://finta.lol/docs/api-reference/errors#invalid_api_key",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "<string>",
    "doc_url": "https://finta.lol/docs/api-reference/errors#invalid_api_key",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "<string>",
    "doc_url": "https://finta.lol/docs/api-reference/errors#invalid_api_key",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "<string>",
    "doc_url": "https://finta.lol/docs/api-reference/errors#invalid_api_key",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "<string>",
    "doc_url": "https://finta.lol/docs/api-reference/errors#invalid_api_key",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "<string>",
    "doc_url": "https://finta.lol/docs/api-reference/errors#invalid_api_key",
    "param": "<string>"
  }
}

Authorizations

Authorization

string

header

required

API key prefixed with finta_

Body

application/json

conditions

object[]

required

Nonempty flat AND list. Repeated fields are allowed; all constraints must match.

Minimum array length: 1

merchant matches the assigned merchant name; description matches the transaction description. account_id and card_id must be accessible exact stable identities. Legacy account and card_name text conditions are read-only compatibility fields and are rejected on create. Combined account/card references require a provable relationship; incompatible or unverifiable pairs are rejected. transaction_type currently represents transfer only; it is not the public transaction resource's standard/transfer/split enum. Signed amount_cents uses integer cents without absolute values or currency conversion. greater_than means >=, less_than means <=, and between includes both bounds, minimum first. Signed amounts express inflow/outflow constraints; there is no separate direction field. Consumers must handle legacy text fields and should tolerate future supported condition variants.

Show child attributes

actions

object

required

Nonempty supported subset. Explicit nulls are rejected. Categories must be selectable and departments assignable; nonzero offsets cannot accompany Asset categories.

Show child attributes

apply_to_existing_transactions

boolean

default:true

Create-only switch requesting asynchronous historical application. False saves for future matching only. A saved response does not confirm execution completed.

Response

Saved rule; historical application may still be queued.

The complete saved company automation definition. IDs are stable opaque rule_ identifiers, including for historical rules. No public condition IDs, priority, enable state, or historical application status are exposed. The create-time application flag is not response state.

string

required

Pattern: ^rule_[A-Za-z0-9]+$

object

enum<string>

required

Available options:

rule

conditions

object[]

required

Flat AND conditions; repeated fields express multiple constraints. Text matches are case-insensitive.

Minimum array length: 1

merchant matches the assigned merchant name; description matches the transaction description. account_id and card_id match exact stable identities, never display names. Legacy account and card_name are compatibility text fields; duplicate names and contains can match multiple sources. Their original stored text is preserved. transaction_type currently represents transfer only; it is not the public transaction resource's standard/transfer/split enum. Signed amount_cents uses integer cents without absolute values or currency conversion. greater_than means >=, less_than means <=, and between includes both bounds, minimum first. Signed amounts express inflow/outflow constraints; there is no separate direction field. Consumers must handle legacy text fields and should tolerate future supported condition variants.

Show child attributes

actions

object

required

Only configured actions are present; absent actions are omitted rather than null. category_id and department_id preserve the saved reference's public ID, including legacy references that may no longer be selectable for a new rule. Reading a rule performs no actions. Accounting-date offsets are relative to the original transaction date on import, and do not apply historically. Nonzero offsets cannot be combined with Asset category actions.

Show child attributes

Create rule

curl --request POST \
  --url https://finta.lol/api/v1/rules \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "conditions": [
    {
      "field": "merchant",
      "operator": "contains",
      "value": "Cursor"
    }
  ],
  "actions": {
    "merchant": "Cursor AI"
  },
  "apply_to_existing_transactions": true
}
'

import requests

url = "https://finta.lol/api/v1/rules"

payload = {
    "conditions": [
        {
            "field": "merchant",
            "operator": "contains",
            "value": "Cursor"
        }
    ],
    "actions": { "merchant": "Cursor AI" },
    "apply_to_existing_transactions": True
}
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({
    conditions: [{field: 'merchant', operator: 'contains', value: 'Cursor'}],
    actions: {merchant: 'Cursor AI'},
    apply_to_existing_transactions: true
  })
};

fetch('https://finta.lol/api/v1/rules', 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://finta.lol/api/v1/rules",
  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([
    'conditions' => [
        [
                'field' => 'merchant',
                'operator' => 'contains',
                'value' => 'Cursor'
        ]
    ],
    'actions' => [
        'merchant' => 'Cursor AI'
    ],
    'apply_to_existing_transactions' => 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://finta.lol/api/v1/rules"

	payload := strings.NewReader("{\n  \"conditions\": [\n    {\n      \"field\": \"merchant\",\n      \"operator\": \"contains\",\n      \"value\": \"Cursor\"\n    }\n  ],\n  \"actions\": {\n    \"merchant\": \"Cursor AI\"\n  },\n  \"apply_to_existing_transactions\": true\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://finta.lol/api/v1/rules")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"conditions\": [\n    {\n      \"field\": \"merchant\",\n      \"operator\": \"contains\",\n      \"value\": \"Cursor\"\n    }\n  ],\n  \"actions\": {\n    \"merchant\": \"Cursor AI\"\n  },\n  \"apply_to_existing_transactions\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://finta.lol/api/v1/rules")

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  \"conditions\": [\n    {\n      \"field\": \"merchant\",\n      \"operator\": \"contains\",\n      \"value\": \"Cursor\"\n    }\n  ],\n  \"actions\": {\n    \"merchant\": \"Cursor AI\"\n  },\n  \"apply_to_existing_transactions\": true\n}"

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

{
  "id": "<string>",
  "object": "rule",
  "conditions": [
    {
      "field": "merchant",
      "operator": "equals",
      "value": "<string>"
    }
  ],
  "actions": {
    "merchant": "<string>",
    "category_id": "<string>",
    "department_id": "<string>",
    "spread": 19,
    "accounting_date_offset_months": 0
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "<string>",
    "doc_url": "https://finta.lol/docs/api-reference/errors#invalid_api_key",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "<string>",
    "doc_url": "https://finta.lol/docs/api-reference/errors#invalid_api_key",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "<string>",
    "doc_url": "https://finta.lol/docs/api-reference/errors#invalid_api_key",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "<string>",
    "doc_url": "https://finta.lol/docs/api-reference/errors#invalid_api_key",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "<string>",
    "doc_url": "https://finta.lol/docs/api-reference/errors#invalid_api_key",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "<string>",
    "doc_url": "https://finta.lol/docs/api-reference/errors#invalid_api_key",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "<string>",
    "doc_url": "https://finta.lol/docs/api-reference/errors#invalid_api_key",
    "param": "<string>"
  }
}

API Reference

Company

Team

Categories

Rules

Departments

Integrations

Aggregations

Transactions

Journal Entries

Parties

Reports

Create rule

Authorizations

Body

Response