Rules

Update rule

Updates future matching only; never runs history or repairs past transactions. Requires Accounting setup: Manage and API access: Manage; Transactions: Manage is not required. Supplied action fields merge into existing actions. Omitted fields stay unchanged and null removes an action from the rule, not from past transactions. Supplied conditions replace the entire flat AND list; omission preserves it, including legacy account/card_name text predicates. Legacy fields cannot be submitted as new conditions. Exact identity references and inclusive signed amount boundaries retain their Create semantics. The complete resulting definition is validated atomically and must contain at least one condition and action, including the Asset/nonzero-offset restriction. Explicitly supplied category/department IDs require current selectability/assignability, even if they equal the saved value. Omitted actions retain their existing saved associations within the authorized company/system scope, including system departments available through the company department collection, even if no longer selectable/assignable for a new rule. This does not exempt preserved actions from whole-definition validation. Invalid updates leave the rule and queued history unchanged. Rejects empty bodies, only empty actions, unknown fields, and apply_to_existing_transactions. Valid no-ops return 200 without changing the definition or cancelling queued history. A real edit cancels pending API-created historical work. Already-running history returns retryable 503 rule_busy without changes; retry with exponential backoff. Legacy unassociated UI jobs do not gain these cancellation guarantees. Reads and merges serialize against other definition writes. Exact normalized duplicates excluding this rule return 409 rule_already_exists with the accessible existing rule ID in the message; unavailable duplicate IDs return 503 rules_not_ready. Unknown, foreign-company, global, internal/system, owner-specific and mixed-owner rules all return the same 404 resource_missing. Malformed rule_ IDs return 400 invalid_request. Unsupported stored definitions return 503 rules_not_ready. No new migration or public job API is introduced.

PATCH

rules

{id}

Update rule

curl --request PATCH \
  --url https://app.finta.com/api/v1/rules/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "actions": {
    "merchant": "Cursor",
    "department_id": null
  }
}
'

import requests

url = "https://app.finta.com/api/v1/rules/{id}"

payload = { "actions": {
        "merchant": "Cursor",
        "department_id": None
    } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({actions: {merchant: 'Cursor', department_id: null}})
};

fetch('https://app.finta.com/api/v1/rules/{id}', 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/rules/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'actions' => [
        'merchant' => 'Cursor',
        'department_id' => null
    ]
  ]),
  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/rules/{id}"

	payload := strings.NewReader("{\n  \"actions\": {\n    \"merchant\": \"Cursor\",\n    \"department_id\": null\n  }\n}")

	req, _ := http.NewRequest("PATCH", 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.patch("https://app.finta.com/api/v1/rules/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"actions\": {\n    \"merchant\": \"Cursor\",\n    \"department_id\": null\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.finta.com/api/v1/rules/{id}")

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

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"actions\": {\n    \"merchant\": \"Cursor\",\n    \"department_id\": null\n  }\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
  }
}

Authorizations

Authorization

string

header

required

API key prefixed with finta_

Path Parameters

string

required

Public rule_ ID with a nonempty alphanumeric suffix of any length.

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

Body

application/json

Option 1
Option 2

Partial update. Conditions replace the list; actions merge by key with null for removal. The resulting definition must remain nonempty and valid. An actions-only empty object is rejected.

conditions

object[]

required

Replaces all conditions. Omission preserves existing conditions, including legacy text predicates.

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

Omitted action keys stay unchanged. Null removes a configured action. At least one action must remain after merging.

Show child attributes

Response

The complete saved rule, with removed actions omitted.

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

Update rule

curl --request PATCH \
  --url https://app.finta.com/api/v1/rules/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "actions": {
    "merchant": "Cursor",
    "department_id": null
  }
}
'

import requests

url = "https://app.finta.com/api/v1/rules/{id}"

payload = { "actions": {
        "merchant": "Cursor",
        "department_id": None
    } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({actions: {merchant: 'Cursor', department_id: null}})
};

fetch('https://app.finta.com/api/v1/rules/{id}', 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/rules/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'actions' => [
        'merchant' => 'Cursor',
        'department_id' => null
    ]
  ]),
  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/rules/{id}"

	payload := strings.NewReader("{\n  \"actions\": {\n    \"merchant\": \"Cursor\",\n    \"department_id\": null\n  }\n}")

	req, _ := http.NewRequest("PATCH", 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.patch("https://app.finta.com/api/v1/rules/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"actions\": {\n    \"merchant\": \"Cursor\",\n    \"department_id\": null\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.finta.com/api/v1/rules/{id}")

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

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"actions\": {\n    \"merchant\": \"Cursor\",\n    \"department_id\": null\n  }\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
  }
}

API Reference

Company

Team

Categories

Rules

Departments

Integrations

Aggregations

Transactions

Journal Entries

Parties

Reports

Update rule

Authorizations

Path Parameters

Body

Response