GET
/
v1-preview
/
models
/
us-form-1040
/
{documentId}
from abbyy_document_ai import DocumentAi
import os


with DocumentAi(
    api_key_auth=os.getenv("DOCUMENTAI_API_KEY_AUTH", ""),
) as document_ai:

    res = document_ai.models.us_form1040.get_extracted_fields(document_id="wh23anb5xjf0ntw5taase5qz")

    assert res.us_form1040 is not None

    # Handle response
    print(res.us_form1040)
{
  "meta": {
    "id": "wh23anb5xjf0ntw5taase5qz",
    "name": "document.jpg",
    "createdAt": "2025-02-07T17:44:06.949Z",
    "model": "us-form-1040",
    "status": "Processed",
    "pageCount": 10,
    "errors": [
      {
        "message": "Total is required"
      }
    ]
  },
  "fields": {
    "form": {
      "1040": true,
      "1040Sr": false
    },
    "year": "2024",
    "filingStatus": {
      "head": false,
      "joint": false,
      "separately": true,
      "single": false,
      "widow": false
    },
    "mfsSpouseOrHohOrQwChildName": "John Smith",
    "firstName": "Jane",
    "lastName": "Doe",
    "ssn": "123-45-6789",
    "spouse": {
      "spousesFirstName": "John",
      "spousesLastName": "Smith",
      "spousesSsn": "987-65-4321"
    },
    "address": {
      "homeAddress": "123 Main Street",
      "apartmentNumber": "Apt 4B",
      "cityTownOrPostOffice": "New York",
      "state": "NY",
      "zipCode": "10001",
      "foreignCountryName": "",
      "foreignProvinceOrStateOrCountry": "",
      "foreignPostalCode": ""
    },
    "fullYearHealthCareCoverageOutdated": true,
    "presidentialElectionCampaign": {
      "you": true,
      "spouse": false
    },
    "financialInterestInVirtualCurrencyDuringThisYear": {
      "yes": false,
      "no": true
    },
    "standardDeduction": {
      "someoneCanClaim": {
        "youAsADependent": false,
        "yourSpouseAsADependent": false
      },
      "separateReturnOrDualStatusAlien": false,
      "ageOrBlindness": {
        "you": {
          "bornBeforeJanuary21957": false,
          "bornBeforeJanuary21956Outdated": false,
          "bornBeforeJanuary21955Outdated": false,
          "bornBeforeJanuary21954Outdated": false,
          "blind": false
        },
        "spouse": {
          "bornBeforeJanuary21957": false,
          "bornBeforeJanuary21956Outdated": false,
          "bornBeforeJanuary21955Outdated": false,
          "bornBeforeJanuary21954Outdated": false,
          "blind": false
        }
      }
    },
    "moreThanFourDependents": false,
    "dependents": [
      {
        "fullName": "Alice Doe",
        "ssn": "111-22-3333",
        "relationship": "Daughter",
        "childTaxCredit": true,
        "creditForOtherDependents": false
      }
    ],
    "wagesSalariesTips": 75000,
    "taxExemptInterestGroup": {
      "taxExemptInterest": 1000,
      "taxableInterest": 500
    },
    "dividendsGroup": {
      "qualifiedDividends": 2000,
      "ordinaryDividends": 3000
    },
    "irasPensionsAndAnnuitiesGroupOutdated": {
      "irasPensionsAndAnnuitiesOutdated": 15000,
      "taxableAmountOutdated": 12000
    },
    "iraDistributionsGroup": {
      "iraDistributions": 5000,
      "taxableAmount": 4000
    },
    "pensionsAndAnnuitiesGroup": {
      "pensionsAndAnnuities": 10000,
      "taxableAmount": 8000
    },
    "socialSecurityBenefitsGroup": {
      "socialSecurityBenefits": 20000,
      "taxableAmount": 15000
    },
    "capitalGainOrLossGroup": {
      "capitalGainOrLoss": 5000,
      "scheduleDNotRequired": true
    },
    "amountFromSchedule1Line22Outdated": 1000,
    "otherIncomeFromSchedule1": 1000,
    "totalIncome": 150000,
    "adjustmentsToIncomeGroup": {
      "fromSchedule1": 5000,
      "charitableContributions": 1000,
      "totalAdjustmentsToIncome": 6000
    },
    "adjustedGrossIncome": 144000,
    "taxableIncomeGroup": {
      "standardDeductionOrItemizedDeductions": 13850,
      "charitableContributions": 1000,
      "partialSum": 14850,
      "qualifiedBusinessIncomeDeduction": 2000,
      "totalDeduction": 16850,
      "taxableIncome": 127150
    },
    "taxGroup": {
      "tax": 25000,
      "form8814": false,
      "form4972": false,
      "otherForm": false,
      "otherFormName": "",
      "amountFromSchedule2CheckOutdated": false,
      "amountFromSchedule2": 0,
      "groupTotal": 25000
    },
    "childTaxCreditGroup": {
      "childTaxCredit": 2000,
      "amountFromSchedule3CheckOutdated": false,
      "amountFromSchedule3": 0,
      "groupTotal": 2000
    },
    "taxMinusChildTaxCredit": 23000,
    "otherTaxesIncludingSelfEmploymentTax": 5000,
    "totalTax": 28000,
    "federalIncomeTaxWithheldFromFormsW2And1099Outdated": 30000,
    "federalIncomeTaxGroup": {
      "formW2": 25000,
      "form1099": 5000,
      "otherForms": 0,
      "groupTotal": 30000
    },
    "thisYearEstimatedTaxPaymentsAndAmountAppliedFromLastYearReturn": 0,
    "earnedIncomeCreditGroup": {
      "earnedIncomeCredit": 0,
      "qualifiedToClaimTheEic": false,
      "combatPayElection": false,
      "priorYearEarnedIncome": 0
    },
    "additionalChildTaxCreditSchedule8812": 0,
    "americanOpportunityCreditFromForm8863": 0,
    "recoveryRebateCredit": 0,
    "amountFromSchedule5": 0,
    "amountFromSchedule3": 0,
    "totalOtherPaymentsAndRefundableCredits": 0,
    "totalPayments": 30000,
    "overpaidAmount": 2000,
    "refundGroup": {
      "form8888Attached": false,
      "refundableAmount": 2000,
      "routingNumber": "123456789",
      "type": {
        "checking": false,
        "saving": true
      },
      "accountNumber": "987654321"
    },
    "overpaidAmountToBeAppliedToNextYearEstimatedTax": 0,
    "owedAmount": 0,
    "estimatedTaxPenalty": 0,
    "thirdPartyDesignee": {
      "anotherPersonCanDiscussWithIrs": {
        "no": true,
        "yes": false
      },
      "designeesName": "",
      "phoneNumber": "",
      "pin": ""
    },
    "signature": {
      "date": "2024-04-15",
      "occupation": "Engineer",
      "identityProtectionPin": ""
    },
    "spousesSignature": {
      "date": "2024-04-15",
      "occupation": "",
      "identityProtectionPin": "",
      "phoneNumber": "",
      "emailAddress": ""
    },
    "preparer": {
      "preparersName": "",
      "date": "2024-04-15",
      "ptin": "",
      "firmsName": "",
      "firmsAddress": "",
      "phoneNumber": "",
      "firmsEin": "",
      "thirdPartyDesigneeOutdated": false,
      "selfEmployed": false
    }
  }
}

Authorizations

​
Authorization
string
header
required

Our API offers authentication via API keys. You can obtain an API key from https://developer.abbyy.com

Path Parameters

​
documentId
string
required

The id of the document

Response

200
application/json

Extracted US Form 1040 Data Response

​
meta
object
required

Represents a document that has been submitted for processing.

Example:
{
  "id": "wh23anb5xjf0ntw5taase5qz",
  "name": "document.jpg",
  "createdAt": "2025-02-07T17:44:06.949Z",
  "model": "image-to-text",
  "status": "Processed",
  "pageCount": 10,
  "errors": [{ "message": "Total is required" }]
}
​
fields
object

Fields extracted from a US Form 1040

Example:
{
  "form": { "1040": true, "1040Sr": false },
  "year": "2024",
  "filingStatus": {
    "head": false,
    "joint": false,
    "separately": true,
    "single": false,
    "widow": false
  },
  "mfsSpouseOrHohOrQwChildName": "John Smith",
  "firstName": "Jane",
  "lastName": "Doe",
  "ssn": "123-45-6789",
  "spouse": {
    "spousesFirstName": "John",
    "spousesLastName": "Smith",
    "spousesSsn": "987-65-4321"
  },
  "address": {
    "homeAddress": "123 Main Street",
    "apartmentNumber": "Apt 4B",
    "cityTownOrPostOffice": "New York",
    "state": "NY",
    "zipCode": "10001",
    "foreignCountryName": "",
    "foreignProvinceOrStateOrCountry": "",
    "foreignPostalCode": ""
  },
  "fullYearHealthCareCoverageOutdated": true,
  "presidentialElectionCampaign": { "you": true, "spouse": false },
  "financialInterestInVirtualCurrencyDuringThisYear": { "yes": false, "no": true },
  "standardDeduction": {
    "someoneCanClaim": {
      "youAsADependent": false,
      "yourSpouseAsADependent": false
    },
    "separateReturnOrDualStatusAlien": false,
    "ageOrBlindness": {
      "you": {
        "bornBeforeJanuary21957": false,
        "bornBeforeJanuary21956Outdated": false,
        "bornBeforeJanuary21955Outdated": false,
        "bornBeforeJanuary21954Outdated": false,
        "blind": false
      },
      "spouse": {
        "bornBeforeJanuary21957": false,
        "bornBeforeJanuary21956Outdated": false,
        "bornBeforeJanuary21955Outdated": false,
        "bornBeforeJanuary21954Outdated": false,
        "blind": false
      }
    }
  },
  "moreThanFourDependents": false,
  "dependents": [
    {
      "fullName": "Alice Doe",
      "ssn": "111-22-3333",
      "relationship": "Daughter",
      "childTaxCredit": true,
      "creditForOtherDependents": false
    }
  ],
  "wagesSalariesTips": 75000,
  "taxExemptInterestGroup": {
    "taxExemptInterest": 1000,
    "taxableInterest": 500
  },
  "dividendsGroup": {
    "qualifiedDividends": 2000,
    "ordinaryDividends": 3000
  },
  "irasPensionsAndAnnuitiesGroupOutdated": {
    "irasPensionsAndAnnuitiesOutdated": 15000,
    "taxableAmountOutdated": 12000
  },
  "iraDistributionsGroup": {
    "iraDistributions": 5000,
    "taxableAmount": 4000
  },
  "pensionsAndAnnuitiesGroup": {
    "pensionsAndAnnuities": 10000,
    "taxableAmount": 8000
  },
  "socialSecurityBenefitsGroup": {
    "socialSecurityBenefits": 20000,
    "taxableAmount": 15000
  },
  "capitalGainOrLossGroup": {
    "capitalGainOrLoss": 5000,
    "scheduleDNotRequired": true
  },
  "amountFromSchedule1Line22Outdated": 1000,
  "otherIncomeFromSchedule1": 1000,
  "totalIncome": 150000,
  "adjustmentsToIncomeGroup": {
    "fromSchedule1": 5000,
    "charitableContributions": 1000,
    "totalAdjustmentsToIncome": 6000
  },
  "adjustedGrossIncome": 144000,
  "taxableIncomeGroup": {
    "standardDeductionOrItemizedDeductions": 13850,
    "charitableContributions": 1000,
    "partialSum": 14850,
    "qualifiedBusinessIncomeDeduction": 2000,
    "totalDeduction": 16850,
    "taxableIncome": 127150
  },
  "taxGroup": {
    "tax": 25000,
    "form8814": false,
    "form4972": false,
    "otherForm": false,
    "otherFormName": "",
    "amountFromSchedule2CheckOutdated": false,
    "amountFromSchedule2": 0,
    "groupTotal": 25000
  },
  "childTaxCreditGroup": {
    "childTaxCredit": 2000,
    "amountFromSchedule3CheckOutdated": false,
    "amountFromSchedule3": 0,
    "groupTotal": 2000
  },
  "taxMinusChildTaxCredit": 23000,
  "otherTaxesIncludingSelfEmploymentTax": 5000,
  "totalTax": 28000,
  "federalIncomeTaxWithheldFromFormsW2And1099Outdated": 30000,
  "federalIncomeTaxGroup": {
    "formW2": 25000,
    "form1099": 5000,
    "otherForms": 0,
    "groupTotal": 30000
  },
  "thisYearEstimatedTaxPaymentsAndAmountAppliedFromLastYearReturn": 0,
  "earnedIncomeCreditGroup": {
    "earnedIncomeCredit": 0,
    "qualifiedToClaimTheEic": false,
    "combatPayElection": false,
    "priorYearEarnedIncome": 0
  },
  "additionalChildTaxCreditSchedule8812": 0,
  "americanOpportunityCreditFromForm8863": 0,
  "recoveryRebateCredit": 0,
  "amountFromSchedule5": 0,
  "amountFromSchedule3": 0,
  "totalOtherPaymentsAndRefundableCredits": 0,
  "totalPayments": 30000,
  "overpaidAmount": 2000,
  "refundGroup": {
    "form8888Attached": false,
    "refundableAmount": 2000,
    "routingNumber": "123456789",
    "type": { "checking": false, "saving": true },
    "accountNumber": "987654321"
  },
  "overpaidAmountToBeAppliedToNextYearEstimatedTax": 0,
  "owedAmount": 0,
  "estimatedTaxPenalty": 0,
  "thirdPartyDesignee": {
    "anotherPersonCanDiscussWithIrs": { "no": true, "yes": false },
    "designeesName": "",
    "phoneNumber": "",
    "pin": ""
  },
  "signature": {
    "date": "2024-04-15",
    "occupation": "Engineer",
    "identityProtectionPin": ""
  },
  "spousesSignature": {
    "date": "2024-04-15",
    "occupation": "",
    "identityProtectionPin": "",
    "phoneNumber": "",
    "emailAddress": ""
  },
  "preparer": {
    "preparersName": "",
    "date": "2024-04-15",
    "ptin": "",
    "firmsName": "",
    "firmsAddress": "",
    "phoneNumber": "",
    "firmsEin": "",
    "thirdPartyDesigneeOutdated": false,
    "selfEmployed": false
  }
}
​
validationErrors
object[]

An array of validation errors that occurred while processing the document. These typically do not prevent field extraction, but rather indicate issues extracting key fields.

Was this page helpful?