openData Studio中文
TurboTax: File Your Tax Return icon

TurboTax tax-return, refund and document data API

Intuit Inc · Business

Open on Google Play

TurboTax: File Your Tax Return is Intuit Inc.'s Android client for U.S. individual income-tax filing. After an Intuit account sign-in, filers import W-2 and 1099 forms by camera scan or employer and broker download, walk the federal and state interview, e-file with the IRS and state agencies, and watch refunds on a native refund-monitor screen. The same shell hosts TurboTax Live Assisted and Live Full Service when the filer wants a CPA or enrolled agent on video, plus a My TurboTax year dashboard, document checklist, and prior-year returns. This build is tax year 2025 (prior year 2024). It is the phone front door for Intuit's U.S. consumer tax franchise and sits next to H&R Block, TaxAct, Cash App Taxes and FreeTaxUSA for wage-and-investment returns.

Federal and state filing rows carry returnStatus and taxAuthority per agency, while refund-monitor amounts land as amount and isRefund keyed by agency. Document checklist items expose checkListItemId, expectedForms and supporting documentIds after a W-2 or 1099 upload. entityKey addresses the year's consumer tax-document vault, and fedReturnState plus productId on the My TurboTax dashboard tell a host which SKU and federal progress the signed-in year is on.

Payroll, cash-advance and bookkeeping stacks use those fields to confirm e-file acceptance and refund versus balance-due before moving money or attaching a scanned wage statement. openData Studio turns the same tax-year objects into callable open data.

Screenshots

  • TurboTax: File Your Tax Return screenshot 1
  • TurboTax: File Your Tax Return screenshot 2
  • TurboTax: File Your Tax Return screenshot 3
  • TurboTax: File Your Tax Return screenshot 4
  • TurboTax: File Your Tax Return screenshot 5
  • TurboTax: File Your Tax Return screenshot 6
  • TurboTax: File Your Tax Return screenshot 7
  • TurboTax: File Your Tax Return screenshot 8

API surface

The endpoints and request/response examples below are reconstructed from the app's interface — illustrative, not a live capture.

  • My TurboTax dashboard state

    GET /v1/filings/{taxYear}/overview openfinance

    Reads the My TurboTax year hub: productId SKU, fedReturnState federal progress, isFFA free-file flag, taxPrepDelegated Live Full Service handoff and ttoDownLevel.

    Auth: OAuth 2 Bearer access token (Authorization: Bearer) issued after Intuit account sign-in, plus a request-correlation header and an optional session-ticket header on some clients.

    • dashboard
    • isFFA
    • productId
    • fedReturnState
    • taxPrepDelegated
    • ttoDownLevel.id
    GET /v1/filings/2025/overview HTTP/1.1
Authorization: Bearer <access_token>
X-Correlation-Id: 6f2c1a8e-9b44-4d11-a3c0-1e7b0d4f9a21
Accept: application/json
    {
  "dashboard": "IN_PROGRESS",
  "isFFA": false,
  "productId": "TURBOTAX_DELUXE",
  "fedReturnState": "PERSONAL_INFO_COMPLETE",
  "taxPrepDelegated": false,
  "ttoDownLevel": {"id": "none"}
}

  • Not-started year dashboard

    GET /v1/filings/{taxYear}/intake-state openfinance

    Loads the not-started My TurboTax year card (isSkipYear) used before a 2025 return is allocated, flagged for the unified Android shell.

    Auth: OAuth 2 Bearer access token (Authorization: Bearer) issued after Intuit account sign-in, plus a request-correlation header.

    • isSkipYear
    GET /v1/filings/2025/intake-state?unifiedShell=true HTTP/1.1
Authorization: Bearer <access_token>
Accept: application/json
    {
  "isSkipYear": false
}

  • E-file status (lite)

    GET /v1/submissions/status openfinance

    Returns lite e-file status for the year's federal and state agencies: taxYear plus per-row taxAuthority and returnStatus.

    Auth: OAuth 2 Bearer access token (Authorization: Bearer). The tax-year entity is addressed by the signed-in return; request-correlation header attached.

    • filing.taxYear
    • agencyReturnInformation.taxAuthority
    • agencyReturnInformation.returnStatus
    GET /v1/submissions/status HTTP/1.1
Authorization: Bearer <access_token>
Accept: application/json
    {
  "filing": {
    "taxYear": "2025",
    "agencyReturnInformation": [
      {
        "taxAuthority": "IRS",
        "returnStatus": "ACCEPTED"
      },
      {
        "taxAuthority": "CA_FTB",
        "returnStatus": "TRANSMITTED"
      }
    ]
  }
}

  • Income tax returns

    GET /v1/returns openfinance

    Lists the filer's income-tax returns (taxYear, productType, efileStatus) used by the prior-year and current-year switchers.

    Auth: OAuth 2 Bearer access token (Authorization: Bearer) with a request-correlation header.

    • taxYear
    • productType
    • efileStatus
    GET /v1/returns HTTP/1.1
Authorization: Bearer <access_token>
Accept: application/json
    {
  "taxReturns": [
    {
      "taxYear": "2025",
      "productType": "DELUXE",
      "efileStatus": "ACCEPTED"
    },
    {
      "taxYear": "2024",
      "productType": "PREMIER",
      "efileStatus": "ACCEPTED"
    }
  ]
}

  • Consumer tax documents

    GET /v1/vaults/{taxYear}/keys opendata

    Resolves the year's consumer tax-document vault keys (entities[].entityKey) used by Full Service and the document checklist.

    Auth: OAuth 2 Bearer access token (Authorization: Bearer) with a request-correlation header.

    • entities.entityKey
    GET /v1/vaults/2025/keys HTTP/1.1
Authorization: Bearer <access_token>
Accept: application/json
    {
  "entities": [
    {
      "entityKey": "ctd-2025-8f21c4a1"
    }
  ]
}

  • Tax-year document checklist

    GET /v1/prep/{taxYear}/required-docs opendata

    Returns the year's document checklist: counts plus items with checkListItemId, expectedForms and supporting documentId rows after a W-2 or 1099 is attached.

    Auth: OAuth 2 Bearer access token (Authorization: Bearer) attached by a shared header interceptor; the call is rejected when the headers cannot be minted. Request-correlation header attached.

    • taxYear
    • numberItems
    • numberCompleted
    • checkListItemId
    • name
    • customDisplayName
    • status
    • expectedForms
    • supportingItems.documentId
    • supportingItems.documentType
    • supportingItems.documentName
    • supportingItems.createDate
    GET /v1/prep/2025/required-docs HTTP/1.1
Authorization: Bearer <access_token>
Accept: application/json
    {
  "taxYear": "2025",
  "numberItems": 4,
  "numberCompleted": 1,
  "checklist": [
    {
      "checkListItemId": "cli-w2-001",
      "name": "W2",
      "customDisplayName": "W-2 from Harbor Mill",
      "description": "Wage and tax statement",
      "deleted": false,
      "status": "COMPLETED",
      "derived": false,
      "source": "SCAN",
      "category": "INCOME",
      "expectedForms": ["W2"],
      "supportingItems": [
        {
          "documentType": "W2",
          "documentId": "doc-9a21",
          "documentName": "w2-harbor-mill.pdf",
          "createDate": "2026-02-12T18:04:11Z"
        }
      ]
    }
  ]
}

  • Start tax-document upload

    POST /v1/uploads/prepare opendata

    Opens a secured document upload (syncExtraction, folderId, uploadDataList) so a scanned W-2 or 1099 can land in the year's vault.

    Auth: OAuth 2 Bearer access token (Authorization: Bearer) for the secured document service that receives W-2 and 1099 images, with per-client authorization attributes and a request-correlation header.

    • syncExtraction
    • folderId
    • uploadDataList
    • documentId
    • status
    POST /v1/uploads/prepare HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "syncExtraction": true,
  "folderId": "folder-ty2025",
  "uploadDataList": [
    {
      "fileName": "w2-harbor-mill.jpg",
      "contentType": "image/jpeg"
    }
  ]
}
    {
  "documentId": "doc-9a21",
  "status": "UPLOAD_STARTED",
  "folderId": "folder-ty2025"
}

  • List vault documents

    GET /v1/files opendata

    Lists documents already in the filer's document vault (the Smart Docs list): documentId, documentType, documentName, createDate.

    Auth: OAuth 2 Bearer access token (Authorization: Bearer) with per-client authorization attributes; the call fails when the bearer is missing.

    • documentId
    • documentType
    • documentName
    • createDate
    GET /v1/files HTTP/1.1
Authorization: Bearer <access_token>
Accept: application/json
    {
  "documents": [
    {
      "documentId": "doc-9a21",
      "documentType": "W2",
      "documentName": "w2-harbor-mill.pdf",
      "createDate": "2026-02-12T18:04:11Z"
    }
  ]
}

  • Refund vs balance due

    POST /v1/refunds/balance openfinance

    Per-agency refund or balance-due lookup returning amount and isRefund (with a federal-versus-state flag) for the native refund-monitor screen.

    Auth: OAuth 2 Bearer access token (Authorization: Bearer) with a request-correlation header.

    • agency
    • amount
    • isRefund
    • state
    POST /v1/refunds/balance HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "taxReturnDescriptor": {
    "taxYear": "2025"
  }
}
    {
  "refundBalanceDue": [
    {
      "agency": "IRS",
      "amount": "1842.00",
      "isRefund": true
    },
    {
      "agency": "CA_FTB",
      "amount": "126.00",
      "isRefund": false
    }
  ]
}

  • Allocate tax session

    POST /v1/filing-sessions/allocate openfinance

    Allocates a TurboTax Online interview session: resourceOwnerId, dpEntityKey, swimlane and readOnly for the year's return.

    Auth: OAuth 2 Bearer access token (Authorization: Bearer). The request body carries the authId from sign-in; request-correlation header attached.

    • authid
    • customerSource
    • alias
    • swimlane
    • version
    • abtest
    • authId
    • resourceOwnerId
    • readOnly
    • dpEntityKey
    POST /v1/filing-sessions/allocate HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "authid": "auth-8f21c4",
  "customerSource": "TTM_ANDROID",
  "alias": "ty2025-individual",
  "swimlane": "prod",
  "version": "12.19.0",
  "abtest": ""
}
    {
  "authId": "auth-8f21c4",
  "resourceOwnerId": "roid-44ab",
  "readOnly": false,
  "dpEntityKey": "dp-2025-9c01",
  "swimlane": "prod",
  "version": "12.19.0"
}

  • Acquire employer tax data

    POST /v1/connections/import openbanking

    Starts a tax-data import connection so W-2/1099 data can be pulled from a payroll or broker provider; the response carries channelId, connectionId and connectionSettings.

    Auth: OAuth 2 Bearer access token (Authorization: Bearer) plus connection headers for the payroll or broker provider link; request-correlation header attached.

    • channelId
    • connectionId
    • connectionSettings
    POST /v1/connections/import HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "providerId": "adp-w2",
  "channelId": "ch-w2-import",
  "connectionSettings": {
    "taxYear": "2025"
  }
}
    {
  "channelId": "ch-w2-import",
  "connectionId": "conn-77de",
  "connectionSettings": {
    "taxYear": "2025",
    "status": "POLLING"
  }
}

  • Intuit account profile

    POST /v1/me/profile osint

    Reads the signed-in Intuit person account: givenName, familyName, email, pseudonymId and uid used across TurboTax, Credit Karma linking and Live expert assignment.

    Auth: Intuit account session established by native sign-in; the OAuth 2 Bearer access token is sent on subsequent profile calls.

    • myAccount.id
    • pseudonymId
    • givenName
    • familyName
    • email
    • userId
    • userIdPseudonym
    • uid
    POST /v1/me/profile HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "fields": ["id", "pseudonymId", "givenName", "familyName", "email"]
}
    {
  "id": "acct-12ab",
  "pseudonymId": "pseudo-44",
  "givenName": "Maya",
  "familyName": "Chen",
  "email": "[email protected]"
}

Data categories

  • tax-returns
  • efile-status
  • refunds
  • tax-documents
  • w2-1099-import
  • identity

Where teams use this data

  • Refund vs balance-due ops

    A payroll or cash-advance product can poll incomeTaxGetRefundBalanceDue and join agency, amount and isRefund (plus RefundItem.isFederalRefundData) to decide whether to surface a refund-advance offer or a balance-due reminder after IRS acceptance.

  • E-file acceptance desk

    A tax-season support desk can watch FilingInfo.agencyReturnInformation rows — taxAuthority plus returnStatus — and TaxReturn.efileStatus so agents know which federal or state return is still TRANSMITTED versus ACCEPTED without opening the interview.

  • W-2 vault sync for bookkeeping

    A bookkeeping stack can take checklist supportingItems.documentId / documentType after start-upload, then pull the year's entityKey from consumer tax documents so the same W-2 image that fed TurboTax also lands in the general ledger.

  • Intuit identity match

    An account-linking flow can match givenName, familyName, email and pseudonymId from the Intuit person account against an existing Credit Karma or QuickBooks login before attaching a tax year.

Frequently asked questions

What filing-status fields does TurboTax expose?

Each agency row on the lite e-file status payload has taxAuthority (for example IRS or a state FTB) and returnStatus, nested under filing.taxYear. The tax-returns list adds efileStatus and productType per taxYear so a host can tell Deluxe from Premier without opening the interview.

How is refund versus balance-due represented?

A refund-and-balance-due lookup returns agency, amount and isRefund for each federal or state agency. The in-app refund monitor shows those as separate federal and state figures so a refund and a balance due never blur together.

Which document fields survive a W-2 upload?

An upload takes folderId and syncExtraction, then the year's checklist returns checkListItemId, expectedForms and supportingItems with documentId, documentType, documentName and createDate. A separate tax-document lookup resolves the vault as entities.entityKey.

How does the app authenticate filers?

Filers sign in with an Intuit account. Later calls send an OAuth 2 Bearer access token plus a request-correlation header, and some document and checklist clients also attach a session ticket. The account profile lookup returns givenName, familyName, email and pseudonymId for the signed-in profile.

Apps similar to TurboTax: File Your Tax Return

  • H&R Block — H&R Block sells digital tax-preparation software in Free, Deluxe, Premium and Self-Employed editions that import photos of W-2 forms, e-file federal returns, and pair online filers with a tax professional through Tax Pro Review and Tax Pro Go.
  • TaxAct — TaxAct is a Cedar Rapids, Iowa tax-preparation company owned by Cinven that sells filing software for individuals, small businesses and tax professionals and is a member of the IRS Free File Alliance.
  • TaxSlayer — TaxSlayer is an Augusta, Georgia tax-software firm that offers consumer online filing and TaxSlayer Pro for accountants, supplies software for the IRS VITA and TCE programs, and participates in IRS Free File.
  • FreeTaxUSA — FreeTaxUSA is an IRS Free File Alliance member that prepares and e-files federal returns for eligible taxpayers and includes a state return, remaining in the program after TurboTax and H&R Block left.
  • Cash App Taxes — Cash App Taxes, operated by Cash App Taxes, Inc. under Block, Inc., is an authorized IRS e-file provider that files U.S. federal and state returns from a Cash App account for W-2, 1099, self-employment and investment income.
  • Jackson Hewitt — Jackson Hewitt is a U.S. tax-preparation company that files individual returns through retail offices and its ProFiler software, including electronic filing.

More Business apps

Topics

  • TurboTax API
  • tax return status
  • e-file returnStatus
  • refund amount isRefund
  • W-2 document checklist
  • Intuit tax documents
  • fedReturnState productId
  • TurboTax identity profile

Need this app's data API integrated?

We deliver scoped integrations for any named app — from USD 500 with source-code handoff, or hosted access billed per call. Tell us the data you need.

  • NDA + SOW on every engagement
  • Delivery in 3–7 days
  • Payment only after acceptance
  • Work scoped to authorized use

Get a quote