--- title: "Federal first, then the states" url: https://services.dev/docs/examples/tax/efile captured: [tax-branches.txt, tax-efile-v3.txt] --- # Federal first, then the states URL: https://services.dev/docs/examples/tax/efile > The annual return's file step. One filing per jurisdiction, the federal return leading and each state linked to it, a rejection routed by its code to the step that repairs it, and a repair inside the perfection window that keeps its first filing time. *tax's words: return is a job, taxpayer is a subject, review is a task, preparer is a member (examples/tax/brand.ts).* One submit step files the return everywhere it's owed: the federal return first, then each state, linked to it. A rejection is a transition to the step its code names, state by state, and the states that accepted stay filed. ```bash grep -A3 "file: {$" services/annual-return.ts ``` ```txt title="magic values: none" file: { submit: efile, to: 'IRS and states', receipt: 'receipts', each: { of: 'jurisdictions', lead: j => j === 'US' }, rejected: { ein_mismatch: { to: 'organizer', items: reask.ein_mismatch }, schedule_missing: { to: 'organizer', items: reask.schedule_missing }, math: 'draft', '*': 'prepare' }, perfect: '10d', }, ``` | Key | Here | What it does | |---|---|---| | `submit` | `efile`, your function in `lib/tax.ts` | Files one jurisdiction's return. A live brand calls its transmitter here | | `receipt` | `'receipts'` | The output each receipt's id fills, one per jurisdiction | | `each.of` | `'jurisdictions'` | One submission, and one receipt, per element of the input list | | `each.lead` | `j => j === 'US'` | The federal return goes first; each state waits for its acceptance | | `rejected` | a map of codes | Each code to the step that repairs it, in the order written; `'*'` takes the rest | | `perfect` | `'10d'` | A repair resubmitted within 10 days of the first submission keeps that submission's time | Each code, where it goes, and the test EIN that produces it: | Code | Goes to | Then | Test EIN | |---|---|---|---| | `ein_mismatch` | `organizer` | Re-asks only that state's tax account number | `98-7654321`, New York | | `schedule_missing` | `organizer` | Re-asks only the schedule that state named | `98-7654323`, New Jersey | | `math` | `draft` | The AI drafts again, and the signer signs the new version | `98-7654322`, California | | any other | `prepare` | A preparer repairs it, and a different member signs | `98-7654325`, New Jersey, and `98-7654326`, California, `business_rule` | ## One return, four filings The simulated e-file system in `lib/tax.ts`, your code, rejects New York once for test EIN 98-7654321. Ada signs the §7216 consent and answers the organizer through her own links, and Katherine Johnson signs: ```txt → POST /returns {"service":"annual-return","business":{"name":"Acme Robotics","email":"books@acme.example"},"owner":{"name":"Ada Lovelace","email":"ada@example.com"},"ein":"98-7654321","tax_year":"2026","entity":"C corp","jurisdictions":["US","US-CA","US-NY","US-NJ"],"books":"https://books.example/acme","max_usd":1800,"key":"acme-ny"} ``` ```txt title="captured/tax-efile-v3.txt · magic values: none" # Ada signs the §7216 consent and answers the organizer through her own links # mbr_8Ea1, in her own session: GET /tasks/tsk_7Hq2/sheet · POST /tasks/tsk_7Hq2/claim · POST /tasks/tsk_7Hq2/clear → POST /practitioners/returns/job_4Tx2/approve {"checklist":["every line traces to a source","due diligence answered","the officer's e-file authorization shows this return's figures"]} ← 200 ``` Ada signs Form 8879-CORP. The federal return, California and New Jersey are accepted, and New York is rejected with `ein_mismatch`: ```txt → POST /practitioners/returns/job_4Tx2/approve {"checklist":["every line traces to a source","due diligence answered","the officer's e-file authorization shows this return's figures"]} ``` ```txt title="200 · magic values: none" ← job_4Tx2 · waiting · on claim · $1,800.00 held · sign rcp_7Hq2 US accepted · filed 2027-02-01 · US 1120 2026 accepted rcp_7Hq3 US-CA accepted · filed 2027-02-01 · after rcp_7Hq2 · US-CA 100 2026 accepted rcp_7Hq4 US-NY rejected · ein_mismatch · filed 2027-02-01 · after rcp_7Hq2 rcp_7Hq5 US-NJ accepted · filed 2027-02-01 · after rcp_7Hq2 · US-NJ CBT-100 2026 accepted ``` ## Repaired in time Three days later Ada answers New York's one item. The workpapers changed, so the signature no longer covers them: Katherine signs the new version, a new act paid again, and Ada signs a new Form 8879-CORP. Only New York is refiled: ```txt → POST /test_clocks/default/advance {"to":"3d"} ``` ```txt title="magic values: none" ← job_4Tx2 · delivered · workpapers-2026.txt · return.txt · $1,800.00 charged rcp_7Hq2 US accepted · filed 2027-02-01 · US 1120 2026 accepted rcp_7Hq3 US-CA accepted · filed 2027-02-01 · after rcp_7Hq2 · US-CA 100 2026 accepted rcp_7Hq4 US-NY rejected · ein_mismatch · filed 2027-02-01 · after rcp_7Hq2 rcp_7Hq5 US-NJ accepted · filed 2027-02-01 · after rcp_7Hq2 · US-NJ CBT-100 2026 accepted rcp_7Hq6 US-NY accepted · filed 2027-02-01 · sent 2027-02-04 · after rcp_7Hq2 · US-NY CT-3 2026 accepted ``` New York's two receipts. The refiled one went out inside `perfect: '10d'`, so it keeps the rejected filing's `at`; `sent_at` is when it actually left: ```bash curl -s http://localhost:8787/returns/job_4Tx2 | jq '[.receipts[] | select(.element == 2)]' # New York, rejected then filed on time ``` ```json title="magic values: none" [ { "id": "rcp_7Hq4", "object": "receipt", "job": "job_4Tx2", "step": "file", "to": "IRS and states", "at": "2027-02-01T09:00:00.000Z", "status": "rejected", "element": 2, "for": "US-NY", "lead": "rcp_7Hq2", "livemode": false, "codes": [ "ein_mismatch" ], "simulated": true }, { "id": "rcp_7Hq6", "object": "receipt", "job": "job_4Tx2", "step": "file", "to": "IRS and states", "at": "2027-02-01T09:00:00.000Z", "sent_at": "2027-02-04T09:00:00.000Z", "status": "accepted", "element": 2, "for": "US-NY", "lead": "rcp_7Hq2", "livemode": false, "ref": "US-NY CT-3 2026 accepted", "simulated": true } ] ``` The charge released when the last filing was accepted. The owner's record shows each step, including the signature the gate refused for the changed workpapers: ```txt → GET /owner/returns/job_4Tx2 # the owner console ``` ```txt title="magic values: none" record consent · owner · §7216 | organizer.books · answered | organizer.bank · answered | organizer.payroll · answered | organizer.assets · answered | organizer.ca_account · answered | organizer.ny_account · answered | organizer.nj_account · answered | organizer · owner · upload | compute · code | draft · ai | check · ai · adversarial · 3 lenses · pass | sign · person · ptin and cpa · * · mbr_8Ea1 | authorize · owner · Form 8879-CORP · id-verified | file · IRS and states · rejected · ein_mismatch · repairing at organizer | organizer.ny_account · answered | organizer · owner · upload | compute · code | sign · signer · refused · unattested · workpapers changed after the signer signed it; they sign the new version before it is filed. | authorize · signature void | draft · ai | check · ai · adversarial · 3 lenses · pass | sign · person · ptin and cpa · * · mbr_8Ea1 | authorize · signature void | authorize · owner · Form 8879-CORP · id-verified · clock paused 3d | file · IRS and states · efin simulated · 4 accepted ledger +$1,800.00 · AI $3.36 · signer $210.00 · you $1,586.64 ``` ## Every code, by test EIN Each test EIN, run on its own. After any repair the return changed, so the signer signs again before it's filed: ```txt → POST /returns {"service":"annual-return","business":{"name":"Acme Robotics","email":"books@acme.example"},"owner":{"name":"Ada","email":"signs@example.test"},"ein":"98-7654321","tax_year":"2026","entity":"C corp","jurisdictions":["US","US-CA","US-NY","US-NJ"],"books":"https://books.example/acme","max_usd":1800,"key":"98-7654321"} # ein = 98-7654321 ``` ```txt title="captured/tax-branches.txt · magic values: owner.email = signs@example.test, owner.email = declines@example.test, owner.email = silent@example.test, metadata.sandbox.asks = { approve: pay it }, metadata.sandbox.asks = { approve: pay a different amount }, metadata.sandbox.asks = { approve: skip, in writing }, metadata.sandbox.outside = never, metadata.sandbox.brand = stale, metadata.sandbox.brand = verified, member = mbr_eligible, member = mbr_lapsed_credential" ← job_4Tx2 · delivered · workpapers-2026.txt · return.txt · $1,800.00 charged record … organizer · owner · upload | draft · ai | sign · person · ptin and enrolled agent · * · mbr_8Ea1 | file · IRS and states · rejected · ein_mismatch · repairing at organizer | organizer · owner · upload | sign · signer · refused · unattested · workpapers changed after the signer signed it; they sign the new version before it is filed. | draft · ai | sign · person · ptin and enrolled agent · * · mbr_8Ea1 | file · IRS and states · efin simulated · 4 accepted ``` ```txt → POST /returns {"service":"annual-return","business":{"name":"Acme Robotics","email":"books@acme.example"},"owner":{"name":"Ada","email":"signs@example.test"},"ein":"98-7654322","tax_year":"2026","entity":"C corp","jurisdictions":["US","US-CA","US-NY","US-NJ"],"books":"https://books.example/acme","max_usd":1800,"key":"98-7654322"} # ein = 98-7654322 ``` ```txt title="captured/tax-branches.txt · magic values: owner.email = signs@example.test, owner.email = declines@example.test, owner.email = silent@example.test, metadata.sandbox.asks = { approve: pay it }, metadata.sandbox.asks = { approve: pay a different amount }, metadata.sandbox.asks = { approve: skip, in writing }, metadata.sandbox.outside = never, metadata.sandbox.brand = stale, metadata.sandbox.brand = verified, member = mbr_eligible, member = mbr_lapsed_credential" ← job_4Tx2 · delivered · workpapers-2026.txt · return.txt · $1,800.00 charged record … organizer · owner · upload | draft · ai | sign · person · ptin and enrolled agent · * · mbr_8Ea1 | file · IRS and states · rejected · math · repairing at draft | draft · ai · redo | sign · signer · refused · unattested · return changed after the signer signed it; they sign the new version before it is filed. | sign · person · ptin and enrolled agent · * · mbr_8Ea1 | file · IRS and states · efin simulated · 4 accepted ``` ```txt → POST /returns {"service":"annual-return","business":{"name":"Acme Robotics","email":"books@acme.example"},"owner":{"name":"Ada","email":"signs@example.test"},"ein":"98-7654323","tax_year":"2026","entity":"C corp","jurisdictions":["US","US-CA","US-NY","US-NJ"],"books":"https://books.example/acme","max_usd":1800,"key":"98-7654323"} # ein = 98-7654323 ``` ```txt title="captured/tax-branches.txt · magic values: owner.email = signs@example.test, owner.email = declines@example.test, owner.email = silent@example.test, metadata.sandbox.asks = { approve: pay it }, metadata.sandbox.asks = { approve: pay a different amount }, metadata.sandbox.asks = { approve: skip, in writing }, metadata.sandbox.outside = never, metadata.sandbox.brand = stale, metadata.sandbox.brand = verified, member = mbr_eligible, member = mbr_lapsed_credential" ← job_4Tx2 · delivered · workpapers-2026.txt · return.txt · $1,800.00 charged record … organizer · owner · upload | draft · ai | sign · person · ptin and enrolled agent · * · mbr_8Ea1 | file · IRS and states · rejected · schedule_missing · repairing at organizer | organizer · owner · upload | sign · signer · refused · unattested · workpapers changed after the signer signed it; they sign the new version before it is filed. | draft · ai | sign · person · ptin and enrolled agent · * · mbr_8Ea1 | file · IRS and states · efin simulated · 4 accepted ``` ```txt → POST /returns {"service":"annual-return","business":{"name":"Acme Robotics","email":"books@acme.example"},"owner":{"name":"Ada","email":"signs@example.test"},"ein":"98-7654325","tax_year":"2026","entity":"C corp","jurisdictions":["US","US-CA","US-NY","US-NJ"],"books":"https://books.example/acme","max_usd":1800,"key":"98-7654325"} # ein = 98-7654325 ``` ```txt title="captured/tax-branches.txt · magic values: owner.email = signs@example.test, owner.email = declines@example.test, owner.email = silent@example.test, metadata.sandbox.asks = { approve: pay it }, metadata.sandbox.asks = { approve: pay a different amount }, metadata.sandbox.asks = { approve: skip, in writing }, metadata.sandbox.outside = never, metadata.sandbox.brand = stale, metadata.sandbox.brand = verified, member = mbr_eligible, member = mbr_lapsed_credential" ← job_4Tx2 · delivered · workpapers-2026.txt · return.txt · $1,800.00 charged record … organizer · owner · upload | draft · ai | sign · person · ptin and enrolled agent · * · mbr_8Ea1 | file · IRS and states · rejected · business_rule · repairing at prepare | prepare · person · ptin and enrolled agent · * · mbr_8Ea1 | sign · person · ptin and cpa · * · mbr_7Hq2 | file · IRS and states · efin simulated · 4 accepted ``` ```txt → POST /returns {"service":"annual-return","business":{"name":"Acme Robotics","email":"books@acme.example"},"owner":{"name":"Ada","email":"signs@example.test"},"ein":"98-7654326","tax_year":"2026","entity":"C corp","jurisdictions":["US","US-CA","US-NY","US-NJ"],"books":"https://books.example/acme","max_usd":1800,"key":"98-7654326"} # ein = 98-7654326 ``` ```txt title="captured/tax-branches.txt · magic values: owner.email = signs@example.test, owner.email = declines@example.test, owner.email = silent@example.test, metadata.sandbox.asks = { approve: pay it }, metadata.sandbox.asks = { approve: pay a different amount }, metadata.sandbox.asks = { approve: skip, in writing }, metadata.sandbox.outside = never, metadata.sandbox.brand = stale, metadata.sandbox.brand = verified, member = mbr_eligible, member = mbr_lapsed_credential" ← job_4Tx2 · delivered · workpapers-2026.txt · return.txt · $1,800.00 charged record … organizer · owner · upload | draft · ai | sign · person · ptin and enrolled agent · * · mbr_8Ea1 | file · IRS and states · US-CA rejected · business_rule · repairing at prepare | prepare · person · ptin and enrolled agent · US-CA · mbr_8Ea1, a CTEC, CPA, EA or bar card on a California leg | sign · person · ptin and cpa · * · mbr_7Hq2 | file · IRS and states · efin simulated · 4 accepted ``` Two states, each with its own code and item, and the states that accepted stay filed: ```txt → POST /returns {"service":"annual-return","business":{"name":"Acme Robotics","email":"books@acme.example"},"owner":{"name":"Ada","email":"signs@example.test"},"ein":"98-7654324","tax_year":"2026","entity":"C corp","jurisdictions":["US","US-CA","US-NY","US-NJ"],"books":"https://books.example/acme","max_usd":1800,"key":"two-states"} # ein = 98-7654324 ``` ```txt title="captured/tax-branches.txt · magic values: owner.email = signs@example.test, owner.email = declines@example.test, owner.email = silent@example.test, metadata.sandbox.asks = { approve: pay it }, metadata.sandbox.asks = { approve: pay a different amount }, metadata.sandbox.asks = { approve: skip, in writing }, metadata.sandbox.outside = never, metadata.sandbox.brand = stale, metadata.sandbox.brand = verified, member = mbr_eligible, member = mbr_lapsed_credential" ← job_4Tx2 · delivered · workpapers-2026.txt · return.txt · $1,800.00 charged record … organizer.books · answered | organizer.bank · answered | organizer.payroll · answered | organizer.assets · answered | organizer.ca_account · answered | organizer.ny_account · answered | organizer.nj_account · answered | file · IRS and states · rejected · ein_mismatch · repairing at organizer | file · IRS and states · rejected · schedule_missing | organizer.ny_account · answered | organizer.nj_schedule · answered | file · IRS and states · efin simulated · 4 accepted re-asked ny_account: Your NY tax account number · nj_schedule: The NJ schedule the state found missing receipt US · accepted · filed 2027-02-01 09:00 receipt US-CA · accepted · filed 2027-02-01 09:00 receipt US-NY · rejected ein_mismatch · filed 2027-02-01 09:00 receipt US-NJ · rejected schedule_missing · filed 2027-02-01 09:00 receipt US-NY · accepted · filed 2027-02-01 09:00 receipt US-NJ · accepted · filed 2027-02-01 09:00 status delivered ``` [One submission per element](https://services.dev/docs/service/each.md) and [Sending to outside systems](https://services.dev/docs/service/submit.md) cover the keys. --- - Up: [The tax example](https://services.dev/docs/examples/tax.md) - Previous: [Annual return](https://services.dev/docs/examples/tax/annual-return.md) - Next: [Estimated payment](https://services.dev/docs/examples/tax/estimate.md)