Developer Platform

TaxWallet API Documentation

A RESTful API for the workflows behind modern tax preparation — identity, taxpayers, e-file and returns, documents and OCR, bank products, and notifications. Built for partners, service bureaus, and software integrators building on the six TaxWallet API services.

Read the docs

Powering tax preparation across 50+ offices and 30,000+ returns since 2022.

Introduction

The TaxWallet API is tax infrastructure exposed as a clean, RESTful interface. It is the same engine that powers tax preparation across 50+ offices and more than 30,000 returns since 2022, made available so you can build the tax workflow directly into your own product.

It is designed for three audiences:

  • Partners — embedding tax preparation and e-file into an existing platform.
  • Service bureaus — managing many preparers and offices through a single integration.
  • Software integrators — building new experiences on top of the six TaxWallet API services.

Everything is organized around six services: Authentication & Identity, Taxpayers / Citizens, E-File & Returns, Documents & OCR, Payments & Bank Products, and Notifications. Each is documented below with example endpoints, requests, and responses.

Conventions. All requests and responses are JSON. Resource paths are versioned under /v1. Amounts are integer cents with an explicit currency. Timestamps are ISO 8601 (UTC).

Base URLs

The API is available in two independent environments. They do not share data — credentials, taxpayers, and returns created in the sandbox never appear in production.

EnvironmentBase URLUse for
ProductionReleased when tests passLive taxpayers, real e-file transmissions.
Sandboxhttps://sandbox.taxwallet.aiDevelopment and testing with simulated data.

Examples throughout this page target the sandbox (https://sandbox.taxwallet.ai) so they are safe to copy and run. The production host is published here on release — it goes live once the full test suite passes.

Authentication

Every request is authenticated with a credential pair sent as request headers: a Code that identifies your account and a License key (your secret API key). Both are issued to you on approval.

Header format

X-TaxWallet-Code: <YOUR_CODE>
X-TaxWallet-License: <YOUR_LICENSE_KEY>
Accept: application/json

Keep your License key secret. Send it only from server-side code, never from a browser or mobile client. Keys are issued on approval and can be rotated at any time — if a key is exposed, request a rotation immediately.

Some integrations exchange the credential pair for a short-lived bearer token at POST /v1/auth/token, then send that token as Authorization: Bearer … on subsequent calls. See Authentication & Identity below.

API Services

The platform is composed of six services. Each exposes a focused set of resources; example endpoints follow.

Authentication & Identity

Exchange credentials for tokens, manage organizations and preparer members, and resolve the identity of the account behind a request.

POST/v1/auth/token

Exchange your Code + License key for a short-lived bearer token.

curl -X POST \
  'https://sandbox.taxwallet.ai/v1/auth/token' \
  -H 'X-TaxWallet-Code: <YOUR_CODE>' \
  -H 'X-TaxWallet-License: <YOUR_LICENSE_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"grantType":"client_credentials"}'
Response · 200 OK
{
  "accessToken": "tw_tok_9f2c…",
  "tokenType": "Bearer",
  "expiresIn": 3600
}
GET/v1/organizations

List the organizations (offices / EFINs) your account can act on behalf of.

curl -X GET \
  'https://sandbox.taxwallet.ai/v1/organizations' \
  -H 'X-TaxWallet-Code: <YOUR_CODE>' \
  -H 'X-TaxWallet-License: <YOUR_LICENSE_KEY>' \
  -H 'Accept: application/json'
Response · 200 OK
{
  "data": [
    { "id": "org_4ab21", "name": "Northwind Tax", "officeCount": 3 }
  ],
  "nextCursor": null
}
GET/v1/organizations/{orgId}/members

List preparers and staff who belong to an organization.

curl -X GET \
  'https://sandbox.taxwallet.ai/v1/organizations/org_4ab21/members' \
  -H 'X-TaxWallet-Code: <YOUR_CODE>' \
  -H 'X-TaxWallet-License: <YOUR_LICENSE_KEY>' \
  -H 'Accept: application/json'
Response · 200 OK
{
  "data": [
    { "id": "mbr_77c0", "name": "Dana Cole", "role": "preparer" }
  ],
  "nextCursor": null
}

Taxpayers / Citizens

Create and retrieve taxpayer records (“citizens”) — the people a return is filed for, including filing status and dependents.

GET/v1/citizens?limit=2

List taxpayer records with cursor pagination.

curl -X GET \
  'https://sandbox.taxwallet.ai/v1/citizens?limit=2' \
  -H 'X-TaxWallet-Code: <YOUR_CODE>' \
  -H 'X-TaxWallet-License: <YOUR_LICENSE_KEY>' \
  -H 'Accept: application/json'
Response · 200 OK
{
  "data": [
    {
      "id": "ctz_3kd91m",
      "firstName": "Avery",
      "lastName": "Stone",
      "filingStatus": "single"
    }
  ],
  "nextCursor": null
}
POST/v1/citizens

Create a taxpayer record.

curl -X POST \
  'https://sandbox.taxwallet.ai/v1/citizens' \
  -H 'X-TaxWallet-Code: <YOUR_CODE>' \
  -H 'X-TaxWallet-License: <YOUR_LICENSE_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"firstName":"Avery","lastName":"Stone","filingStatus":"single"}'
Response · 200 OK
{
  "id": "ctz_3kd91m",
  "firstName": "Avery",
  "lastName": "Stone",
  "filingStatus": "single",
  "createdAt": "2026-01-15T12:00:00Z"
}
GET/v1/citizens/{citizenId}

Retrieve a single taxpayer record by ID.

curl -X GET \
  'https://sandbox.taxwallet.ai/v1/citizens/ctz_3kd91m' \
  -H 'X-TaxWallet-Code: <YOUR_CODE>' \
  -H 'X-TaxWallet-License: <YOUR_LICENSE_KEY>' \
  -H 'Accept: application/json'
Response · 200 OK
{
  "id": "ctz_3kd91m",
  "firstName": "Avery",
  "lastName": "Stone",
  "filingStatus": "single",
  "dependents": []
}

E-File & Returns

Build a return, calculate it, transmit the e-file manifest to the agency, and poll for acknowledgments (accepted / rejected).

POST/v1/returns

Create a tax return for a taxpayer and tax year.

curl -X POST \
  'https://sandbox.taxwallet.ai/v1/returns' \
  -H 'X-TaxWallet-Code: <YOUR_CODE>' \
  -H 'X-TaxWallet-License: <YOUR_LICENSE_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"citizenId":"ctz_3kd91m","taxYear":2025,"formType":"1040"}'
Response · 200 OK
{
  "id": "ret_55ab12",
  "taxYear": 2025,
  "formType": "1040",
  "status": "draft"
}
POST/v1/returns/{returnId}/calculate

Run the tax engine and compute refund or balance due (integer cents).

curl -X POST \
  'https://sandbox.taxwallet.ai/v1/returns/ret_55ab12/calculate' \
  -H 'X-TaxWallet-Code: <YOUR_CODE>' \
  -H 'X-TaxWallet-License: <YOUR_LICENSE_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{}'
Response · 200 OK
{
  "id": "ret_55ab12",
  "status": "ready",
  "refundOrDue": { "amount": 125000, "currency": "USD" }
}
POST/v1/efiles

Transmit the e-file manifest for a return to the filing agency.

curl -X POST \
  'https://sandbox.taxwallet.ai/v1/efiles' \
  -H 'X-TaxWallet-Code: <YOUR_CODE>' \
  -H 'X-TaxWallet-License: <YOUR_LICENSE_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"returnId":"ret_55ab12"}'
Response · 200 OK
{
  "id": "efl_91xk20",
  "returnId": "ret_55ab12",
  "status": "transmitted",
  "submittedAt": "2026-02-01T09:30:00Z"
}
GET/v1/efiles/{efileId}

Get the current e-file status, including the agency acknowledgment.

curl -X GET \
  'https://sandbox.taxwallet.ai/v1/efiles/efl_91xk20' \
  -H 'X-TaxWallet-Code: <YOUR_CODE>' \
  -H 'X-TaxWallet-License: <YOUR_LICENSE_KEY>' \
  -H 'Accept: application/json'
Response · 200 OK
{
  "id": "efl_91xk20",
  "returnId": "ret_55ab12",
  "formType": "1040",
  "taxYear": 2025,
  "status": "accepted",
  "acknowledgedAt": "2026-02-01T15:12:00Z"
}

Documents & OCR

Upload source documents and extract structured data. The OCR engine recognizes common tax forms — W-2, 1099, 1098, and 1095-A — and returns typed fields.

POST/v1/documents

Upload a document (PDF or image) and attach it to a taxpayer.

curl -X POST \
  'https://sandbox.taxwallet.ai/v1/documents' \
  -H 'X-TaxWallet-Code: <YOUR_CODE>' \
  -H 'X-TaxWallet-License: <YOUR_LICENSE_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"citizenId":"ctz_3kd91m","type":"W2","fileUrl":"https://files.example.com/w2.pdf"}'
Response · 200 OK
{
  "id": "doc_a1b2c3",
  "type": "W2",
  "status": "processing"
}
GET/v1/documents/{documentId}

Retrieve a document and its extracted (OCR) fields once processing completes.

curl -X GET \
  'https://sandbox.taxwallet.ai/v1/documents/doc_a1b2c3' \
  -H 'X-TaxWallet-Code: <YOUR_CODE>' \
  -H 'X-TaxWallet-License: <YOUR_LICENSE_KEY>' \
  -H 'Accept: application/json'
Response · 200 OK
{
  "id": "doc_a1b2c3",
  "type": "W2",
  "status": "extracted",
  "fields": {
    "employer": "Acme Corp",
    "wages": 5820000,
    "federalWithheld": 712000
  }
}
GET/v1/documents?citizenId=ctz_3kd91m

List all documents attached to a taxpayer.

curl -X GET \
  'https://sandbox.taxwallet.ai/v1/documents?citizenId=ctz_3kd91m' \
  -H 'X-TaxWallet-Code: <YOUR_CODE>' \
  -H 'X-TaxWallet-License: <YOUR_LICENSE_KEY>' \
  -H 'Accept: application/json'
Response · 200 OK
{
  "data": [
    { "id": "doc_a1b2c3", "type": "W2", "status": "extracted" },
    { "id": "doc_d4e5f6", "type": "1099", "status": "extracted" }
  ],
  "nextCursor": null
}

Payments & Bank Products

Offer bank products on a return — refund transfers that net preparation fees out of the refund, and taxpayer advances disbursed before the refund settles.

POST/v1/bank-products

Create a refund transfer bank product on a return.

curl -X POST \
  'https://sandbox.taxwallet.ai/v1/bank-products' \
  -H 'X-TaxWallet-Code: <YOUR_CODE>' \
  -H 'X-TaxWallet-License: <YOUR_LICENSE_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"returnId":"ret_55ab12","product":"refund_transfer"}'
Response · 200 OK
{
  "id": "bp_70cd11",
  "returnId": "ret_55ab12",
  "product": "refund_transfer",
  "status": "pending",
  "fees": { "amount": 3995, "currency": "USD" }
}
POST/v1/bank-products/{id}/advance

Request a taxpayer advance against an approved refund transfer.

curl -X POST \
  'https://sandbox.taxwallet.ai/v1/bank-products/bp_70cd11/advance' \
  -H 'X-TaxWallet-Code: <YOUR_CODE>' \
  -H 'X-TaxWallet-License: <YOUR_LICENSE_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"amount":50000,"currency":"USD"}'
Response · 200 OK
{
  "id": "adv_22ff90",
  "bankProductId": "bp_70cd11",
  "amount": { "amount": 50000, "currency": "USD" },
  "status": "approved"
}
GET/v1/bank-products/{id}

Retrieve the current status of a bank product and any disbursements.

curl -X GET \
  'https://sandbox.taxwallet.ai/v1/bank-products/bp_70cd11' \
  -H 'X-TaxWallet-Code: <YOUR_CODE>' \
  -H 'X-TaxWallet-License: <YOUR_LICENSE_KEY>' \
  -H 'Accept: application/json'
Response · 200 OK
{
  "id": "bp_70cd11",
  "product": "refund_transfer",
  "status": "funded",
  "disbursements": [
    { "type": "advance", "amount": 50000, "status": "paid" }
  ]
}

Notifications

Send transactional messages to taxpayers and staff over push, email, and SMS — for example, “your return was accepted” or “documents needed.”

POST/v1/notifications

Send a notification across one or more channels.

curl -X POST \
  'https://sandbox.taxwallet.ai/v1/notifications' \
  -H 'X-TaxWallet-Code: <YOUR_CODE>' \
  -H 'X-TaxWallet-License: <YOUR_LICENSE_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"citizenId":"ctz_3kd91m","channels":["push","sms"],"template":"return_accepted"}'
Response · 200 OK
{
  "id": "ntf_5e6f7a",
  "channels": ["push", "sms"],
  "status": "queued"
}
GET/v1/notifications/{id}

Retrieve delivery status per channel for a notification.

curl -X GET \
  'https://sandbox.taxwallet.ai/v1/notifications/ntf_5e6f7a' \
  -H 'X-TaxWallet-Code: <YOUR_CODE>' \
  -H 'X-TaxWallet-License: <YOUR_LICENSE_KEY>' \
  -H 'Accept: application/json'
Response · 200 OK
{
  "id": "ntf_5e6f7a",
  "status": "delivered",
  "results": [
    { "channel": "push", "status": "delivered" },
    { "channel": "sms", "status": "delivered" }
  ]
}

Integrations we offer

Beyond the core API, the platform ships with managed integration categories so you don't have to assemble the supporting infrastructure yourself. Each is available to approved partners and surfaces through the services above.

Banking & refund-transfer partners

Refund transfers and taxpayer advances through integrated bank product providers, surfaced via Payments & Bank Products.

Identity verification

Identity proofing and knowledge-based checks to confirm a taxpayer before filing.

OCR & document AI

Structured extraction of W-2, 1099, 1098, and 1095-A data from uploaded documents.

E-signature

Capture legally binding signatures on consent forms and the completed return.

SMS & push

Transactional messaging and mobile push for status updates and document requests.

White-label client app

A brandable taxpayer-facing mobile and web app that runs on top of your API account.

Webhooks

Subscribe to webhooks to receive events instead of polling. Register an HTTPS endpoint for your account; we POST a signed JSON payload when an event occurs. Verify the X-TaxWallet-Signature header against your webhook secret before trusting a payload.

Common event types

  • return.calculated
  • efile.transmitted
  • efile.accepted
  • efile.rejected
  • document.extracted
  • bank_product.funded
  • advance.approved
  • notification.delivered

Sample payload

{
  "id": "evt_8a1b2c",
  "type": "efile.accepted",
  "createdAt": "2026-02-01T15:12:00Z",
  "data": {
    "efileId": "efl_91xk20",
    "returnId": "ret_55ab12",
    "taxYear": 2025,
    "status": "accepted"
  }
}

Respond with 2xx within a few seconds. Non-2xx responses are retried with exponential backoff.

Errors & rate limits

The API uses conventional HTTP status codes. Errors return a consistent JSON shape with a stable machine-readable code and a human-readable message.

{
  "error": {
    "code": "validation_error",
    "message": "filingStatus is required.",
    "field": "filingStatus",
    "requestId": "req_d29f1a"
  }
}

Common status codes

StatusCodeMeaning
400validation_errorThe request body failed validation.
401unauthenticatedMissing or invalid credentials.
403forbiddenCredentials lack access to this resource.
404not_foundThe resource does not exist.
409conflictThe request conflicts with current state.
429rate_limitedToo many requests — slow down.
500internal_errorSomething went wrong on our end.

Rate limits

Each response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. When you exceed your limit you receive a 429 with a Retry-After header — back off and retry after the indicated interval.

Sandbox & going live

Build and test against the sandbox first. It mirrors production behavior with simulated data — e-file transmissions are acknowledged synthetically, and bank products fund without moving real money.

  1. 1

    Request access

    Use the Request API access button. We issue a sandbox Code and License key on approval.

  2. 2

    Build against sandbox

    Point your integration at https://sandbox.taxwallet.ai and exercise the full workflow — create a taxpayer, build a return, calculate, transmit, and read back the acknowledgment.

  3. 3

    Request production access

    Production is released once the full test suite passes. When it goes live we publish the production host and issue your credentials — no code changes beyond the base URL and credentials.

Ready to build on TaxWallet?

Tell us what you're building and we'll issue sandbox credentials so you can start integrating today.