Aggregations

Retrieve total

Calculates one signed total for the requested category and its descendants.

Check the category’s point_in_time field from GET /categories before choosing date parameters. Periodic categories (point_in_time: false), such as income-statement and cash-flow categories, require start_date and end_date. Point-in-time categories (point_in_time: true), such as balance-sheet categories, require date and reject start_date and end_date.

Existing integrations may continue using the deprecated month contract. Periodic categories accept start_month and end_month; point-in-time categories accept only end_month. Month parameters use YYYY-MM and cannot be combined with full-date parameters. Responses include both representations so clients can migrate independently.

Dates use YYYY-MM-DD, but totals have monthly granularity and ignore the day (DD). For example, 2026-02-03 and 2026-02-28 select the same February total. Periodic totals include both selected months. Point-in-time totals are cumulative through the selected month. Assets use debit minus credit. All other categories use credit minus debit.

merchant is an exact, case-sensitive match. A blank value means all merchants.

refreshed_at is the Unix timestamp of the most recent change to data included in the result. It is null when no data matches. Newly imported activity may not appear immediately.

The API rejects period and department_id. It ignores other unknown query parameters.

GET

aggregations

total

Retrieve total

curl --request GET \
  --url https://app.finta.com/api/v1/aggregations/total \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.finta.com/api/v1/aggregations/total', 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/aggregations/total",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "object": "total",
  "category_id": "cat_o5p6q7r8s9t0u1",
  "merchant": "AWS",
  "start_month": "2026-01",
  "end_month": "2026-03",
  "start_date": "2026-01-15",
  "end_date": "2026-03-20",
  "date": null,
  "point_in_time": false,
  "total_cents": -182340,
  "currency": "USD",
  "debit_cents": 182340,
  "credit_cents": 0,
  "refreshed_at": 1786992120
}

Authorizations

Authorization

string

header

required

API key prefixed with finta_

Query Parameters

category_id

string

required

A cat_ ID returned by GET /categories.

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

start_month

string

Deprecated first month for a periodic category, as YYYY-MM. Use with end_month, not with full-date parameters.

Pattern: ^\d{4}-(0[1-9]|1[0-2])$

end_month

string

Deprecated last month for a periodic category or cutoff month for a point-in-time category, as YYYY-MM. Do not combine with full-date parameters.

Pattern: ^\d{4}-(0[1-9]|1[0-2])$

start_date

string<date>

First selected month for a periodic category, as YYYY-MM-DD. Required when point_in_time is false and rejected when it is true. The day is ignored.

end_date

string<date>

Last selected month for a periodic category, as YYYY-MM-DD. Required when point_in_time is false and rejected when it is true. The day is ignored.

date

string<date>

Selected month for a point-in-time category, as YYYY-MM-DD. Required when point_in_time is true and rejected when it is false. The day is ignored.

merchant

string

Exact, case-sensitive merchant or counterparty name. Blank means all merchants.

Response

The requested total

object

enum<string>

required

Available options:

total

category_id

string

required

The requested public category ID.

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

Example:

"cat_o5p6q7r8s9t0u1"

merchant

string | null

required

The exact merchant filter, or null when no merchant filter was applied.

Example:

"AWS"

start_month

string | null

required

The selected first month for a periodic total. Derived from start_date for full-date requests and null for point-in-time totals.

Pattern: ^\d{4}-(0[1-9]|1[0-2])$

Example:

"2026-01"

end_month

string

required

The selected last or cutoff month. Derived from end_date or date for full-date requests.

Pattern: ^\d{4}-(0[1-9]|1[0-2])$

Example:

"2026-03"

start_date

string<date> | null

required

The requested periodic start date. For a legacy month request, this is the first day of start_month. Null when point_in_time is true.

Example:

"2026-01-15"

end_date

string<date> | null

required

The requested periodic end date. For a legacy month request, this is the last day of end_month. Null when point_in_time is true.

Example:

"2026-03-20"

date

string<date> | null

required

The requested point-in-time date. For a legacy month request, this is the last day of end_month. Null when point_in_time is false.

Example:

null

point_in_time

boolean

required

When true, request the total with date. When false, request it with start_date and end_date.

Example:

false

total_cents

integer

required

Signed total in cents. Assets use debit minus credit; all other categories use credit minus debit.

Example:

-182340

currency

enum<string>

required

ISO 4217 currency code for the total.

Available options:

USD

Example:

"USD"

debit_cents

integer

required

Contributing debit amount in cents before sign calculation.

Example:

182340

credit_cents

integer

required

Contributing credit amount in cents before sign calculation.

Example:

0

refreshed_at

integer | null

required

Unix timestamp of the most recent change to data included in the result. Null when no data matches.

Example:

1786992120

Retrieve total

curl --request GET \
  --url https://app.finta.com/api/v1/aggregations/total \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.finta.com/api/v1/aggregations/total', 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/aggregations/total",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "object": "total",
  "category_id": "cat_o5p6q7r8s9t0u1",
  "merchant": "AWS",
  "start_month": "2026-01",
  "end_month": "2026-03",
  "start_date": "2026-01-15",
  "end_date": "2026-03-20",
  "date": null,
  "point_in_time": false,
  "total_cents": -182340,
  "currency": "USD",
  "debit_cents": 182340,
  "credit_cents": 0,
  "refreshed_at": 1786992120
}

API Reference

Company

Team

Categories

Departments

Integrations

Aggregations

Transactions

Journal Entries

Parties

Reports

Retrieve total

Authorizations

Query Parameters

Response