Transactions

Submit transaction upload

Adds bank or credit card transactions, parsed by the caller from a file, to one account. Requires API access and Transactions: Manage.

The first call opens a hidden draft; pass its id as upload_id on later calls. Send the rows in chunks of up to 500 (2,000 per upload), including rows you leave out with exclude. Each call returns validation for every row received so far. commit: true imports the upload once ready_to_commit is true, waiting up to about 20 seconds for categorization; otherwise nothing is imported. Exact copies of existing transactions are skipped. Posting only upload_id returns the current state. Only the person who started an upload can continue it.

POST

transaction_uploads

curl --request POST \
  --url https://app.finta.com/api/v1/transaction_uploads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "account_id": "acct_2Fk8Qz1LmN0pRs",
  "file_totals": {
    "row_count": 3,
    "net_amount_cents": -6499
  },
  "columns": [
    "row",
    "date",
    "description",
    "amount"
  ],
  "rows": [
    [
      1,
      "08/13/2026",
      "BLUE BOTTLE COFFEE",
      "-45.00"
    ],
    [
      2,
      "08/14/2026",
      "FIGMA",
      "-19.99"
    ],
    [
      3,
      "08/20/2026",
      "STRIPE TRANSFER",
      "0.00"
    ]
  ],
  "exclude": [
    {
      "row": 3,
      "reason": "not_a_transaction"
    }
  ],
  "commit": true
}
'

import requests

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

payload = {
    "account_id": "acct_2Fk8Qz1LmN0pRs",
    "file_totals": {
        "row_count": 3,
        "net_amount_cents": -6499
    },
    "columns": ["row", "date", "description", "amount"],
    "rows": [[1, "08/13/2026", "BLUE BOTTLE COFFEE", "-45.00"], [2, "08/14/2026", "FIGMA", "-19.99"], [3, "08/20/2026", "STRIPE TRANSFER", "0.00"]],
    "exclude": [
        {
            "row": 3,
            "reason": "not_a_transaction"
        }
    ],
    "commit": 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({
    account_id: 'acct_2Fk8Qz1LmN0pRs',
    file_totals: {row_count: 3, net_amount_cents: -6499},
    columns: ['row', 'date', 'description', 'amount'],
    rows: [
      [1, '08/13/2026', 'BLUE BOTTLE COFFEE', '-45.00'],
      [2, '08/14/2026', 'FIGMA', '-19.99'],
      [3, '08/20/2026', 'STRIPE TRANSFER', '0.00']
    ],
    exclude: [{row: 3, reason: 'not_a_transaction'}],
    commit: true
  })
};

fetch('https://app.finta.com/api/v1/transaction_uploads', 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/transaction_uploads",
  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([
    'account_id' => 'acct_2Fk8Qz1LmN0pRs',
    'file_totals' => [
        'row_count' => 3,
        'net_amount_cents' => -6499
    ],
    'columns' => [
        'row',
        'date',
        'description',
        'amount'
    ],
    'rows' => [
        [
                1,
                '08/13/2026',
                'BLUE BOTTLE COFFEE',
                '-45.00'
        ],
        [
                2,
                '08/14/2026',
                'FIGMA',
                '-19.99'
        ],
        [
                3,
                '08/20/2026',
                'STRIPE TRANSFER',
                '0.00'
        ]
    ],
    'exclude' => [
        [
                'row' => 3,
                'reason' => 'not_a_transaction'
        ]
    ],
    'commit' => 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://app.finta.com/api/v1/transaction_uploads"

	payload := strings.NewReader("{\n  \"account_id\": \"acct_2Fk8Qz1LmN0pRs\",\n  \"file_totals\": {\n    \"row_count\": 3,\n    \"net_amount_cents\": -6499\n  },\n  \"columns\": [\n    \"row\",\n    \"date\",\n    \"description\",\n    \"amount\"\n  ],\n  \"rows\": [\n    [\n      1,\n      \"08/13/2026\",\n      \"BLUE BOTTLE COFFEE\",\n      \"-45.00\"\n    ],\n    [\n      2,\n      \"08/14/2026\",\n      \"FIGMA\",\n      \"-19.99\"\n    ],\n    [\n      3,\n      \"08/20/2026\",\n      \"STRIPE TRANSFER\",\n      \"0.00\"\n    ]\n  ],\n  \"exclude\": [\n    {\n      \"row\": 3,\n      \"reason\": \"not_a_transaction\"\n    }\n  ],\n  \"commit\": 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://app.finta.com/api/v1/transaction_uploads")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"account_id\": \"acct_2Fk8Qz1LmN0pRs\",\n  \"file_totals\": {\n    \"row_count\": 3,\n    \"net_amount_cents\": -6499\n  },\n  \"columns\": [\n    \"row\",\n    \"date\",\n    \"description\",\n    \"amount\"\n  ],\n  \"rows\": [\n    [\n      1,\n      \"08/13/2026\",\n      \"BLUE BOTTLE COFFEE\",\n      \"-45.00\"\n    ],\n    [\n      2,\n      \"08/14/2026\",\n      \"FIGMA\",\n      \"-19.99\"\n    ],\n    [\n      3,\n      \"08/20/2026\",\n      \"STRIPE TRANSFER\",\n      \"0.00\"\n    ]\n  ],\n  \"exclude\": [\n    {\n      \"row\": 3,\n      \"reason\": \"not_a_transaction\"\n    }\n  ],\n  \"commit\": true\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"account_id\": \"acct_2Fk8Qz1LmN0pRs\",\n  \"file_totals\": {\n    \"row_count\": 3,\n    \"net_amount_cents\": -6499\n  },\n  \"columns\": [\n    \"row\",\n    \"date\",\n    \"description\",\n    \"amount\"\n  ],\n  \"rows\": [\n    [\n      1,\n      \"08/13/2026\",\n      \"BLUE BOTTLE COFFEE\",\n      \"-45.00\"\n    ],\n    [\n      2,\n      \"08/14/2026\",\n      \"FIGMA\",\n      \"-19.99\"\n    ],\n    [\n      3,\n      \"08/20/2026\",\n      \"STRIPE TRANSFER\",\n      \"0.00\"\n    ]\n  ],\n  \"exclude\": [\n    {\n      \"row\": 3,\n      \"reason\": \"not_a_transaction\"\n    }\n  ],\n  \"commit\": true\n}"

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

{
  "id": "<string>",
  "object": "transaction_upload",
  "account_id": "<string>",
  "status": "draft",
  "rows_expected": 123,
  "rows_received": 123,
  "rows_remaining": 123,
  "totals_match": true,
  "summary": {
    "start_date": "2023-12-25",
    "end_date": "2023-12-25",
    "rows_to_upload": 123,
    "excluded": 123,
    "skipped_exact_duplicates": 123,
    "money_in_cents": 123,
    "money_out_cents": 123
  },
  "errors": [
    {
      "code": "<string>",
      "rows": [
        123
      ],
      "message": "<string>",
      "suggestion": "<string>",
      "blocking": true,
      "acknowledged": true
    }
  ],
  "warnings": [
    {
      "code": "<string>",
      "rows": [
        123
      ],
      "message": "<string>",
      "suggestion": "<string>",
      "blocking": true,
      "acknowledged": true
    }
  ],
  "open_questions": [
    {
      "code": "date_format_ambiguous",
      "parameter": "date_format",
      "question": "<string>",
      "suggestion": "<string>",
      "default": "<string>",
      "why_default": "<string>"
    }
  ],
  "ready_to_commit": true,
  "next_step": "<string>",
  "result": {
    "uploaded": 123,
    "excluded": [
      {
        "row": 123,
        "reason": "<string>",
        "note": "<string>"
      }
    ],
    "skipped_exact_duplicates": [
      123
    ],
    "auto_categorized": 123,
    "url": "<string>",
    "failure_message": "<string>"
  }
}

Authorizations

Authorization

string

header

required

API key prefixed with finta_

Body

application/json

account_id

string

An acct_ ID from GET or POST /accounts. Required on the first call.

upload_id

string | null

The id returned by the first call.

file_totals

object

Computed from the file itself. Required on the first call; cannot change.

Show child attributes

columns

enum<string>[]

The order of values in each row. Required with the first rows.

Available options:

row,

date,

description,

amount

rows

((string | number | null)[])[]

row is the 1-based row number; resending it replaces the row. date is as the file writes it, so Finta can tell month/day from day/month. description is at most 40 characters. amount is a signed decimal such as -45.00.

Maximum array length: 500

date_format

enum<string>

Order of numeric dates, when an open question asks.

Available options:

MDY,

DMY

sign_convention

enum<string>

How the file signs money out. Defaults to negative_is_money_out.

Available options:

negative_is_money_out,

positive_is_money_out

exclude

object[]

Rows to leave out. Adds to earlier exclusions.

Show child attributes

acknowledged_warnings

enum<string>[]

Blocking warnings you accept, covering the rows they list now.

Available options:

possible_duplicate,

overlaps_existing_data,

possible_investment_trade,

possible_reversal_pair

allow_synced_account

boolean

Upload to an account that syncs from an integration. Confirm with the user first.

commit

boolean

Import the upload if nothing blocks it.

Response

The upload after this call.

string

required

Pass as upload_id on later calls.

object

enum<string>

required

Available options:

transaction_upload

account_id

string

required

status

enum<string>

required

Available options:

draft,

importing,

imported,

failed

rows_expected

integer

required

rows_received

integer

required

rows_remaining

integer

required

totals_match

boolean | null

required

Null until every row is received and readable.

summary

object

required

What a commit would import, or did.

Show child attributes

errors

object[]

required

Fix by resending or excluding rows; no override.

Show child attributes

warnings

object[]

required

Show child attributes

open_questions

object[]

required

Show child attributes

ready_to_commit

boolean

required

next_step

string

required

result

object | null

required

Null while the upload is a draft.

Show child attributes

Submit transaction upload

curl --request POST \
  --url https://app.finta.com/api/v1/transaction_uploads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "account_id": "acct_2Fk8Qz1LmN0pRs",
  "file_totals": {
    "row_count": 3,
    "net_amount_cents": -6499
  },
  "columns": [
    "row",
    "date",
    "description",
    "amount"
  ],
  "rows": [
    [
      1,
      "08/13/2026",
      "BLUE BOTTLE COFFEE",
      "-45.00"
    ],
    [
      2,
      "08/14/2026",
      "FIGMA",
      "-19.99"
    ],
    [
      3,
      "08/20/2026",
      "STRIPE TRANSFER",
      "0.00"
    ]
  ],
  "exclude": [
    {
      "row": 3,
      "reason": "not_a_transaction"
    }
  ],
  "commit": true
}
'

import requests

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

payload = {
    "account_id": "acct_2Fk8Qz1LmN0pRs",
    "file_totals": {
        "row_count": 3,
        "net_amount_cents": -6499
    },
    "columns": ["row", "date", "description", "amount"],
    "rows": [[1, "08/13/2026", "BLUE BOTTLE COFFEE", "-45.00"], [2, "08/14/2026", "FIGMA", "-19.99"], [3, "08/20/2026", "STRIPE TRANSFER", "0.00"]],
    "exclude": [
        {
            "row": 3,
            "reason": "not_a_transaction"
        }
    ],
    "commit": 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({
    account_id: 'acct_2Fk8Qz1LmN0pRs',
    file_totals: {row_count: 3, net_amount_cents: -6499},
    columns: ['row', 'date', 'description', 'amount'],
    rows: [
      [1, '08/13/2026', 'BLUE BOTTLE COFFEE', '-45.00'],
      [2, '08/14/2026', 'FIGMA', '-19.99'],
      [3, '08/20/2026', 'STRIPE TRANSFER', '0.00']
    ],
    exclude: [{row: 3, reason: 'not_a_transaction'}],
    commit: true
  })
};

fetch('https://app.finta.com/api/v1/transaction_uploads', 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/transaction_uploads",
  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([
    'account_id' => 'acct_2Fk8Qz1LmN0pRs',
    'file_totals' => [
        'row_count' => 3,
        'net_amount_cents' => -6499
    ],
    'columns' => [
        'row',
        'date',
        'description',
        'amount'
    ],
    'rows' => [
        [
                1,
                '08/13/2026',
                'BLUE BOTTLE COFFEE',
                '-45.00'
        ],
        [
                2,
                '08/14/2026',
                'FIGMA',
                '-19.99'
        ],
        [
                3,
                '08/20/2026',
                'STRIPE TRANSFER',
                '0.00'
        ]
    ],
    'exclude' => [
        [
                'row' => 3,
                'reason' => 'not_a_transaction'
        ]
    ],
    'commit' => 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://app.finta.com/api/v1/transaction_uploads"

	payload := strings.NewReader("{\n  \"account_id\": \"acct_2Fk8Qz1LmN0pRs\",\n  \"file_totals\": {\n    \"row_count\": 3,\n    \"net_amount_cents\": -6499\n  },\n  \"columns\": [\n    \"row\",\n    \"date\",\n    \"description\",\n    \"amount\"\n  ],\n  \"rows\": [\n    [\n      1,\n      \"08/13/2026\",\n      \"BLUE BOTTLE COFFEE\",\n      \"-45.00\"\n    ],\n    [\n      2,\n      \"08/14/2026\",\n      \"FIGMA\",\n      \"-19.99\"\n    ],\n    [\n      3,\n      \"08/20/2026\",\n      \"STRIPE TRANSFER\",\n      \"0.00\"\n    ]\n  ],\n  \"exclude\": [\n    {\n      \"row\": 3,\n      \"reason\": \"not_a_transaction\"\n    }\n  ],\n  \"commit\": 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://app.finta.com/api/v1/transaction_uploads")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"account_id\": \"acct_2Fk8Qz1LmN0pRs\",\n  \"file_totals\": {\n    \"row_count\": 3,\n    \"net_amount_cents\": -6499\n  },\n  \"columns\": [\n    \"row\",\n    \"date\",\n    \"description\",\n    \"amount\"\n  ],\n  \"rows\": [\n    [\n      1,\n      \"08/13/2026\",\n      \"BLUE BOTTLE COFFEE\",\n      \"-45.00\"\n    ],\n    [\n      2,\n      \"08/14/2026\",\n      \"FIGMA\",\n      \"-19.99\"\n    ],\n    [\n      3,\n      \"08/20/2026\",\n      \"STRIPE TRANSFER\",\n      \"0.00\"\n    ]\n  ],\n  \"exclude\": [\n    {\n      \"row\": 3,\n      \"reason\": \"not_a_transaction\"\n    }\n  ],\n  \"commit\": true\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"account_id\": \"acct_2Fk8Qz1LmN0pRs\",\n  \"file_totals\": {\n    \"row_count\": 3,\n    \"net_amount_cents\": -6499\n  },\n  \"columns\": [\n    \"row\",\n    \"date\",\n    \"description\",\n    \"amount\"\n  ],\n  \"rows\": [\n    [\n      1,\n      \"08/13/2026\",\n      \"BLUE BOTTLE COFFEE\",\n      \"-45.00\"\n    ],\n    [\n      2,\n      \"08/14/2026\",\n      \"FIGMA\",\n      \"-19.99\"\n    ],\n    [\n      3,\n      \"08/20/2026\",\n      \"STRIPE TRANSFER\",\n      \"0.00\"\n    ]\n  ],\n  \"exclude\": [\n    {\n      \"row\": 3,\n      \"reason\": \"not_a_transaction\"\n    }\n  ],\n  \"commit\": true\n}"

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

{
  "id": "<string>",
  "object": "transaction_upload",
  "account_id": "<string>",
  "status": "draft",
  "rows_expected": 123,
  "rows_received": 123,
  "rows_remaining": 123,
  "totals_match": true,
  "summary": {
    "start_date": "2023-12-25",
    "end_date": "2023-12-25",
    "rows_to_upload": 123,
    "excluded": 123,
    "skipped_exact_duplicates": 123,
    "money_in_cents": 123,
    "money_out_cents": 123
  },
  "errors": [
    {
      "code": "<string>",
      "rows": [
        123
      ],
      "message": "<string>",
      "suggestion": "<string>",
      "blocking": true,
      "acknowledged": true
    }
  ],
  "warnings": [
    {
      "code": "<string>",
      "rows": [
        123
      ],
      "message": "<string>",
      "suggestion": "<string>",
      "blocking": true,
      "acknowledged": true
    }
  ],
  "open_questions": [
    {
      "code": "date_format_ambiguous",
      "parameter": "date_format",
      "question": "<string>",
      "suggestion": "<string>",
      "default": "<string>",
      "why_default": "<string>"
    }
  ],
  "ready_to_commit": true,
  "next_step": "<string>",
  "result": {
    "uploaded": 123,
    "excluded": [
      {
        "row": 123,
        "reason": "<string>",
        "note": "<string>"
      }
    ],
    "skipped_exact_duplicates": [
      123
    ],
    "auto_categorized": 123,
    "url": "<string>",
    "failure_message": "<string>"
  }
}

API Reference

Company

Team

Categories

Rules

Departments

Integrations

Aggregations

Transactions

Journal Entries

Parties

Reports

Submit transaction upload

Authorizations

Body

Response