{
  "info": {
    "_postman_id": "countrytaxcalc-api-v1",
    "name": "CountryTaxCalc API v1",
    "description": "Income tax calculation API covering 111 countries, all 50 US states, and 13 Canadian provinces.\n\nAuthentication: pass your API key in the `X-API-Key` header.\n\nGet a free API key at https://countrytaxcalc.com/api-access/\nFull documentation at https://countrytaxcalc.com/api/",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
    "version": "1.0.0"
  },
  "auth": {
    "type": "apikey",
    "apikey": [
      { "key": "key", "value": "X-API-Key", "type": "string" },
      { "key": "value", "value": "{{api_key}}", "type": "string" },
      { "key": "in", "value": "header", "type": "string" }
    ]
  },
  "variable": [
    {
      "key": "base_url",
      "value": "https://api.countrytaxcalc.com",
      "type": "string",
      "description": "API base URL"
    },
    {
      "key": "api_key",
      "value": "ctc_your_key_here",
      "type": "string",
      "description": "Your CountryTaxCalc API key. Get one at https://countrytaxcalc.com/api-access/"
    }
  ],
  "item": [
    {
      "name": "Health",
      "item": [
        {
          "name": "Health check",
          "request": {
            "auth": { "type": "noauth" },
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/v1/health",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "health"]
            },
            "description": "Returns server and database status. No authentication required. Use this to verify the API is reachable before making authenticated requests."
          },
          "response": [
            {
              "name": "Healthy",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"status\": \"healthy\",\n  \"timestamp\": \"2026-07-06T12:00:00.000Z\",\n  \"database\": \"connected\"\n}"
            }
          ]
        }
      ]
    },
    {
      "name": "Countries",
      "item": [
        {
          "name": "List all countries",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/v1/countries",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "countries"]
            },
            "description": "Returns all 111+ supported countries with currency metadata. Available on all tiers including Free.\n\nRequired tier: Free+"
          },
          "response": [
            {
              "name": "200 OK",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"countries\": [\n    {\n      \"country_code\": \"DE\",\n      \"country_name\": \"Germany\",\n      \"currency\": \"EUR\",\n      \"currency_symbol\": \"€\",\n      \"currency_name\": \"Euro\",\n      \"has_jurisdictions\": false\n    },\n    {\n      \"country_code\": \"US\",\n      \"country_name\": \"United States\",\n      \"currency\": \"USD\",\n      \"currency_symbol\": \"$\",\n      \"currency_name\": \"US Dollar\",\n      \"has_jurisdictions\": true\n    }\n  ],\n  \"total\": 111\n}"
            }
          ]
        },
        {
          "name": "Country detail",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/v1/countries/DE",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "countries", "DE"]
            },
            "description": "Detailed info for a single country including available jurisdictions, complexity rating, and feature flags.\n\nRequired tier: Starter+"
          },
          "response": [
            {
              "name": "Germany",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"country_code\": \"DE\",\n  \"country_name\": \"Germany\",\n  \"currency\": \"EUR\",\n  \"currency_symbol\": \"€\",\n  \"currency_name\": \"Euro\",\n  \"tax_year\": 2026,\n  \"has_jurisdictions\": false,\n  \"calculation_complexity\": \"advanced\",\n  \"features\": [\"national_income_tax\", \"social_contributions\", \"solidarity_surcharge\", \"progressive_brackets\"],\n  \"source_url\": \"https://www.bundesfinanzministerium.de/\",\n  \"last_updated\": \"2026-04-15\"\n}"
            },
            {
              "name": "USA (with jurisdictions)",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"country_code\": \"US\",\n  \"country_name\": \"United States\",\n  \"currency\": \"USD\",\n  \"tax_year\": 2026,\n  \"has_jurisdictions\": true,\n  \"jurisdictions\": [\n    { \"code\": \"CA\", \"name\": \"California\", \"has_income_tax\": true },\n    { \"code\": \"TX\", \"name\": \"Texas\", \"has_income_tax\": false },\n    { \"code\": \"NY\", \"name\": \"New York\", \"has_income_tax\": true }\n  ],\n  \"calculation_complexity\": \"complex\",\n  \"features\": [\"federal_tax\", \"state_tax\", \"social_contributions\", \"progressive_brackets\"]\n}"
            }
          ]
        },
        {
          "name": "Tax rates for a country",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/v1/countries/DE/rates",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "countries", "DE", "rates"],
              "query": [
                {
                  "key": "year",
                  "value": "2026",
                  "description": "Tax year (defaults to current year). Historical years require Growth+.",
                  "disabled": true
                }
              ]
            },
            "description": "Raw tax brackets, deductions, and social contribution rates. No income calculation required. Responses are cached for 1 hour.\n\nRequired tier: Starter+\nHistorical years: Growth+"
          },
          "response": [
            {
              "name": "Germany rates",
              "status": "OK",
              "code": 200,
              "header": [
                { "key": "Content-Type", "value": "application/json" },
                { "key": "Cache-Control", "value": "public, max-age=3600" }
              ],
              "body": "{\n  \"country_code\": \"DE\",\n  \"country_name\": \"Germany\",\n  \"currency\": \"EUR\",\n  \"tax_year\": 2026,\n  \"calculation_type\": \"progressive\",\n  \"source_url\": \"https://www.bundesfinanzministerium.de/\",\n  \"last_updated\": \"2026-04-15\",\n  \"brackets\": [\n    { \"from\": 0, \"to\": 11784, \"rate\": 0, \"rate_percent\": \"0.0%\" },\n    { \"from\": 11784, \"to\": 66761, \"rate\": 0.14, \"rate_percent\": \"14.0%\" },\n    { \"from\": 66761, \"to\": 277826, \"rate\": 0.42, \"rate_percent\": \"42.0%\" },\n    { \"from\": 277826, \"to\": null, \"rate\": 0.45, \"rate_percent\": \"45.0%\" }\n  ],\n  \"deductions\": [],\n  \"social_contributions\": [\n    {\n      \"name\": \"Health Insurance (Employee)\",\n      \"type\": \"health_employee\",\n      \"employee_rate\": 0.0735,\n      \"employer_rate\": 0.0735,\n      \"cap_amount\": null\n    },\n    {\n      \"name\": \"Pension (Employee)\",\n      \"type\": \"pension_employee\",\n      \"employee_rate\": 0.093,\n      \"employer_rate\": 0.093,\n      \"cap_amount\": 90600\n    }\n  ]\n}"
            }
          ]
        }
      ]
    },
    {
      "name": "Calculate",
      "item": [
        {
          "name": "Calculate tax — Germany (EUR)",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"country\": \"DE\",\n  \"income\": 80000,\n  \"currency\": \"EUR\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{base_url}}/api/v1/calculate",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "calculate"]
            },
            "description": "Full tax calculation for Germany with income in EUR.\n\nRequired tier: Free+"
          }
        },
        {
          "name": "Calculate tax — USA California (USD)",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"country\": \"US\",\n  \"income\": 120000,\n  \"currency\": \"USD\",\n  \"jurisdiction\": \"CA\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{base_url}}/api/v1/calculate",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "calculate"]
            },
            "description": "US tax calculation with California state tax included. `jurisdiction: \"CA\"` = California (not Canada).\n\nRequired tier: Free+"
          }
        },
        {
          "name": "Calculate tax — UK (income in USD, auto-converted to GBP)",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"country\": \"GB\",\n  \"income\": 100000,\n  \"currency\": \"USD\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{base_url}}/api/v1/calculate",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "calculate"]
            },
            "description": "When `currency` differs from the country's local currency, the API auto-converts using ECB rates (Frankfurter). The `currency_conversion` object in the response shows the exchange rate used.\n\nRequired tier: Free+"
          }
        },
        {
          "name": "Calculate tax — Canada Ontario",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"country\": \"CA\",\n  \"income\": 95000,\n  \"currency\": \"CAD\",\n  \"jurisdiction\": \"ON\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{base_url}}/api/v1/calculate",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "calculate"]
            },
            "description": "Canada with Ontario provincial tax. Note: `country: \"CA\"` = Canada. `jurisdiction: \"ON\"` = Ontario.\n\nRequired tier: Free+"
          }
        },
        {
          "name": "Calculate tax — historical year (2024)",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"country\": \"DE\",\n  \"income\": 75000,\n  \"currency\": \"EUR\",\n  \"tax_year\": 2024\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{base_url}}/api/v1/calculate",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "calculate"]
            },
            "description": "Request a historical tax year. Returns 403 on Free/Starter — requires Growth tier or higher.\n\nRequired tier: Growth+"
          }
        }
      ]
    },
    {
      "name": "Summary",
      "item": [
        {
          "name": "Rank all countries by tax rate",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/v1/summary?income=100000",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "summary"],
              "query": [
                {
                  "key": "income",
                  "value": "100000",
                  "description": "Gross income. Treated as equivalent amount in each country's local currency."
                },
                {
                  "key": "year",
                  "value": "2026",
                  "description": "Tax year (defaults to current year)",
                  "disabled": true
                }
              ]
            },
            "description": "Returns all 111+ countries ranked by effective tax rate for a given income level. Income is treated as nominal in each country's local currency — use /compare for cross-currency comparisons.\n\nRequired tier: Growth+"
          },
          "response": [
            {
              "name": "200 OK (truncated)",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"income\": 100000,\n  \"currency_note\": \"Income treated as nominal in each country's local currency.\",\n  \"tax_year\": 2026,\n  \"total_countries\": 111,\n  \"countries\": [\n    {\n      \"rank\": 1,\n      \"country_code\": \"AE\",\n      \"country_name\": \"United Arab Emirates\",\n      \"currency\": \"AED\",\n      \"income_tax\": 0,\n      \"social_tax\": 0,\n      \"total_tax\": 0,\n      \"net_income\": 100000,\n      \"effective_tax_rate\": 0,\n      \"effective_tax_rate_percent\": \"0.0%\"\n    }\n  ]\n}"
            }
          ]
        }
      ]
    },
    {
      "name": "Compare",
      "item": [
        {
          "name": "Compare 5 countries",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"income\": 100000,\n  \"currency\": \"USD\",\n  \"countries\": [\n    { \"country\": \"US\", \"jurisdiction\": \"CA\" },\n    { \"country\": \"US\", \"jurisdiction\": \"TX\" },\n    { \"country\": \"GB\" },\n    { \"country\": \"DE\" },\n    { \"country\": \"AU\" }\n  ]\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{base_url}}/api/v1/compare",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "compare"]
            },
            "description": "Compare tax across multiple countries in one call. Maximum 20 countries per request. Each country gets its own currency conversion. Allow 2–5 seconds for large requests.\n\nRequired tier: Pro+"
          }
        },
        {
          "name": "Compare 20 countries (max)",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"income\": 150000,\n  \"currency\": \"USD\",\n  \"countries\": [\n    { \"country\": \"US\", \"jurisdiction\": \"CA\" },\n    { \"country\": \"US\", \"jurisdiction\": \"TX\" },\n    { \"country\": \"US\", \"jurisdiction\": \"NY\" },\n    { \"country\": \"US\", \"jurisdiction\": \"FL\" },\n    { \"country\": \"GB\" },\n    { \"country\": \"DE\" },\n    { \"country\": \"FR\" },\n    { \"country\": \"NL\" },\n    { \"country\": \"AU\" },\n    { \"country\": \"CA\", \"jurisdiction\": \"ON\" },\n    { \"country\": \"SG\" },\n    { \"country\": \"AE\" },\n    { \"country\": \"CH\" },\n    { \"country\": \"IE\" },\n    { \"country\": \"NZ\" },\n    { \"country\": \"PT\" },\n    { \"country\": \"ES\" },\n    { \"country\": \"IT\" },\n    { \"country\": \"JP\" },\n    { \"country\": \"DK\" }\n  ]\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{base_url}}/api/v1/compare",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "compare"]
            },
            "description": "Maximum 20-country comparison. Note: allow 2–5 seconds for this request.\n\nRequired tier: Pro+"
          }
        }
      ]
    }
  ]
}