TurboTax 申报、退税与文档数据 API

TurboTax: File Your Tax Return 是 Intuit Inc. 面向美国个人所得税申报的安卓客户端。用户登录 Intuit 账户后，可通过相机扫描或从雇主、券商处下载来导入 W-2 与 1099 表单，依次完成联邦与州的申报问答，向 IRS 及各州税务机关电子申报，并在原生的退税监控界面中跟踪退税进度。同一外壳还承载 TurboTax Live Assisted 与 Live Full Service：当用户希望由 CPA 或注册税务代理（enrolled agent）通过视频协助时即可使用；此外还有 My TurboTax 年度看板、文档清单和往年申报表。当前版本对应 2025 税年（上一税年为 2024）。它是 Intuit 美国个人报税业务的手机入口，在工资与投资类申报场景中与 H&R Block、TaxAct、Cash App Taxes 和 FreeTaxUSA 同台竞争。

联邦与州的申报记录按税务机关分别携带 returnStatus 与 taxAuthority，退税监控的金额则以 amount 和 isRefund 按机关为键给出。文档清单条目在 W-2 或 1099 上传之后会提供 checkListItemId、expectedForms 以及相应的 documentId。entityKey 用于定位该年度的消费者税务文档库；My TurboTax 看板上的 fedReturnState 与 productId 则告诉宿主应用，当前登录年度使用的是哪个产品版本、联邦申报进行到哪一步。

发薪、预支现金和记账类系统借助这些字段，在划转资金或关联扫描的工资单据之前，先确认电子申报是否已被接受，以及是退税还是应补税额。openData Studio 把同样的税年对象变成可调用的开放数据。

应用截图

API 端点一览

以下端点与请求/响应示例均依据应用界面推导重构，为示意说明，并非实际抓包。

My TurboTax 年度看板状态
GET /v1/filings/{taxYear}/overview openfinance
读取 My TurboTax 年度首页：productId 产品版本、fedReturnState 联邦申报进度、isFFA 免费申报标志、taxPrepDelegated（Live Full Service 交接）以及 ttoDownLevel。
认证方式：登录 Intuit 账户后签发的 OAuth 2 Bearer 访问令牌（Authorization: Bearer），外加请求关联头；部分客户端还会带可选的会话票据头。
- 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"}
}
```
未开始年度看板
GET /v1/filings/{taxYear}/intake-state openfinance
加载 2025 年申报表分配之前、尚未开始的 My TurboTax 年度卡片（isSkipYear），并为统一安卓外壳加上标记。
认证方式：登录 Intuit 账户后签发的 OAuth 2 Bearer 访问令牌（Authorization: Bearer），外加请求关联头。
- isSkipYear
```
GET /v1/filings/2025/intake-state?unifiedShell=true HTTP/1.1
Authorization: Bearer <access_token>
Accept: application/json
```
```
{
  "isSkipYear": false
}
```
电子申报状态（精简版）
GET /v1/submissions/status openfinance
返回该年度联邦与州机关的精简电子申报状态：taxYear，以及每一行的 taxAuthority 与 returnStatus。
认证方式： OAuth 2 Bearer 访问令牌（Authorization: Bearer）。税年实体由已登录的申报表确定，并附带请求关联头。
- 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"
      }
    ]
  }
}
```

所得税申报表列表

GET /v1/returns openfinance

列出用户的所得税申报表（taxYear、productType、efileStatus），供往年与当年切换器使用。

认证方式： OAuth 2 Bearer 访问令牌（Authorization: Bearer），外加请求关联头。

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"
    }
  ]
}

消费者税务文档
GET /v1/vaults/{taxYear}/keys opendata
解析该年度消费者税务文档库的键（entities[].entityKey），供 Full Service 与文档清单使用。
认证方式： OAuth 2 Bearer 访问令牌（Authorization: Bearer），外加请求关联头。
- entities.entityKey
```
GET /v1/vaults/2025/keys HTTP/1.1
Authorization: Bearer <access_token>
Accept: application/json
```
```
{
  "entities": [
    {
      "entityKey": "ctd-2025-8f21c4a1"
    }
  ]
}
```

税年文档清单

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

返回该年度的文档清单：数量统计，以及带有 checkListItemId、expectedForms 和相应 documentId 行的条目（在 W-2 或 1099 关联之后出现）。

认证方式： OAuth 2 Bearer 访问令牌（Authorization: Bearer），由共享的请求头拦截器附加；若无法生成请求头，调用会被拒绝。同时附带请求关联头。

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"
        }
      ]
    }
  ]
}

开始税务文档上传
POST /v1/uploads/prepare opendata
开启一次受保护的文档上传（syncExtraction、folderId、uploadDataList），让扫描的 W-2 或 1099 进入该年度的文档库。
认证方式： OAuth 2 Bearer 访问令牌（Authorization: Bearer），用于接收 W-2 与 1099 影像的受保护文档服务，并带有按客户端区分的授权属性和请求关联头。
- 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"
}
```
文档库文件列表
GET /v1/files opendata
列出用户文档库中已有的文档（Smart Docs 列表）：documentId、documentType、documentName、createDate。
认证方式： OAuth 2 Bearer 访问令牌（Authorization: Bearer），带有按客户端区分的授权属性；缺少 Bearer 令牌时调用失败。
- 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"
    }
  ]
}
```

退税与应补税额

POST /v1/refunds/balance openfinance

按机关查询退税或应补税额，返回 amount 与 isRefund（附带联邦与州的区分标志），供原生退税监控界面使用。

认证方式： OAuth 2 Bearer 访问令牌（Authorization: Bearer），外加请求关联头。

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
    }
  ]
}

分配报税会话

POST /v1/filing-sessions/allocate openfinance

为该年度申报表分配一个 TurboTax Online 申报问答会话：resourceOwnerId、dpEntityKey、swimlane 与 readOnly。

认证方式： OAuth 2 Bearer 访问令牌（Authorization: Bearer）。请求体携带登录时获得的 authId，并附带请求关联头。

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"
}

获取雇主税务数据
POST /v1/connections/import openbanking
发起税务数据导入连接，以便从工资单或券商提供方拉取 W-2/1099 数据；响应包含 channelId、connectionId 与 connectionSettings。
认证方式： OAuth 2 Bearer 访问令牌（Authorization: Bearer），外加指向工资单或券商提供方链接的连接请求头，并附带请求关联头。
- 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 账户资料
POST /v1/me/profile osint
读取已登录的 Intuit 个人账户：givenName、familyName、email、pseudonymId 与 uid，这些字段贯穿 TurboTax、Credit Karma 关联和 Live 专家分配。
认证方式：由原生登录建立的 Intuit 账户会话；后续的资料调用会发送 OAuth 2 Bearer 访问令牌。
- 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]"
}
```

数据类别

所得税申报表
电子申报状态
退税
税务文档
W-2/1099 导入
身份信息

数据使用场景与案例

退税与应补税额运营
发薪或预支现金类产品可以轮询 incomeTaxGetRefundBalanceDue，并关联 agency、amount 与 isRefund（以及 RefundItem.isFederalRefundData），在 IRS 接受申报后决定是展示退税预支优惠，还是推送应补税额提醒。
电子申报受理台
报税季客服台可以监控 FilingInfo.agencyReturnInformation 各行（taxAuthority 加 returnStatus）以及 TaxReturn.efileStatus，让坐席无需打开申报问答，就能知道哪一份联邦或州申报仍是 TRANSMITTED、哪一份已 ACCEPTED。
面向记账的 W-2 文档库同步
记账系统可在 start-upload 之后读取清单中的 supportingItems.documentId / documentType，再从消费者税务文档中取得该年度的 entityKey，使同一张喂给 TurboTax 的 W-2 影像也能进入总账。
Intuit 身份匹配
账户关联流程可以在绑定税年之前，把 Intuit 个人账户中的 givenName、familyName、email 与 pseudonymId，与已有的 Credit Karma 或 QuickBooks 登录进行比对。

常见问题

TurboTax 暴露哪些申报状态字段？

精简版电子申报状态载荷中的每个机关行都带有 taxAuthority（例如 IRS 或州税务局 FTB）和 returnStatus，嵌套在 filing.taxYear 之下。申报表列表则按 taxYear 补充 efileStatus 与 productType，宿主无需打开申报问答，就能区分 Deluxe 与 Premier。

退税与应补税额是如何表示的？

退税与应补税额查询会为每个联邦或州机关返回 agency、amount 和 isRefund。应用内的退税监控把它们显示为独立的联邦与州数字，因此退税与应补税额不会混在一起。

W-2 上传之后会留下哪些文档字段？

上传接收 folderId 和 syncExtraction，随后该年度的清单会返回 checkListItemId、expectedForms，以及带有 documentId、documentType、documentName 和 createDate 的 supportingItems。另有一个税务文档查询把文档库解析为 entities.entityKey。

应用如何对报税用户进行鉴权？

用户使用 Intuit 账户登录。之后的调用会携带 OAuth 2 Bearer 访问令牌和请求关联头，部分文档与清单客户端还会附带会话票据。账户资料查询会为已登录用户返回 givenName、familyName、email 和 pseudonymId。

与 TurboTax: File Your Tax Return 相似的应用

H&R Block — H&R Block 提供 Free、Deluxe、Premium 与 Self-Employed 等数字报税软件，可导入 W-2 照片、电子申报联邦税表，并通过 Tax Pro Review 与 Tax Pro Go 为在线申报者匹配税务专业人员。
TaxAct — TaxAct 是总部位于爱荷华州锡达拉皮兹、由 Cinven 控股的报税软件公司，面向个人、小企业和税务专业人士提供申报软件，并加入 IRS Free File Alliance。
TaxSlayer — TaxSlayer 是总部位于佐治亚州奥古斯塔的报税软件公司，提供面向消费者的在线申报和面向会计师的 TaxSlayer Pro，同时为 IRS 的 VITA、TCE 项目提供软件，并参与 IRS Free File。
FreeTaxUSA — FreeTaxUSA 是 IRS Free File Alliance 成员，为符合条件的纳税人准备并电子申报联邦税表，且包含州税申报；在 TurboTax 与 H&R Block 退出该项目后仍继续参与。
Cash App Taxes — Cash App Taxes 由 Block, Inc. 旗下的 Cash App Taxes, Inc. 运营，是获授权的 IRS 电子申报服务商，可从 Cash App 账户申报美国联邦与州税，覆盖 W-2、1099、自雇与投资收益。
Jackson Hewitt — Jackson Hewitt 是美国报税服务公司，通过门店和自有 ProFiler 软件为个人办理报税，并支持电子申报。

需要集成这个 App 的数据 API？

我们可为任意指定 App 交付定制集成——源码交付 USD 500 起，或托管 API 按调用计费。告诉我们您需要的数据即可。

每个项目均签 NDA 与 SOW
3–7 天交付
验收通过后才付款
仅在授权范围内作业

获取报价

TurboTax 申报、退税与文档数据 API

应用截图

API 端点一览

My TurboTax 年度看板状态

未开始年度看板

电子申报状态（精简版）

所得税申报表列表

消费者税务文档

税年文档清单

开始税务文档上传

文档库文件列表

退税与应补税额

分配报税会话

获取雇主税务数据

Intuit 账户资料

数据类别

数据使用场景与案例

退税与应补税额运营

电子申报受理台

面向记账的 W-2 文档库同步

Intuit 身份匹配

常见问题

与 TurboTax: File Your Tax Return 相似的应用

更多企业办公类应用

ADP Mobile Solutions

Box

CryptoRush: Crypto Simulator

Darwinbox

相关主题

需要集成这个 App 的数据 API？

TurboTax 申报、退税与文档数据 API

应用截图

API 端点一览

My TurboTax 年度看板状态

未开始年度看板

电子申报状态（精简版）

所得税申报表列表

消费者税务文档

税年文档清单

开始税务文档上传

文档库文件列表

退税与应补税额

分配报税会话

获取雇主税务数据

Intuit 账户资料

数据类别

数据使用场景与案例

退税与应补税额运营

电子申报受理台

面向记账的 W-2 文档库同步

Intuit 身份匹配

常见问题

相关应用

与 TurboTax: File Your Tax Return 相似的应用

更多企业办公类应用

ADP Mobile Solutions

Box

CryptoRush: Crypto Simulator

Darwinbox

相关主题

需要集成这个 App 的数据 API？