Skip to content
IndepAI API Docs

Calculate Tax

POST
/api/v1/tax/calculate
curl --request POST \
  --url https://indepai.app/api/v1/tax/calculate \
  --header 'Content-Type: application/json' \
  --data '{ "countryCode": "PT", "income": { "salary": 0, "freelance": 0, "dividends": 0, "capitalGains": 0, "rental": 0, "other": 0 }, "deductions": { "pension": 0, "health": 0, "education": 0, "housing": 0, "charity": 0, "other": 0 }, "specialProgramId": "nhr-portugal", "filingStatus": "single", "dependents": 0 }'

Calculate estimated tax liability for a given income and country

Request Body

Section titled “Request Body”
Media typeapplication/json
object
countryCode
required

Country for tax calculation

string
>= 2 characters <= 2 characters
Example
PT
income
required
object
salary

Annual salary income

number
0
Example
60000
freelance

Annual freelance/self-employment income

number
0
Example
20000
dividends

Annual dividend income

number
0
Example
5000
capitalGains

Annual capital gains (can be negative)

number
0
Example
10000
rental

Annual rental income

number
0
Example
0
other

Other taxable income

number
0
Example
0
deductions
object
pension

Pension contributions

number
0
health

Health insurance premiums

number
0
education

Education expenses

number
0
housing

Housing deductions (mortgage interest, etc.)

number
0
charity

Charitable donations

number
0
other

Other deductions

number
0
specialProgramId

ID of special tax program to apply

string
Example
nhr-portugal
filingStatus

Tax filing status

string
default: single
Allowed values: single married_filing_jointly married_filing_separately
dependents

Number of dependents

integer
0

Responses

Section titled “Responses”

200

Section titled “200”

Tax calculation result

Media typeapplication/json
object
success
required
boolean
data
required
object
country
required

Country name

string
totalGrossIncome
required

Total gross income

number
taxableIncome
required

Taxable income after deductions

number
totalDeductions
required

Total deductions applied

number
taxBreakdown
required
object
incomeTax
required

Income tax amount

number
capitalGainsTax
required

Capital gains tax amount

number
dividendTax
required

Dividend tax amount

number
socialSecurity
required

Social security contributions

number
otherTaxes
required

Other applicable taxes

number
totalTax
required

Total tax liability

number
effectiveTaxRate
required

Effective tax rate (%)

number
<= 100
netIncome
required

Net income after taxes

number
specialProgramApplied
required

Name of special program applied

string | null
notes
required

Important notes and disclaimers

Array<string>
comparison
required

Comparison with standard taxation

object
standardTax
required

Tax without special programs

number
savings
required

Savings from special program

number
meta
required
object
timestamp
required
string format: date-time
disclaimer
required

Legal disclaimer

string
Example
{
  "success": true,
  "data": {
    "country": "Portugal",
    "totalGrossIncome": 95000,
    "taxableIncome": 85000,
    "totalDeductions": 10000,
    "taxBreakdown": {
      "incomeTax": 25000,
      "capitalGainsTax": 2800,
      "dividendTax": 1400,
      "socialSecurity": 5000,
      "otherTaxes": 0
    },
    "totalTax": 34200,
    "effectiveTaxRate": 36,
    "netIncome": 60800
  },
  "meta": {
    "disclaimer": "This is an estimate only. Consult a tax professional for accurate advice."
  }
}

400

Section titled “400”

Validation error

Media typeapplication/json
object
success
required

Always false for error responses

boolean
error
required

Error type

string
code

Machine-readable error code

string
details

Detailed validation errors

Array<object>
object
path
required

Path to the invalid field

string
message
required

Error message

string
Example
{
  "success": false,
  "error": "Validation error",
  "code": "VALIDATION_ERROR",
  "details": [
    {
      "path": "currentAge",
      "message": "Must be between 18 and 100"
    }
  ]
}