# Introduction One API to estimate, save and pay your customers’ quarterly taxes to the IRS and every state. Self-employed people owe the IRS and their state four times a year, and nobody takes it out of a paycheck. With this API your product does it for them: work out what they owe, save it from every deposit, pay both agencies on time and keep the receipt. - [Quickstart](/developers/docs/quickstart): From a sandbox key to a scheduled payment in five minutes. - [API reference](/developers/docs/reference): Every endpoint, field and error. - [Test values](/developers/docs/testing): Make any check fail or any payment bounce on purpose. - [Build with AI](/developers/docs/ai): Tool definitions your assistant can call today. ## Your first request Paste this with a sandbox key. It returns what a freelancer in New York owes this quarter, federal and state. ```bash curl -X POST "https://api.workmade.com/v1/estimates" \ -H "Authorization: Bearer $WORKMADE_KEY" \ -H "Content-Type: application/json" \ -d '{ "taxpayer_id": "tp_8Kq2", "quarter": "2026-Q4", "income_ytd": 8420000, "expenses_ytd": 1265000 }' ``` ## How it fits together | Step | What happens | Endpoint | | --- | --- | --- | | Estimate | Federal and state amounts, and the minimum that avoids a penalty | `POST /v1/estimates` | | Save | A share of every deposit, held in an account in your customer’s name | `POST /v1/set_asides` | | Pay | The IRS and the state before the due date, electronically or by check | `POST /v1/payments` | | Track | An event at every step, with the confirmation and receipt | Webhooks | ## What it doesn’t do - It doesn’t file annual returns. Draft returns are in beta, and a CPA files them. - It doesn’t lend money. If a customer is short, you hear about it before the due date. - It doesn’t cover payroll, sales tax or business income tax. Only individual estimated tax. - Money never passes through your accounts or ours. It only goes to a tax agency or back to your customer. > This is the design-partner preview, version `2026-11-01`. Fields may change before general availability; every change is in the [changelog](changelog). --- # Quickstart From a sandbox key to a scheduled payment in five steps. Nothing real moves in sandbox. ### 1. Get a sandbox key [Ask us for a sandbox key](/developers#partner) and keep it in an environment variable. ```bash export WORKMADE_KEY=sk_test_51Qp8ZkTvR2mWb7Nc4f2a ``` ### 2. Add a taxpayer Checks start as soon as they’re created. In sandbox they pass in about a second. ```bash curl -X POST "https://api.workmade.com/v1/taxpayers" \ -H "Authorization: Bearer $WORKMADE_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Maya Ortiz", "email": "maya@ortiz.studio", "state": "NY", "ssn": "123-45-6789", "date_of_birth": "1991-04-22", "bank_account": { "routing_number": "021000021", "account_number": "000123456789" } }' ``` ### 3. Get an estimate Send what they’ve earned and spent so far this year. Amounts are in cents. ```bash curl -X POST "https://api.workmade.com/v1/estimates" \ -H "Authorization: Bearer $WORKMADE_KEY" \ -H "Content-Type: application/json" \ -d '{ "taxpayer_id": "tp_8Kq2", "quarter": "2026-Q4", "income_ytd": 8420000, "expenses_ytd": 1265000 }' ``` ### 4. Start saving Save 24% of every deposit you report. The customer approves the bank debit once. ```bash curl -X POST "https://api.workmade.com/v1/set_asides" \ -H "Authorization: Bearer $WORKMADE_KEY" \ -H "Content-Type: application/json" \ -d '{ "taxpayer_id": "tp_8Kq2", "rule": "percent_of_deposits", "percent": 24 }' ``` ### 5. Schedule the payments One request books the IRS and the state. We pick the dates so both land before the due date. ```bash curl -X POST "https://api.workmade.com/v1/payments" \ -H "Authorization: Bearer $WORKMADE_KEY" \ -H "Content-Type: application/json" \ -d '{ "taxpayer_id": "tp_8Kq2", "quarter": "2026-Q4" }' ``` Want to see them settle without waiting until January? [Skip ahead in time](testing#move-time-forward) in sandbox. ## Next - [Listen for webhooks](/developers/docs/webhooks): Hear about every payment as it moves. - [Go live](/developers/docs/authentication): Swap `sk_test_` for `sk_live_`. Nothing else changes. --- # Authentication Send your secret key as a bearer token. Sandbox and live use the same code. ```bash curl "https://api.workmade.com/v1/taxpayers" \ -H "Authorization: Bearer $WORKMADE_KEY" ``` | | Sandbox | Live | | --- | --- | --- | | Key starts with | `sk_test_` | `sk_live_` | | Money moves | Never | Yes | | Checks | Instant, with [test values](testing) | Real, usually under 2 seconds | | Rate limit | 25 requests a second | 100 requests a second | > Keep keys on your servers. Never put one in a mobile app, a browser or a git repo. If one leaks, delete it in the dashboard and it stops working at once. ## Idempotency Send an `Idempotency-Key` header on every `POST`. If a request times out, retry it with the same key and you’ll never pay a quarter twice. Keys last 24 hours. ```bash curl -X POST "https://api.workmade.com/v1/payments" \ -H "Authorization: Bearer $WORKMADE_KEY" \ -H "Idempotency-Key: 6f1c2b7e-q4-tp_8Kq2" \ -H "Content-Type: application/json" \ -d '{ "taxpayer_id": "tp_8Kq2", "quarter": "2026-Q4" }' ``` ## Versions Your account is pinned to the version that was current when you made your first request. To try a newer one on a single request, send `WorkMade-Version: 2026-11-01`. --- # Test values In sandbox, these values make things go wrong on purpose, so you can build for every case before you go live. ## Taxpayers | Send | What happens | | --- | --- | | `ssn` ending in `0000` | Identity check fails | | `ssn` ending in `1111` | Identity check waits for a photo ID | | `ein` of `00-0000000` | Business tax ID doesn’t match IRS records | | `name` containing `Sanctioned` | Sanctions check flags the taxpayer | | Anything else | Every check passes | ## Bank accounts | `account_number` ends in | What happens | | --- | --- | | `0002` | The tax payment bounces back: account closed | | `0003` | Saving fails: not enough money in the account | | Anything else | Debits and payments succeed | ## Move time forward Quarterly taxes take months. In sandbox you can jump ahead and watch payments send, settle and fire webhooks in seconds. ```bash curl -X POST "https://api.workmade.com/v1/test/advance_time" \ -H "Authorization: Bearer $WORKMADE_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "2027-01-16" }' ``` --- # Estimates How we work out what a customer owes, and how to keep it current. Send income and expenses for the year so far. We return federal income tax and self-employment tax, the state’s estimate, and the safe-harbor minimum: the smallest amount that avoids an underpayment penalty. - Recalculate whenever income changes. The same taxpayer and quarter always return one estimate, updated in place. - Safe harbor uses 100% of last year’s tax, or 110% when last year’s income was over $150,000. Send `prior_year_tax` if you have it. - If income is lumpy, we use the annualized method so nobody overpays early in the year. ## Every state’s calendar Most states share the federal dates. Some don’t, and the estimate always uses the state’s own. | State | Form | Due dates (2026 tax year) | Split | | --- | --- | --- | --- | | Federal | 1040-ES | Apr 15, Jun 15, Sep 15, Jan 15 | 25% each | | California | 540-ES | Apr 15, Jun 15, Jan 15 | 30%, 40%, 0%, 30% | | Virginia | 760ES | May 1, Jun 15, Sep 15, Jan 15 | 25% each | | Hawaii | N-200V | Apr 20, Jun 22, Sep 21, Jan 20 | 25% each | | New York | IT-2105 | Same as federal | 25% each | > The nine states with no income tax (AK, FL, NV, NH, SD, TN, TX, WA, WY) return `state: null`. We pay federal only. --- # Saving money Set aside a share of every deposit, so the money is there when the quarter is due. Choose a rule. Money is debited from the customer’s bank into an account in their name at our partner bank. It can only go to a tax agency or back to the account it came from. | Rule | How it works | | --- | --- | | `percent_of_deposits` | Report each deposit with `POST /v1/deposits` and we save that share of it | | `fixed` | A set amount on a schedule: `weekly`, `monthly` or before each due date | The customer approves the bank debit once, inside your product. We keep a record of the approval. ## When someone is short If the balance won’t cover the quarter, you get a `balance.short` event 10 days before the first payment sends, with the amount missing. We never lend the difference. --- # Payments One request pays the IRS and the state, on time, with a receipt. We schedule each payment to land before its due date. Where the agency takes electronic payments we send them electronically. Where it doesn’t, we print a check with the state’s own form, mail it early and track it to delivery. ## A backup for every payment If one way fails, we try the next automatically. A bounced transfer never becomes a missed deadline. Every attempt is on the payment’s `attempts` list. ## What a payment goes through | Status | Means | | --- | --- | | `scheduled` | Booked. You can still cancel it. | | `sent` · `mailed` | On its way to the agency. | | `settled` · `delivered` | The agency has it. `confirmation` is filled in. | | `returned` | It bounced. `attempts` says why, and we’ll retry if we can. | | `canceled` | You canceled it before it sent. | --- # Coverage Which tax agencies the API pays for the 2026 tax year, and how each one is paid. > Payments through the API are not live yet. This is the list it pays at launch, the same agencies WorkMade’s own product pays for its members. In sandbox today you can add taxpayers, run checks, get estimates and book test payments. The IRS, every state with a personal income tax, and Washington, DC. Most agencies take a mailed check with their own payment voucher, and we fill in that voucher for each payment. A few only take estimated payments on their own website. | Agency | Form | How it’s paid | | --- | --- | --- | | Internal Revenue Service | Form 1040-ES | Mailed check with Form 1040-ES | | Alabama Department of Revenue | Form 40ES | Mailed check with Form 40ES | | Arizona Department of Revenue | Form 140ES | Mailed check with Form 140ES | | Arkansas Department of Finance and Administration | AR1000ES | Mailed check with Form AR1000ES | | California Franchise Tax Board | Form 540-ES | Mailed check with Form 540-ES | | Colorado Department of Revenue | DR 0104EP | Mailed check with Form DR 0104EP | | Connecticut Department of Revenue Services | CT-1040ES | Mailed check with Form CT-1040ES | | Delaware Division of Revenue | PIT-EST | Mailed check with Form PIT-EST | | DC Office of Tax and Revenue | D-40ES | Mailed check with Form D-40ES | | Georgia Department of Revenue | Form 500-ES | Mailed check with Form 500-ES | | Hawaii Department of Taxation | N-200V | Mailed check with Form N-200V | | Idaho State Tax Commission | Form 51 | Mailed check with Form 51 | | Illinois Department of Revenue | IL-1040-ES | Mailed check with Form IL-1040-ES | | Indiana Department of Revenue | ES-40 | Mailed check with Form ES-40 | | Iowa Department of Revenue | IA 1040ES | On the state’s website | | Kansas Department of Revenue | K-40ES | Mailed check with Form K-40ES | | Kentucky Department of Revenue | 740-ES | Mailed check with Form 740-ES | | Louisiana Department of Revenue | IT-540ES | Mailed check with Form IT-540ES | | Maine Revenue Services | 1040ES-ME | Mailed check with Form 1040ES-ME | | Comptroller of Maryland | Form PV | Mailed check with Form PV | | Massachusetts Department of Revenue | Form 1-ES | Mailed check with Form 1-ES | | Michigan Department of Treasury | MI-1040ES | Mailed check with Form MI-1040ES | | Minnesota Department of Revenue | M14 | On the state’s website | | Mississippi Department of Revenue | Form 80-106 | Mailed check with Form 80-106 | | Missouri Department of Revenue | MO-1040ES | Mailed check with Form MO-1040ES | | Montana Department of Revenue | Form IT | Mailed check with Form IT | | Nebraska Department of Revenue | Form 1040N-ES | Mailed check with Form 1040N-ES | | New Jersey Division of Taxation | NJ-1040-ES | Mailed check with Form NJ-1040-ES | | New Mexico Taxation and Revenue Department | PIT-ES | Mailed check with Form PIT-ES | | New York State Department of Taxation and Finance | IT-2105 | Mailed check with Form IT-2105 | | North Carolina Department of Revenue | NC-40 | Mailed check with Form NC-40 | | North Dakota Office of State Tax Commissioner | ND-1ES | Mailed check with Form ND-1ES | | Ohio Department of Taxation | IT ES (OUPC) | Mailed check with Form IT ES (OUPC) | | Oklahoma Tax Commission | OW-8-ES | Mailed check with Form OW-8-ES | | Oregon Department of Revenue | OR-40-V | Mailed check with Form OR-40-V | | Pennsylvania Department of Revenue | PA-40 ES (I) | Mailed check with Form PA-40 ES (I) | | Rhode Island Division of Taxation | RI-1040ES | Mailed check with Form RI-1040ES | | South Carolina Department of Revenue | SC1040ES | Mailed check with Form SC1040ES | | Utah State Tax Commission | TC-546 | Mailed check with Form TC-546 | | Vermont Department of Taxes | IN-114 | Mailed check with Form IN-114 | | Virginia Department of Taxation | Form 760ES | Mailed check with Form 760ES | | West Virginia Tax Division | IT-140ES | Mailed check with Form IT-140ES | | Wisconsin Department of Revenue | Form 1-ES | On the state’s website | The nine states with no income tax (AK, FL, NV, NH, SD, TN, TX, WA, WY) aren’t listed. Customers there pay federal only. Want this list in code? It’s the `get_coverage` tool on the [docs MCP server](ai#docs-your-assistant-can-read). --- # Verification Know who you’re paying for before any money moves. Checks run when you create a taxpayer and again before every payment. The result is one yes or no: `ready_to_pay`. | Check | What we confirm | | --- | --- | | Identity | Name, birthday, address and Social Security number, against their bank account | | Bank account | It’s open and in their name | | Business tax ID | The business name matches the IRS record for that EIN | | Preparer ID | The CPA filing for them has an active PTIN | | Sanctions | They’re not on a US Treasury sanctions list | Already ran identity checks yourself? Pass the result in `pass_through` and we won’t ask your customer twice. --- # Webhooks We tell your servers when anything changes, so you never have to poll. Add an endpoint in the dashboard or with the API. Each event carries the full object, so you rarely need a second request. | Event | When | | --- | --- | | `verification.completed` | Checks finished, with `ready_to_pay` | | `estimate.updated` | What a customer owes changed | | `balance.short` | Savings won’t cover the quarter | | `payment.scheduled` | A payment is booked | | `payment.settled` | The agency has the money | | `payment.returned` | A payment bounced, with the reason | | `return.drafted` | A draft return is ready (beta) | ## Check the signature Every request carries a `WorkMade-Signature` header. Recompute it with your endpoint’s secret and reject anything that doesn’t match or is more than five minutes old. ```js import crypto from "node:crypto" // header looks like: t=1767225600,v1=5257a869e7ec... export function verify(rawBody, header, secret) { const { t, v1 } = Object.fromEntries(header.split(",").map(p => p.split("="))) if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex") return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1)) } ``` Reply with any `2xx` within 10 seconds. If you don’t, we retry with backoff for three days. Events can arrive out of order, so use the object’s `status`, not the order you received them in. --- # Build with AI Let your assistant answer “what do I owe?” and pay it, with your customer’s go-ahead. Give your model these tools. Each one maps to a single request. Keep a person in the loop: schedule payments only after your customer says yes, and always send an idempotency key. ```json [ { "name": "get_quarter", "description": "What a taxpayer owes this quarter, federal and state, and how much is saved.", "input_schema": { "type": "object", "properties": { "taxpayer_id": { "type": "string" }, "quarter": { "type": "string", "description": "Like 2026-Q4" } }, "required": [ "taxpayer_id", "quarter" ] } }, { "name": "schedule_payments", "description": "Book this quarter’s IRS and state payments. Only call after the user confirms.", "input_schema": { "type": "object", "properties": { "taxpayer_id": { "type": "string" }, "quarter": { "type": "string" } }, "required": [ "taxpayer_id", "quarter" ] } }, { "name": "get_payment", "description": "Where a payment is and its confirmation number.", "input_schema": { "type": "object", "properties": { "payment_id": { "type": "string" } }, "required": [ "payment_id" ] } } ] ``` ## Docs your assistant can read Point your coding assistant at [/llms.txt](/developers/docs/llms.txt) for an index of these docs, or [/llms-full.txt](/developers/docs/llms-full.txt) for all of them in one file. Every page also has a Copy page button. Or add the docs as an MCP server, so Claude, Cursor or ChatGPT can list, search and read every page as tools. It’s read-only and needs no key: `https://www.workmade.com/developers/docs/mcp` ```bash claude mcp add --transport http workmade-docs https://www.workmade.com/developers/docs/mcp ``` ```json { "mcpServers": { "workmade-docs": { "url": "https://www.workmade.com/developers/docs/mcp" } } } ``` --- # Returns At year-end, draft each customer’s federal return from the quarters you already ran. Beta. > Beta for the 2026 tax year. A CPA reviews and files every return. We don’t e-file yet. Drafts cover Form 1040 for sole proprietors with Schedules 1, 2, B, C, SE and 8812, and Forms 8829 and 8995. Every quarterly payment you made through the API is already counted. When a return is outside that scope, it comes back with `status: out_of_scope` and a plain reason in `out_of_scope`, such as depreciation, a Marketplace health plan or a filer aged 65 or over. --- # Overview REST, JSON and bearer keys. Amounts are in cents, dates in ISO 8601. ```bash https://api.workmade.com/v1 ``` ## Errors Errors return an HTTP status and an `error` object with a `code` you can switch on and a `message` you can show. ```json { "error": { "code": "insufficient_set_aside", "message": "Saved $2,100.00 of $2,980.00. Add $880.00 before Jan 12.", "param": null } } ``` | Status | `code` | Means | | --- | --- | --- | | 400 | `invalid_request` | A field is missing or wrong. `param` says which. | | 401 | `authentication_failed` | The key is missing, deleted or for the other environment. | | 404 | `not_found` | No object with that ID. | | 409 | `idempotency_conflict` | Same idempotency key, different request. | | 422 | `insufficient_set_aside` | Not enough saved to pay this quarter. | | 422 | `verification_required` | The taxpayer hasn’t passed checks yet. | | 429 | `rate_limited` | Too many requests. Wait for `Retry-After` seconds. | | 500 | `api_error` | Our fault. Safe to retry with the same idempotency key. | ## Pagination List endpoints return up to `limit` items (default 20, max 100) and `has_more`. Pass the last ID as `starting_after` for the next page. ## Rate limits 100 requests a second in live and 25 in sandbox. Every response carries `RateLimit-Remaining` and `RateLimit-Reset` headers. --- # Taxpayers The person you save and pay taxes for. Checks start the moment one is created. ### Create a taxpayer `POST /v1/taxpayers` Creates the taxpayer and starts verification. | Field | Type | Description | | --- | --- | --- | | `name` (required) | string | Legal name. | | `email` (required) | string | Where we send receipts if you ask us to. | | `state` (required) | string | Two-letter state of residence, like `NY`. | | `ssn` (required) | string | Full Social Security number. Write-only: never returned. | | `date_of_birth` (required) | string | `YYYY-MM-DD`. | | `filing_status` | string | `single`, `married_joint`, `married_separate` or `head_of_household`. Defaults to `single`. | | `business` | object | `name` and `ein`, if they have a business. | | `bank_account` | object | `routing_number` and `account_number` they save from. | | `external_id` | string | Your own ID for this person. | ```bash curl -X POST "https://api.workmade.com/v1/taxpayers" \ -H "Authorization: Bearer $WORKMADE_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Maya Ortiz", "email": "maya@ortiz.studio", "state": "NY", "ssn": "123-45-6789", "date_of_birth": "1991-04-22" }' ``` Response: ```json { "id": "tp_8Kq2", "object": "taxpayer", "name": "Maya Ortiz", "email": "maya@ortiz.studio", "state": "NY", "filing_status": "single", "business": { "name": "Ortiz Studio LLC", "ein_last4": "0921" }, "status": "ready", "ready_to_pay": true, "external_id": "usr_4471", "created": "2026-03-02T15:04:11Z" } ``` ### Retrieve a taxpayer `GET /v1/taxpayers/tp_8Kq2` Returns one taxpayer. ```bash curl "https://api.workmade.com/v1/taxpayers/tp_8Kq2" \ -H "Authorization: Bearer $WORKMADE_KEY" ``` Response: ```json { "id": "tp_8Kq2", "object": "taxpayer", "name": "Maya Ortiz", "email": "maya@ortiz.studio", "state": "NY", "filing_status": "single", "business": { "name": "Ortiz Studio LLC", "ein_last4": "0921" }, "status": "ready", "ready_to_pay": true, "external_id": "usr_4471", "created": "2026-03-02T15:04:11Z" } ``` ### List taxpayers `GET /v1/taxpayers` Newest first. Filter by `status`: `ready`, `verifying` or `short`. ```bash curl "https://api.workmade.com/v1/taxpayers?status=ready&limit=20" \ -H "Authorization: Bearer $WORKMADE_KEY" ``` Response: ```json { "object": "list", "data": [ { "id": "tp_8Kq2", "object": "taxpayer", "name": "Maya Ortiz", "email": "maya@ortiz.studio", "state": "NY", "filing_status": "single", "business": { "name": "Ortiz Studio LLC", "ein_last4": "0921" }, "status": "ready", "ready_to_pay": true, "external_id": "usr_4471", "created": "2026-03-02T15:04:11Z" } ], "has_more": true } ``` --- # Estimates What a taxpayer owes for a quarter, federal and state. ### Create an estimate `POST /v1/estimates` Creates or updates the estimate for that taxpayer and quarter. | Field | Type | Description | | --- | --- | --- | | `taxpayer_id` (required) | string | The taxpayer, like `tp_8Kq2`. | | `quarter` (required) | string | Which quarter, like `2026-Q4`. | | `income_ytd` (required) | integer | Income so far this year, in cents. | | `expenses_ytd` | integer | Business expenses so far this year, in cents. | | `withholding_ytd` | integer | Tax already withheld from any W-2 job, in cents. | | `prior_year_tax` | integer | Last year’s total tax, for the safe-harbor minimum. | ```bash curl -X POST "https://api.workmade.com/v1/estimates" \ -H "Authorization: Bearer $WORKMADE_KEY" \ -H "Content-Type: application/json" \ -d '{ "taxpayer_id": "tp_8Kq2", "quarter": "2026-Q4", "income_ytd": 8420000, "expenses_ytd": 1265000 }' ``` Response: ```json { "id": "est_5Hv2", "object": "estimate", "taxpayer_id": "tp_8Kq2", "quarter": "2026-Q4", "due": "2027-01-15", "federal": { "form": "1040-ES", "amount": 418000 }, "state": { "code": "NY", "form": "IT-2105", "amount": 126500, "due": "2027-01-15" }, "total": 544500, "safe_harbor": { "method": "prior_year_100", "minimum": 418000 }, "created": "2026-10-26T14:22:05Z" } ``` ### Retrieve a quarter `GET /v1/taxpayers/tp_8Kq2/quarters/2026-Q4` Everything about one quarter: owed, saved, and the payments. ```bash curl "https://api.workmade.com/v1/taxpayers/tp_8Kq2/quarters/2026-Q4" \ -H "Authorization: Bearer $WORKMADE_KEY" ``` Response: ```json { "object": "quarter", "taxpayer_id": "tp_8Kq2", "quarter": "2026-Q4", "due": "2027-01-15", "total": 544500, "saved": 544500, "ready_to_pay": true, "payments": [ { "id": "pay_7Hc1", "agency": "IRS", "amount": 418000, "status": "scheduled" }, { "id": "pay_7Hc2", "agency": "NY", "amount": 126500, "status": "scheduled" } ] } ``` --- # Set-asides Rules for saving from a taxpayer’s deposits. ### Create a set-aside `POST /v1/set_asides` Starts saving. Replaces any rule the taxpayer already has. | Field | Type | Description | | --- | --- | --- | | `taxpayer_id` (required) | string | The taxpayer, like `tp_8Kq2`. | | `rule` (required) | string | `percent_of_deposits` or `fixed`. | | `percent` | integer | For `percent_of_deposits`: 1 to 60. | | `amount` | integer | For `fixed`: cents per period. | | `schedule` | string | For `fixed`: `weekly`, `monthly` or `before_due`. | ```bash curl -X POST "https://api.workmade.com/v1/set_asides" \ -H "Authorization: Bearer $WORKMADE_KEY" \ -H "Content-Type: application/json" \ -d '{ "taxpayer_id": "tp_8Kq2", "rule": "percent_of_deposits", "percent": 24 }' ``` Response: ```json { "id": "sa_3Rm8", "object": "set_aside", "taxpayer_id": "tp_8Kq2", "rule": "percent_of_deposits", "percent": 24, "status": "active", "authorization": { "type": "ach_debit", "accepted_at": "2026-03-02T15:06:40Z" } } ``` ### Report a deposit `POST /v1/deposits` Tells us about income so we save its share. | Field | Type | Description | | --- | --- | --- | | `taxpayer_id` (required) | string | The taxpayer, like `tp_8Kq2`. | | `amount` (required) | integer | In cents. | | `received_on` | string | `YYYY-MM-DD`. Defaults to today. | ```bash curl -X POST "https://api.workmade.com/v1/deposits" \ -H "Authorization: Bearer $WORKMADE_KEY" \ -H "Content-Type: application/json" \ -d '{ "taxpayer_id": "tp_8Kq2", "amount": 400000, "received_on": "2026-10-03" }' ``` Response: ```json { "id": "dep_9Lp3", "object": "deposit", "taxpayer_id": "tp_8Kq2", "amount": 400000, "saving": 96000 } ``` ### Retrieve the balance `GET /v1/taxpayers/tp_8Kq2/balance` How much is saved and whether it covers this quarter. ```bash curl "https://api.workmade.com/v1/taxpayers/tp_8Kq2/balance" \ -H "Authorization: Bearer $WORKMADE_KEY" ``` Response: ```json { "object": "balance", "taxpayer_id": "tp_8Kq2", "saved": 544500, "owed_this_quarter": 544500, "short_by": 0 } ``` --- # Payments Money to the IRS and the states. ### Create payments `POST /v1/payments` Books this quarter’s payments: one for the IRS and one for the state. | Field | Type | Description | | --- | --- | --- | | `taxpayer_id` (required) | string | The taxpayer, like `tp_8Kq2`. | | `quarter` (required) | string | Which quarter, like `2026-Q4`. | | `agencies` | string[] | Defaults to both, like `["IRS", "NY"]`. | | `send_on` | string | Override our date. Must still land before the due date. | ```bash curl -X POST "https://api.workmade.com/v1/payments" \ -H "Authorization: Bearer $WORKMADE_KEY" \ -H "Content-Type: application/json" \ -d '{ "taxpayer_id": "tp_8Kq2", "quarter": "2026-Q4" }' ``` Response: ```json { "object": "list", "data": [ { "id": "pay_7Hc1", "object": "payment", "taxpayer_id": "tp_8Kq2", "agency": "IRS", "form": "1040-ES", "quarter": "2026-Q4", "amount": 418000, "method": "electronic", "status": "scheduled", "send_on": "2027-01-12", "due": "2027-01-15", "confirmation": null, "attempts": [] }, { "id": "pay_7Hc2", "object": "payment", "taxpayer_id": "tp_8Kq2", "agency": "NY", "form": "IT-2105", "quarter": "2026-Q4", "amount": 126500, "method": "check", "status": "scheduled", "send_on": "2027-01-05", "due": "2027-01-15", "confirmation": null, "attempts": [] } ] } ``` ### Retrieve a payment `GET /v1/payments/pay_7Hc1` Returns one payment, with every attempt. ```bash curl "https://api.workmade.com/v1/payments/pay_7Hc1" \ -H "Authorization: Bearer $WORKMADE_KEY" ``` Response: ```json { "id": "pay_7Hc1", "object": "payment", "taxpayer_id": "tp_8Kq2", "agency": "IRS", "form": "1040-ES", "quarter": "2026-Q4", "amount": 418000, "method": "electronic", "status": "settled", "send_on": "2027-01-12", "due": "2027-01-15", "confirmation": "270112-EFT-0419", "attempts": [ { "method": "electronic", "status": "settled", "at": "2027-01-12T21:04:55Z" } ] } ``` ### Cancel a payment `POST /v1/payments/pay_7Hc1/cancel` Only while it’s `scheduled`. ```bash curl -X POST "https://api.workmade.com/v1/payments/pay_7Hc1/cancel" \ -H "Authorization: Bearer $WORKMADE_KEY" ``` Response: ```json { "id": "pay_7Hc1", "object": "payment", "taxpayer_id": "tp_8Kq2", "agency": "IRS", "form": "1040-ES", "quarter": "2026-Q4", "amount": 418000, "method": "electronic", "status": "canceled", "send_on": "2027-01-12", "due": "2027-01-15", "confirmation": null, "attempts": [] } ``` --- # Verifications The checks behind `ready_to_pay`. ### Run checks again `POST /v1/verifications` Checks run on their own. Call this after the taxpayer fixes something. | Field | Type | Description | | --- | --- | --- | | `taxpayer_id` (required) | string | The taxpayer, like `tp_8Kq2`. | | `pass_through` | object | Results you already have, like `{ "identity": "verified" }`. | ```bash curl -X POST "https://api.workmade.com/v1/verifications" \ -H "Authorization: Bearer $WORKMADE_KEY" \ -H "Content-Type: application/json" \ -d '{ "taxpayer_id": "tp_8Kq2" }' ``` Response: ```json { "id": "vrf_2HKb", "object": "verification", "taxpayer_id": "tp_8Kq2", "status": "completed", "ready_to_pay": true, "checks": { "identity": "verified", "bank_account": "verified", "ein": "match", "ptin": "active", "sanctions": "clear" } } ``` ### Retrieve a verification `GET /v1/verifications/vrf_2HKb` Returns one verification. ```bash curl "https://api.workmade.com/v1/verifications/vrf_2HKb" \ -H "Authorization: Bearer $WORKMADE_KEY" ``` Response: ```json { "id": "vrf_2HKb", "object": "verification", "taxpayer_id": "tp_8Kq2", "status": "completed", "ready_to_pay": true, "checks": { "identity": "verified", "bank_account": "verified", "ein": "match", "ptin": "active", "sanctions": "clear" } } ``` --- # Returns Draft federal returns. Beta. > Beta. A CPA reviews and files every return. We don’t e-file yet. ### Draft a return `POST /v1/returns` Builds a draft from the year’s data. | Field | Type | Description | | --- | --- | --- | | `taxpayer_id` (required) | string | The taxpayer, like `tp_8Kq2`. | | `tax_year` (required) | integer | Only `2026` during the beta. | ```bash curl -X POST "https://api.workmade.com/v1/returns" \ -H "Authorization: Bearer $WORKMADE_KEY" \ -H "Content-Type: application/json" \ -d '{ "taxpayer_id": "tp_8Kq2", "tax_year": 2026 }' ``` Response: ```json { "id": "rtn_5Tq0", "object": "return", "taxpayer_id": "tp_8Kq2", "tax_year": 2026, "status": "draft", "forms": [ "1040", "SCH_1", "SCH_C", "SCH_SE", "8995" ], "total_tax": 1470000, "estimated_payments": 1672000, "refund": 202000, "amount_due": 0, "out_of_scope": [] } ``` --- # Webhook endpoints Where we send events. ### Create an endpoint `POST /v1/webhook_endpoints` The `secret` is only returned once. | Field | Type | Description | | --- | --- | --- | | `url` (required) | string | Must be `https`. | | `events` (required) | string[] | Which [events](webhooks) to send. | ```bash curl -X POST "https://api.workmade.com/v1/webhook_endpoints" \ -H "Authorization: Bearer $WORKMADE_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://api.yourapp.com/webhooks/workmade", "events": [ "payment.settled", "payment.returned", "verification.completed" ] }' ``` Response: ```json { "id": "we_1", "object": "webhook_endpoint", "url": "https://api.yourapp.com/webhooks/workmade", "events": [ "payment.settled", "payment.returned", "verification.completed" ], "secret": "whsec_9f2c41…", "status": "enabled" } ``` ### Delete an endpoint `DELETE /v1/webhook_endpoints/we_1` Stops sending events at once. ```bash curl -X DELETE "https://api.workmade.com/v1/webhook_endpoints/we_1" \ -H "Authorization: Bearer $WORKMADE_KEY" ``` Response: ```json { "id": "we_1", "object": "webhook_endpoint", "deleted": true } ``` ## The event object ```json { "id": "evt_1vEd", "object": "event", "type": "payment.settled", "created": "2027-01-12T21:04:55Z", "data": { "object": { "id": "pay_7Hc1", "object": "payment", "taxpayer_id": "tp_8Kq2", "agency": "IRS", "form": "1040-ES", "quarter": "2026-Q4", "amount": 418000, "method": "electronic", "status": "settled", "send_on": "2027-01-12", "due": "2027-01-15", "confirmation": "270112-EFT-0419", "attempts": [] } } } ``` --- # Changelog Every change to the API, newest first. ## 2026-11-01 · Preview The first version, for design partners: taxpayers, estimates for federal and every income-tax state, set-asides, payments, verifications, webhooks, and draft returns in beta. ## Coming next - Official libraries for Node and Python. - Federal e-file for draft returns, once the IRS approves it. - More states paid electronically, as they open up.