Overview
The Tax API provides recipients with access to the following documents for consumer-permissioned accounts:
- Tax document images in PDF format
- Detailed tax data in JSON format
The API supports multiple tax form types including:
- 1099-DIV
- 1099-INT
- W-2
- 1042-S
Security
The Tax API requires authentication using a bearer token (id_token assigned to the permissioned user). The id_token should be included in the Authorization header of each request.
For more information on ID tokens, please see the Token API documentation.
Base URL
Like all Akoya APIs, Tax operates in both sandbox and prod:
- Sandbox:
https://sandbox-products.ddp.akoya.com - Production:
https://products.ddp.akoya.com
Endpoints
Search tax forms
GET /tax-forms/{version}/{providerId}/{accountId}
Retrieves a list of tax documents and available tax form images for a specific year.
Path params
| Param | Description |
|---|---|
{version} | Major API version (e.g. v2) |
{providerId} | ID for the financial institution providing the data |
{accountId} | The consumer’s unique account identifier (not the account number) |
Query params
| Param | Type | Required | Description |
|---|---|---|---|
taxYear | String | Yes | Tax year to search for (e.g. 2024) |
taxForms | Array | No | Specific tax form (e.g. Tax1099Int) |
taxDataType | String | No | Format for tax form data (JSON or Base64_PDF) |
resultType | String | No | Specifies response type |
Example response
A list of tax statements matching the search criteria
Data elements shown are not exhaustive
This is an example. See the chart below for a complete list of supported data elements.
{
"statements": [
{
"taxYear": 2024,
"taxStatementId": "9876987698769876",
"attributes": [
{ "name": "federalTaxWithheld", "value": "4014.00" }
],
"taxDataType": "JSON",
"forms": [
{
"tax1099Div": {
"taxYear": 2024,
"taxFormId": "9876987698769876",
"taxFormDate": "2024-03-30",
"taxFormType": "Tax1099Div"
}
}
]
}
]
}
Retrieve a specific tax form
GET /tax-forms/{version}/{providerId}/{taxFormId}
Fetches a specific tax form's data and image.
Path params
| Param | Description |
|---|---|
{version} | API major version (e.g. v2) |
{providerId} | ID for the financial institution providing the data |
{taxFormId} | taxFormId(e.g. 9876987698769876) |
Query params
| Param | Type | Required | Description |
|---|---|---|---|
taxDataType | String | No | Format for tax form data (JSON or BASE64_PDF) |
Example response
- Returns tax form data in JSON format.
- If requested, returns tax form images as PDF
Data elements shown are not exhaustive
This is an example. See the chart below for a complete list of supported data elements.
{
"taxYear": 2024,
"taxStatementId": "1234123412341234",
"attributes": [
{ "name": "Total tax withheld", "value": "8025.00" }
],
"issuer": {
"tin": "12-3456789",
"partyType": "BUSINESS",
"businessName": {
"name1": "Financial Data Exchange"
},
"address": {
"line1": "12020 Sunrise Valley Dr",
"city": "Reston",
"region": "VA",
"postalCode": "20191",
"country": "US"
}
},
"recipient": {
"tin": "xxx-xx-1234",
"partyType": "INDIVIDUAL",
"individualName": {
"first": "Kris",
"middle": "Q",
"last": "Public"
},
"address": {
"line1": "1 Main St",
"city": "Melrose",
"region": "NY",
"postalCode": "12121",
"country": "US"
}
},
"taxDataType": "JSON",
"forms": [
{
"tax1099Div": {
"taxYear": 2024,
"taxFormId": "9876987698769876",
"taxFormDate": "2024-03-30",
"foreignAccountTaxCompliance": false,
"ordinaryDividends": 1107,
"qualifiedDividends": 1208,
"totalCapitalGain": 2109,
"foreignTaxPaid": 4014,
"foreignCountry": "Mexico"
}
}
]
}
Supported data elements
| Tax Form Type | Supported Data Elements |
|---|---|
Tax1099Div | ordinaryDividends, qualifiedDividends, totalCapitalGain, unrecaptured1250Gain, section1202Gain, collectiblesGain, nonTaxableDistribution, section199ADividends, investmentExpenses, foreignTaxPaid, foreignCountry, federalTaxWithheld, cashLiquidation, nonCashLiquidation, taxExemptInterestDividend, specifiedPabInterestDividend, stateAndLocalTaxWithholding, foreignAccountTaxCompliance, taxWithheld, income, stateCode, state, local |
Tax1099Int | interestIncome, usBondInterest, earlyWithdrawalPenalty, federalTaxWithheld, investmentExpenses, foreignTaxPaid, foreignCountry, taxExemptInterest, specifiedPabInterest, marketDiscount, bondPremium, usBondPremium, taxExemptBondPremium, cusipNumber, stateAndLocalTaxWithholding, foreignAccountTaxCompliance, taxWithheld, income, stateCode, state, local |
Tax1099B | securityName, numberOfShares, saleDescription, dateAcquired, dateOfSale, salesPrice, costBasis, accruedMarketDiscount, adjustmentCodes, correctedCostBasis, washSaleLossDisallowed, longOrShort, ordinary, collectible, qof, federalTaxWithheld, noncoveredSecurity, grossOrNet, basisReported, stateAndLocalTaxWithholding, cusip, foreignAccountTaxCompliance, taxWithheld, income, stateCode, state, local |
Tax1099R | grossDistribution, taxableAmount, federalTaxWithheld, stateTaxWithheld, stateAndLocalTaxWithholding, distributionCode, iraSepSimple, totalDistribution, pensionAnnuityTaxableAmount, employeeContributions, loanOffsetAmount, taxableAmountNotDetermined, taxWithheld, income, stateCode, state, local |
Tax1099G | unemploymentCompensation, taxableGrants, federalTaxWithheld, stateTaxWithheld, stateAndLocalTaxWithholding, stateOrLocalIncomeTaxRefunds, agriculturalPayments, economicImpactPayment, taxableInterest, taxWithheld, income, stateCode, state, local |
Tax1098 | mortgageInterestReceived, pointsPaid, propertyTaxes, privateMortgageInsurance, loanOriginationDate, outstandingMortgagePrincipal, federalTaxWithheld, stateAndLocalTaxWithholding, mortgageAcquisitionDate, taxWithheld, income, stateCode, state, local |
TaxW2 | wagesTipsCompensation, socialSecurityWages, medicareWages, federalTaxWithheld, stateTaxWithheld, localTaxWithheld, socialSecurityTaxWithheld, medicareTaxWithheld, retirementPlan, thirdPartySickPay, dependentCareBenefits, nonqualifiedPlans, tipsAllocated, otherCompensation, stateEmployerId, localEmployerId, localityName |
Tax1042S | grossIncome, federalTaxWithheld, foreignTaxPaid, recipientTIN, incomeCode, exemptionCode, countryCode, withholdingAgentTIN, primaryWithholdingAgentTIN, intermediaryTIN, payerTIN, chapter3StatusCode, chapter4StatusCode, withholdingRate, chapterIndicator, recipientType, foreignAccountTaxCompliance |
Tax8949 | securityName, dateAcquired, dateOfSale, salesPrice, costBasis, adjustmentAmount, gainLoss, longOrShort, washSaleLossDisallowed, stateAndLocalTaxWithholding, taxWithheld, income, stateCode, state, local |
Tax5498 | iraContributions, rolloverContributions, rothConversionAmount, rothContributions, requiredMinimumDistribution, fairMarketValue, designatedRothContribution, hsaContributions, medicareAdvantageMsaContributions, stateAndLocalTaxWithholding, taxWithheld, income, stateCode, state, local |
Tax1041K1 | beneficiaryTIN, beneficiaryName, ordinaryIncome, qualifiedDividends, capitalGains, foreignTaxPaid, deductions, taxExemptInterest, alternativeMinimumTax, stateAndLocalTaxWithholding, taxWithheld, income, stateCode, state, local |
TaxW2G | grossWinnings, federalTaxWithheld, stateTaxWithheld, localTaxWithheld, typeOfWager, transactionDate, ticketNumber, winnerTIN, stateAndLocalTaxWithholding, taxWithheld, income, stateCode, state, local |
Tax1040ScheduleC | businessIncome, businessExpenses, netProfitOrLoss, costOfGoodsSold, depreciation, businessUseOfHome, mealsAndEntertainment, utilities, supplies, insurance, stateAndLocalTaxWithholding, taxWithheld, income, stateCode, state, local |
CryptocurrencyTaxStatement | totalCryptoSales, totalCryptoPurchases, cryptoCapitalGains, cryptoCapitalLosses, cryptoMiningIncome, cryptoForkIncome, cryptoAirdropIncome, cryptoTransactionFees, stateAndLocalTaxWithholding, taxWithheld, income, stateCode, state, local |
FarmIncomeStatement | totalFarmIncome, totalFarmExpenses, netFarmProfitOrLoss, livestockSales, cropSales, equipmentDepreciation, feedExpenses, fertilizerExpenses, stateAndLocalTaxWithholding, taxWithheld, income, stateCode, state, local |
FarmRentalIncomeStatement | totalFarmRentalIncome, farmRentalExpenses, netFarmRentalProfitOrLoss, landRentalFees, irrigationExpenses, equipmentMaintenance, insurance, stateAndLocalTaxWithholding, taxWithheld, income, stateCode, state, local |
RentalIncomeStatement | totalRentalIncome, rentalExpenses, netRentalProfitOrLoss, propertyManagementFees, mortgageInterest, propertyTaxes, maintenanceRepairs, depreciation, insurance, stateAndLocalTaxWithholding, taxWithheld, income, stateCode, state, local |