Transactions

Bulk update transactions

Accepts one asynchronous all-or-nothing operation for at most 5,000 transactions. Supply exactly one non-empty selector and a non-empty updates object. Filters combine with AND and select pre-update values. Split parents and all split-derived records are excluded from filters; explicit split IDs fail the job. Transfer eligibility follows existing per-field rules. No matches succeeds with zero updates. Targets freeze at processing start; relevant later edits fail the job. accounting_shift moves each effective accounting date by calendar months, clamping once to the destination month. Omission leaves a field unchanged; null clears department/spread or restores the original accounting date. Requires current API access: Manage and Transactions: Manage, an active actor and company membership, and an eligible company subscription/lifecycle. Those permissions are checked again during execution. No identities are created by submission.

Idempotency keys are scoped to company and submitting user. Identical normalized bodies replay the original queued 202 response; a changed body returns 409. Object key order is ignored; array order is preserved; null and omission differ. Key strings are case-sensitive and are not trimmed or normalized. Whitespace-only keys are rejected. The operation, company and actor define the key scope; a different API key for the same actor/company shares that scope. Keys and results remain for 30 days after terminal completion; active jobs do not expire. After expiry, a new submission can apply another shift. Retrieve the known job to learn its current outcome. The 202 body always contains the stored queued acceptance (matched_count null, updated_count 0, empty errors), even if execution already completed before the response or replay. No response does not imply rejection: retry with the same key and identical body while retained. After expiry the same key creates new work and can apply a relative shift again.

The only public filters are merchant, category_id, account_id, card_id, start_date, end_date, status, transaction_type and categorized. Unknown fields, empty selectors, invalid IDs/dates/enums, duplicate IDs, malformed types, inverted date ranges, and simultaneous selectors are rejected with 400 invalid_request. Explicit selection permits 1–5,000 unique txn_ IDs; 5,001 are rejected before acceptance. Filter selection is asynchronous, unpaginated and fails atomically above 5,000 matches. Unknown or inaccessible account/card references receive the same 404 resource_missing; an incompatible known account/card pair is 400 invalid_request. Missing/foreign transaction IDs and business eligibility errors are job failures discovered during execution.

Success and replay consume API requests, as does polling. Existing per-minute and monthly limits apply. On 429 rate_limit_exceeded, wait Retry-After then retry the identical body/key with backoff. On monthly_limit_exceeded, stop short-term retries; no Retry-After is sent. Fix 400, 401 or 403 before retrying. A 409 idempotency_key_conflict means the key already identifies a different body; poll the original job rather than changing the key to guess whether work ran.

POST

transactions

bulk

update

Bulk update transactions

curl --request POST \
  --url https://finta.lol/api/v1/transactions/bulk/update \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "filters": {
    "merchant": "Cursor"
  },
  "updates": {
    "merchant": "Cursor AI"
  }
}
'

import requests

url = "https://finta.lol/api/v1/transactions/bulk/update"

payload = {
    "filters": { "merchant": "Cursor" },
    "updates": { "merchant": "Cursor AI" }
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({filters: {merchant: 'Cursor'}, updates: {merchant: 'Cursor AI'}})
};

fetch('https://finta.lol/api/v1/transactions/bulk/update', 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/transactions/bulk/update",
  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([
    'filters' => [
        'merchant' => 'Cursor'
    ],
    'updates' => [
        'merchant' => 'Cursor AI'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$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/transactions/bulk/update"

	payload := strings.NewReader("{\n  \"filters\": {\n    \"merchant\": \"Cursor\"\n  },\n  \"updates\": {\n    \"merchant\": \"Cursor AI\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	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/transactions/bulk/update")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filters\": {\n    \"merchant\": \"Cursor\"\n  },\n  \"updates\": {\n    \"merchant\": \"Cursor AI\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://finta.lol/api/v1/transactions/bulk/update")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"filters\": {\n    \"merchant\": \"Cursor\"\n  },\n  \"updates\": {\n    \"merchant\": \"Cursor AI\"\n  }\n}"

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

{
  "id": "<string>",
  "object": "job",
  "type": "bulk_update_transactions",
  "status": "queued",
  "matched_count": 1,
  "updated_count": 1,
  "errors": {
    "object": "list",
    "url": "<string>",
    "has_more": true,
    "next_cursor": "<string>",
    "data": [
      {
        "transaction_id": "<string>",
        "code": "<string>",
        "param": "<string>",
        "message": "<string>"
      }
    ]
  }
}

Authorizations

Authorization

string

header

required

API key prefixed with finta_

Headers

Idempotency-Key

string

required

Nonblank string of 1–255 characters. Whitespace-only and oversized keys return 400 invalid_request with param Idempotency-Key.

Required string length: 1 - 255

Pattern: \S

Body

application/json

Option 1
Option 2

Exactly one non-empty selector and a non-empty updates object; no unknown top-level keys.

filters

object

required

Exactly these nine filters are public; combine supplied fields with AND against pre-update values. Selects all matches without pagination. start_date and end_date are inclusive and end_date must not precede start_date. Explicit null is invalid for filters.

Show child attributes

updates

object

required

Omitted fields are unchanged. Null clears department/spread or restores the original date. merchant and category_id cannot be null. accounting_date and accounting_shift cannot coexist, including a null date. Shared eligibility restrictions apply atomically at execution.

Show child attributes

Response

Original queued acceptance, including on replay after success or failure. Retrieve Location for the current outcome.

string

required

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

object

enum<string>

required

Available options:

job

type

enum<string>

required

Available options:

bulk_update_transactions

status

enum<string>

required

queued awaits execution; processing has a frozen selection; success has committed edits and durable reporting refresh intent; failed has no committed edits. Reporting refresh can finish after success.

Available options:

queued,

processing,

success,

failed

matched_count

integer | null

required

Null until selection succeeds, then the number of frozen targets. A successful empty selection is zero.

Required range: x >= 0

updated_count

integer

required

Distinct transactions actually changed, including assignment provenance, counted once each. Failed jobs always report zero.

Required range: x >= 0

errors

object

required

Show child attributes

Bulk update transactions

curl --request POST \
  --url https://finta.lol/api/v1/transactions/bulk/update \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "filters": {
    "merchant": "Cursor"
  },
  "updates": {
    "merchant": "Cursor AI"
  }
}
'

import requests

url = "https://finta.lol/api/v1/transactions/bulk/update"

payload = {
    "filters": { "merchant": "Cursor" },
    "updates": { "merchant": "Cursor AI" }
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({filters: {merchant: 'Cursor'}, updates: {merchant: 'Cursor AI'}})
};

fetch('https://finta.lol/api/v1/transactions/bulk/update', 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/transactions/bulk/update",
  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([
    'filters' => [
        'merchant' => 'Cursor'
    ],
    'updates' => [
        'merchant' => 'Cursor AI'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$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/transactions/bulk/update"

	payload := strings.NewReader("{\n  \"filters\": {\n    \"merchant\": \"Cursor\"\n  },\n  \"updates\": {\n    \"merchant\": \"Cursor AI\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	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/transactions/bulk/update")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filters\": {\n    \"merchant\": \"Cursor\"\n  },\n  \"updates\": {\n    \"merchant\": \"Cursor AI\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://finta.lol/api/v1/transactions/bulk/update")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"filters\": {\n    \"merchant\": \"Cursor\"\n  },\n  \"updates\": {\n    \"merchant\": \"Cursor AI\"\n  }\n}"

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

{
  "id": "<string>",
  "object": "job",
  "type": "bulk_update_transactions",
  "status": "queued",
  "matched_count": 1,
  "updated_count": 1,
  "errors": {
    "object": "list",
    "url": "<string>",
    "has_more": true,
    "next_cursor": "<string>",
    "data": [
      {
        "transaction_id": "<string>",
        "code": "<string>",
        "param": "<string>",
        "message": "<string>"
      }
    ]
  }
}

API Reference

Company

Team

Categories

Rules

Departments

Integrations

Aggregations

Transactions

Journal Entries

Parties

Reports

Bulk update transactions

Authorizations

Headers

Body

Response