Taxes

Create income upload

Records an income tax return the company already filed outside Finta, with its PDF. This is the Taxes page’s “already filed” upload: it runs the same code, with the same results. Requires API access: Manage and Taxes: Manage.

Upload the PDF first with Create file or Create file upload, then pass its file_id. The PDF is checked before anything is recorded: a Delaware franchise tax report (a PDF whose text contains “Annual Franchise Tax Report”) is refused with wrong_document_type; upload it with Create franchise upload instead.

On success, the year’s income record is created or overwritten: it is marked filed now (filed_at is the upload time, not the date the return was filed), filed_elsewhere is true, and the PDF becomes its filed_return document. Its jurisdictions are US plus states_filed. The same request also sets up that year’s Delaware franchise record, marked filed only if Finta’s Delaware status check already shows the report filed; attach the Delaware report with Create franchise upload. For a company with no records for that year, upload the return first, then the Delaware report.

Only last year’s return or the year before’s can be uploaded, as on the Taxes page. Any other tax_year is refused rather than changed.

POST

taxes

income_uploads

Create income upload

curl --request POST \
  --url https://app.finta.com/api/v1/taxes/income_uploads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tax_year": 2025,
  "tax_firm": "Fondo",
  "states_filed": [
    "CA"
  ],
  "file_id": "file_8dJ2kq9XbT4mNa"
}
'

import requests

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

payload = {
    "tax_year": 2025,
    "tax_firm": "Fondo",
    "states_filed": ["CA"],
    "file_id": "file_8dJ2kq9XbT4mNa"
}
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({
    tax_year: 2025,
    tax_firm: 'Fondo',
    states_filed: ['CA'],
    file_id: 'file_8dJ2kq9XbT4mNa'
  })
};

fetch('https://app.finta.com/api/v1/taxes/income_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/taxes/income_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([
    'tax_year' => 2025,
    'tax_firm' => 'Fondo',
    'states_filed' => [
        'CA'
    ],
    'file_id' => 'file_8dJ2kq9XbT4mNa'
  ]),
  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/taxes/income_uploads"

	payload := strings.NewReader("{\n  \"tax_year\": 2025,\n  \"tax_firm\": \"Fondo\",\n  \"states_filed\": [\n    \"CA\"\n  ],\n  \"file_id\": \"file_8dJ2kq9XbT4mNa\"\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/taxes/income_uploads")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"tax_year\": 2025,\n  \"tax_firm\": \"Fondo\",\n  \"states_filed\": [\n    \"CA\"\n  ],\n  \"file_id\": \"file_8dJ2kq9XbT4mNa\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.finta.com/api/v1/taxes/income_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  \"tax_year\": 2025,\n  \"tax_firm\": \"Fondo\",\n  \"states_filed\": [\n    \"CA\"\n  ],\n  \"file_id\": \"file_8dJ2kq9XbT4mNa\"\n}"

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

{
  "id": "<string>",
  "object": "tax",
  "type": "income",
  "year": 123,
  "jurisdictions": [
    "<string>"
  ],
  "unmapped_jurisdictions": [
    "<string>"
  ],
  "filing_status": "onboarding",
  "filed_at": 123,
  "filed_elsewhere": true,
  "extension_filed_at": 123,
  "documents": [
    {
      "type": "draft_return",
      "filename": "<string>",
      "content_type": "application/pdf",
      "download_url": "<string>",
      "expires_at": 123
    }
  ],
  "created": 123,
  "updated": 123
}

Authorizations

Authorization

string

header

required

API key prefixed with finta_

Body

application/json

tax_year

integer

required

The tax year the return covers. Only last year or the year before is accepted (2025 or 2024 during 2026); any other year is refused.

tax_firm

string

required

The firm or person who prepared the return. Required, as on the Taxes page; like the page, Finta does not currently store it.

Minimum string length: 1

states_filed

string[]

required

USPS codes of the states the return was filed in, such as CA; DC is accepted. Empty when no state return was filed. They become the record's jurisdictions.

Pattern: ^[A-Z]{2}$

file_id

string

required

A file from Create file or Create file upload that is not yet attached.

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

Response

The year's income tax record, marked filed, with the PDF as its filed_return document.

string

required

Stable opaque ID. Income and franchise IDs have separate prefixes and cannot collide.

Pattern: ^tax_(income|franchise)_[A-Za-z0-9]+$

object

enum<string>

required

Available options:

tax

type

enum<string>

required

Available options:

income,

franchise

year

integer

required

jurisdictions

string[]

required

Covered jurisdictions. Income records include US and known recorded states; Delaware franchise records contain only US-DE. The upload alias washington_dc and district_of_columbia both map to US-DC. Status and documents apply to the shared record, not independently to each jurisdiction.

Pattern: ^US(-[A-Z]{2})?$

unmapped_jurisdictions

string[]

required

Stored state names that cannot be mapped to a supported jurisdiction code. Empty when every stored state is recognized.

filing_status

enum<string>

required

Recorded filing progress. onboarding means filing onboarding is not yet completed; preparing means onboarding is completed and draft preparation is pending; review_required means draft preparation is completed and income review/signing or Delaware payment information is needed; filing means review/signing is completed and filing completion is pending; filed means the filing workflow is recorded as completed. It does not establish tax payment or authority acceptance. Handle future unfamiliar values without assuming completion.

Available options:

onboarding,

preparing,

review_required,

filing,

filed

filed_at

integer | null

required

Recorded filing-workflow completion time in Unix seconds when filing is completed. Null when unavailable. Never substitutes updated. For uploaded returns this may be when completion was recorded in Finta.

filed_elsewhere

boolean

required

Whether the record is an uploaded income return or a Delaware filing marked already filed outside Finta.

extension_filed_at

integer | null

required

Recorded income-extension filing time in Unix seconds; null for franchise taxes or when no extension is recorded.

documents

object[]

required

Available PDF attachments, which may be absent even on a filed record. Income records expose their draft/final package; franchise records expose their confirmation PDF. No bank or signing credentials are returned.

Show child attributes

created

integer

required

Record creation time in Unix seconds.

updated

integer

required

Record update time in Unix seconds; not an incremental-sync watermark for related attachments.

Create income upload

curl --request POST \
  --url https://app.finta.com/api/v1/taxes/income_uploads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tax_year": 2025,
  "tax_firm": "Fondo",
  "states_filed": [
    "CA"
  ],
  "file_id": "file_8dJ2kq9XbT4mNa"
}
'

import requests

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

payload = {
    "tax_year": 2025,
    "tax_firm": "Fondo",
    "states_filed": ["CA"],
    "file_id": "file_8dJ2kq9XbT4mNa"
}
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({
    tax_year: 2025,
    tax_firm: 'Fondo',
    states_filed: ['CA'],
    file_id: 'file_8dJ2kq9XbT4mNa'
  })
};

fetch('https://app.finta.com/api/v1/taxes/income_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/taxes/income_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([
    'tax_year' => 2025,
    'tax_firm' => 'Fondo',
    'states_filed' => [
        'CA'
    ],
    'file_id' => 'file_8dJ2kq9XbT4mNa'
  ]),
  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/taxes/income_uploads"

	payload := strings.NewReader("{\n  \"tax_year\": 2025,\n  \"tax_firm\": \"Fondo\",\n  \"states_filed\": [\n    \"CA\"\n  ],\n  \"file_id\": \"file_8dJ2kq9XbT4mNa\"\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/taxes/income_uploads")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"tax_year\": 2025,\n  \"tax_firm\": \"Fondo\",\n  \"states_filed\": [\n    \"CA\"\n  ],\n  \"file_id\": \"file_8dJ2kq9XbT4mNa\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.finta.com/api/v1/taxes/income_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  \"tax_year\": 2025,\n  \"tax_firm\": \"Fondo\",\n  \"states_filed\": [\n    \"CA\"\n  ],\n  \"file_id\": \"file_8dJ2kq9XbT4mNa\"\n}"

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

{
  "id": "<string>",
  "object": "tax",
  "type": "income",
  "year": 123,
  "jurisdictions": [
    "<string>"
  ],
  "unmapped_jurisdictions": [
    "<string>"
  ],
  "filing_status": "onboarding",
  "filed_at": 123,
  "filed_elsewhere": true,
  "extension_filed_at": 123,
  "documents": [
    {
      "type": "draft_return",
      "filename": "<string>",
      "content_type": "application/pdf",
      "download_url": "<string>",
      "expires_at": 123
    }
  ],
  "created": 123,
  "updated": 123
}

API Reference

Taxes

Files

Company

Team

Categories

Rules

Departments

Integrations

Aggregations

Transactions

Forms

Journal Entries

Invoices

Parties

Reports

Feedback

Tax Credits

Create income upload

Authorizations

Body

Response