API Documentation
Complete API reference for e-filing all supported IRS forms via the Plain Dot platform. Each endpoint accepts JSON payloads and returns standardized responses with validation results.
Getting Started
All API requests require authentication via API key in the Authorization header:
Authorization: Bearer YOUR_API_KEY
Base URL: https://api.plaindot.com/v1
W-2 Forms
W-2 - Wage and Tax Statement
Report wages paid and taxes withheld for employees
POST /v1/returns/w-2{
"payerId": "PAYER-123",
"taxYear": 2025,
"employee": {
"ssn": "123-45-6789",
"firstName": "JOHN",
"lastName": "DOE",
"address": "123 MAIN ST",
"city": "ALBANY",
"state": "NY",
"zip": "12203"
},
"wages": 75000.00,
"federalWithheld": 12000.00,
"socialSecurityWages": 75000.00,
"socialSecurityWithheld": 4650.00,
"medicareWages": 75000.00,
"medicareWithheld": 1087.50
}W-2C - Corrected Wage and Tax Statement
Correct information on a previously filed W-2
POST /v1/returns/w-2c{
"payerId": "PAYER-123",
"taxYear": 2025,
"originalW2": "W2-2025-001",
"employee": {
"ssn": "123-45-6789",
"firstName": "JOHN",
"lastName": "DOE"
},
"correctedWages": 76000.00,
"correctedFederalWithheld": 12100.00
}W-2G - Certain Gambling Winnings
Report gambling winnings and any federal income tax withheld
POST /v1/returns/w-2g{
"payerId": "PAYER-123",
"taxYear": 2025,
"winner": {
"ssn": "123-45-6789",
"firstName": "JANE",
"lastName": "SMITH"
},
"winnings": 5000.00,
"dateWon": "2025-03-15",
"typeOfWager": "SLOT_MACHINE",
"federalWithheld": 1250.00
}1095 Forms
1095-B - Health Coverage
Report health insurance coverage information
POST /v1/returns/1095-b{
"payerId": "PAYER-123",
"taxYear": 2025,
"recipient": {
"ssn": "123-45-6789",
"firstName": "ALEX",
"lastName": "JOHNSON"
},
"coverage": {
"allMonths": true,
"policyNumber": "POL-123456"
}
}1095-C - Employer-Provided Health Insurance Offer and Coverage
Report information about health insurance offered by employers
POST /v1/returns/1095-c{
"payerId": "PAYER-123",
"taxYear": 2025,
"employee": {
"ssn": "123-45-6789",
"firstName": "SARAH",
"lastName": "WILLIAMS"
},
"offers": {
"allMonths": true,
"lowestCostOption": 250.00
}
}1098 Forms
1098 - Mortgage Interest Statement
Report mortgage interest received from payers
POST /v1/returns/1098{
"payerId": "LENDER-123",
"taxYear": 2025,
"borrower": {
"ssn": "123-45-6789",
"firstName": "MICHAEL",
"lastName": "BROWN"
},
"mortgageInterest": 15000.00,
"points": 2000.00,
"propertyAddress": "456 ELM ST, ALBANY, NY 12203"
}1098-C - Contributions of Motor Vehicles, Boats, and Airplanes
Report vehicle donations to charitable organizations
POST /v1/returns/1098-c{
"payerId": "CHARITY-123",
"taxYear": 2025,
"donor": {
"ssn": "123-45-6789",
"firstName": "DAVID",
"lastName": "MILLER"
},
"vehicle": {
"year": 2018,
"make": "HONDA",
"model": "ACCORD",
"vin": "1HGBH41JXMN109186"
},
"donationDate": "2025-05-10",
"grossProceeds": 8500.00
}1098-E - Student Loan Interest Statement
Report student loan interest received
POST /v1/returns/1098-e{
"payerId": "LENDER-456",
"taxYear": 2025,
"borrower": {
"ssn": "123-45-6789",
"firstName": "EMILY",
"lastName": "DAVIS"
},
"studentLoanInterest": 2500.00
}1098-F - Fines, Penalties, and Other Amounts
Report fines and penalties paid to government entities
POST /v1/returns/1098-f{
"payerId": "GOVT-789",
"taxYear": 2025,
"payer": {
"ein": "12-3456789",
"name": "ABC CORPORATION"
},
"totalAmount": 50000.00,
"restitution": 20000.00,
"compliance": 30000.00
}1098-T - Tuition Statement
Report qualified tuition and related expenses
POST /v1/returns/1098-t{
"payerId": "SCHOOL-123",
"taxYear": 2025,
"student": {
"ssn": "123-45-6789",
"firstName": "CHRIS",
"lastName": "WILSON"
},
"paymentsReceived": 25000.00,
"adjustments": 0.00,
"scholarships": 5000.00,
"halfTimeStudent": false
}1099 Forms
1099-A - Acquisition or Abandonment of Secured Property
Report acquisition or abandonment of property that was security for a debt
POST /v1/returns/1099-a{
"payerId": "LENDER-123",
"taxYear": 2025,
"borrower": {
"tin": "123-45-6789",
"type": "IND",
"firstName": "ROBERT",
"lastName": "TAYLOR"
},
"acquisitionDate": "2025-06-15",
"balanceOfDebt": 200000.00,
"fairMarketValue": 180000.00,
"personallyLiable": true
}1099-B - Proceeds from Broker and Barter Exchange Transactions
Report proceeds from sales of securities and commodities
POST /v1/returns/1099-b{
"payerId": "BROKER-456",
"taxYear": 2025,
"recipient": {
"tin": "123-45-6789",
"type": "IND",
"firstName": "LINDA",
"lastName": "ANDERSON"
},
"proceeds": 50000.00,
"costBasis": 45000.00,
"dateAcquired": "2020-03-10",
"dateSold": "2025-08-20",
"shortTerm": false
}1099-C - Cancellation of Debt
Report cancellation of debt of $600 or more
POST /v1/returns/1099-c{
"payerId": "CREDITOR-789",
"taxYear": 2025,
"debtor": {
"tin": "123-45-6789",
"type": "IND",
"firstName": "JAMES",
"lastName": "MARTIN"
},
"debtCanceled": 15000.00,
"interestIncluded": 1200.00,
"cancellationDate": "2025-04-30",
"debtDescription": "CREDIT_CARD"
}1099-CAP - Changes in Corporate Control and Capital Structure
Report changes in corporate control and capital structure
POST /v1/returns/1099-cap{
"payerId": "CORP-123",
"taxYear": 2025,
"shareholder": {
"tin": "12-3456789",
"type": "BUS",
"name": "XYZ INVESTMENTS LLC"
},
"cashReceived": 100000.00,
"fairMarketValue": 120000.00,
"changeDate": "2025-09-15"
}1099-DA - Information Return for Donor Advised Funds
Report distributions from donor advised funds
POST /v1/returns/1099-da{
"payerId": "FUND-456",
"taxYear": 2025,
"donor": {
"tin": "123-45-6789",
"type": "IND",
"firstName": "PATRICIA",
"lastName": "THOMAS"
},
"fairMarketValue": 500000.00,
"distributions": 25000.00,
"adminFees": 1000.00
}1099-DIV - Dividends and Distributions
Report dividend payments and distributions
POST /v1/returns/1099-div{
"payerId": "PAYER-123",
"taxYear": 2025,
"recipient": {
"tin": "123-45-6789",
"type": "IND",
"firstName": "MARK",
"lastName": "JACKSON"
},
"totalOrdinaryDividends": 5000.00,
"qualifiedDividends": 4500.00,
"totalCapitalGain": 2000.00,
"foreignTaxPaid": 250.00
}1099-G - Certain Government Payments
Report unemployment compensation and state/local tax refunds
POST /v1/returns/1099-g{
"payerId": "STATE-123",
"taxYear": 2025,
"recipient": {
"tin": "123-45-6789",
"type": "IND",
"firstName": "BARBARA",
"lastName": "WHITE"
},
"unemploymentCompensation": 12000.00,
"federalWithheld": 1200.00,
"stateTaxRefund": 800.00
}1099-INT - Interest Income
Report interest income of $10 or more
POST /v1/returns/1099-int{
"payerId": "BANK-456",
"taxYear": 2025,
"recipient": {
"tin": "123-45-6789",
"type": "IND",
"firstName": "RICHARD",
"lastName": "HARRIS"
},
"interestIncome": 2500.00,
"earlyWithdrawalPenalty": 100.00,
"federalWithheld": 250.00,
"investmentExpenses": 50.00
}1099-K - Payment Card and Third Party Network Transactions
Report payment card and third-party network transactions
POST /v1/returns/1099-k{
"payerId": "PROCESSOR-789",
"taxYear": 2025,
"merchant": {
"tin": "12-3456789",
"type": "BUS",
"name": "SMALL BUSINESS LLC"
},
"grossAmount": 125000.00,
"cardNotPresent": 45000.00,
"numberOfTransactions": 1250,
"january": 10000.00,
"february": 10500.00
}1099-LTC - Long-Term Care and Accelerated Death Benefits
Report long-term care benefits and accelerated death benefits
POST /v1/returns/1099-ltc{
"payerId": "INSURANCE-123",
"taxYear": 2025,
"recipient": {
"tin": "123-45-6789",
"type": "IND",
"firstName": "SUSAN",
"lastName": "CLARK"
},
"grossBenefits": 35000.00,
"acceleratedDeathBenefits": 0.00,
"perDiemPayments": 35000.00,
"reimbursedAmount": 30000.00
}1099-MISC - Miscellaneous Information
Report miscellaneous income of $600 or more
POST /v1/returns/1099-misc{
"payerId": "PAYER-123",
"taxYear": 2025,
"recipient": {
"tin": "123-45-6789",
"type": "IND",
"firstName": "JOSEPH",
"lastName": "RODRIGUEZ"
},
"rents": 18000.00,
"royalties": 5000.00,
"otherIncome": 2500.00,
"federalWithheld": 1000.00
}1099-NEC - Nonemployee Compensation
Report nonemployee compensation of $600 or more
POST /v1/returns/1099-nec{
"payerId": "PAYER-123",
"taxYear": 2025,
"recipient": {
"tin": "123-45-6789",
"type": "IND",
"firstName": "JENNIFER",
"lastName": "GARCIA"
},
"nonemployeeCompensation": 25000.00,
"federalWithheld": 0.00,
"stateTaxWithheld": 1000.00
}1099-OID - Original Issue Discount
Report original issue discount on debt instruments
POST /v1/returns/1099-oid{
"payerId": "ISSUER-456",
"taxYear": 2025,
"recipient": {
"tin": "123-45-6789",
"type": "IND",
"firstName": "WILLIAM",
"lastName": "MARTINEZ"
},
"originalIssueDiscount": 1500.00,
"otherPeriodicInterest": 500.00,
"earlyWithdrawalPenalty": 0.00
}1099-PATR - Taxable Distributions Received from Cooperatives
Report patronage dividends and other distributions from cooperatives
POST /v1/returns/1099-patr{
"payerId": "COOP-789",
"taxYear": 2025,
"recipient": {
"tin": "12-3456789",
"type": "BUS",
"name": "FARM SUPPLY INC"
},
"patronageDividends": 5000.00,
"nonpatronageDistributions": 1000.00,
"perUnitRetainAllocations": 2000.00
}1099-Q - Payments from Qualified Education Programs
Report distributions from 529 plans and Coverdell ESAs
POST /v1/returns/1099-q{
"payerId": "PLAN-123",
"taxYear": 2025,
"recipient": {
"tin": "123-45-6789",
"type": "IND",
"firstName": "MARY",
"lastName": "JOHNSON"
},
"grossDistribution": 15000.00,
"earnings": 3000.00,
"basis": 12000.00,
"trusteeToTrustee": false
}1099-R - Distributions from Pensions, Annuities, etc.
Report distributions from retirement plans and IRAs
POST /v1/returns/1099-r{
"payerId": "PLAN-456",
"taxYear": 2025,
"recipient": {
"tin": "123-45-6789",
"type": "IND",
"firstName": "ROBERT",
"lastName": "BROWN"
},
"grossDistribution": 50000.00,
"taxableAmount": 45000.00,
"federalWithheld": 9000.00,
"distributionCode": "7"
}1099-S - Proceeds from Real Estate Transactions
Report proceeds from sales of real estate
POST /v1/returns/1099-s{
"payerId": "CLOSING-789",
"taxYear": 2025,
"transferor": {
"tin": "123-45-6789",
"type": "IND",
"firstName": "PATRICIA",
"lastName": "DAVIS"
},
"grossProceeds": 350000.00,
"closingDate": "2025-07-15",
"propertyAddress": "789 OAK AVE, SCHENECTADY, NY 12345"
}1099-SA - Distributions from an HSA, Archer MSA, or Medicare Advantage MSA
Report distributions from health savings accounts
POST /v1/returns/1099-sa{
"payerId": "TRUSTEE-123",
"taxYear": 2025,
"recipient": {
"tin": "123-45-6789",
"type": "IND",
"firstName": "ELIZABETH",
"lastName": "WILSON"
},
"grossDistribution": 3500.00,
"earnings": 150.00,
"distributionCode": "1",
"hsaArcherMedicare": "HSA"
}Other Forms
3921 - Exercise of an Incentive Stock Option
Report exercises of incentive stock options
POST /v1/returns/3921{
"payerId": "CORP-123",
"taxYear": 2025,
"employee": {
"tin": "123-45-6789",
"firstName": "CHARLES",
"lastName": "THOMPSON"
},
"exerciseDate": "2025-04-15",
"exercisePrice": 10.00,
"fairMarketValue": 25.00,
"sharesTransferred": 1000
}3922 - Transfer of Stock Acquired Through an ESPP
Report transfers of stock acquired through employee stock purchase plans
POST /v1/returns/3922{
"payerId": "CORP-456",
"taxYear": 2025,
"employee": {
"tin": "123-45-6789",
"firstName": "NANCY",
"lastName": "LEE"
},
"grantDate": "2024-01-01",
"transferDate": "2025-06-30",
"exercisePrice": 15.00,
"fairMarketValueGrant": 18.00,
"fairMarketValueExercise": 22.00,
"sharesTransferred": 500
}5498 - IRA Contribution Information
Report IRA contributions, rollovers, and fair market value
POST /v1/returns/5498{
"payerId": "TRUSTEE-789",
"taxYear": 2025,
"participant": {
"tin": "123-45-6789",
"firstName": "DANIEL",
"lastName": "MOORE"
},
"iraContributions": 6500.00,
"rolloverContributions": 0.00,
"rothIraConversion": 0.00,
"fairMarketValue": 125000.00,
"requiredMinimumDistribution": false
}5498-ESA - Coverdell ESA Contribution Information
Report contributions to Coverdell Education Savings Accounts
POST /v1/returns/5498-esa{
"payerId": "TRUSTEE-123",
"taxYear": 2025,
"beneficiary": {
"tin": "123-45-6789",
"firstName": "EMMA",
"lastName": "TAYLOR"
},
"contributions": 2000.00,
"rolloverContributions": 0.00
}5498-SA - HSA, Archer MSA, or Medicare Advantage MSA Information
Report contributions to health savings accounts
POST /v1/returns/5498-sa{
"payerId": "TRUSTEE-456",
"taxYear": 2025,
"participant": {
"tin": "123-45-6789",
"firstName": "OLIVIA",
"lastName": "ANDERSON"
},
"employeeContributions": 3850.00,
"employerContributions": 1000.00,
"totalContributions": 4850.00,
"fairMarketValue": 12500.00
}Response Format
All endpoints return a consistent response structure:
{
"id": "ret_abc123",
"status": "accepted",
"formType": "1099-NEC",
"taxYear": 2025,
"validations": [],
"irsSubmissionId": null,
"createdAt": "2025-01-15T10:30:00Z"
}Error Handling
Common HTTP status codes:
200Success400Bad request - malformed JSON or missing required fields401Unauthorized - invalid or missing API key422Validation failed - check validations object in response429Rate limit exceeded500Internal server error