{"openapi":"3.1.0","info":{"title":"Gideon Trucker Tax API","version":"1.0.0","summary":"Prepare and e-file Form 2290 from your own software.","description":"The same validator, the same e-file path and the same IRS acknowledgements as the /pro dashboard. A key acts as whoever made it. A tax professional's key prepares returns under that preparer's PTIN and EFIN and files them on their plan, with nothing charged per return. A software partner's key (a trucking management system, a fleet app) prepares returns that Gideon e-files as the ERO — the partner holds no PTIN or EFIN — and each return's fee, min(trucks × $3, $15), is drawn from the partner's prepaid credit when the return is first e-filed; checking, status, the Schedule 1 and re-sending a rejected return cost nothing. Every figure the IRS re-derives (the tax, the balance due) is computed by the API from the vehicles you send and never taken from the request. Gideon's fee (serviceFeeCents) is a different number from the federal tax (totalTaxCents), which the taxpayer pays to the IRS.","contact":{"name":"Gideon Trucker Tax","email":"ian@gideonsolutions.us","url":"https://gideontruckertax.com/contact"}},"servers":[{"url":"https://gideontruckertax.com/api/v1"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An API key made on /pro/api-keys (a preparer) or /partner/keys (a software partner), e.g. `Authorization: Bearer gt_live_…`. Shown once; store it as you would a password."}},"schemas":{"Return2290Input":{"type":"object","description":"A Form 2290 as the site's own form sends it. Money is a decimal string (\"550.00\"), months are YYYY-MM, the tax year is the year the July–June period starts. The preparer and firm blocks are ignored: they are your profile.","required":["taxYear","firstUsedMonth","returnType","paymentMethod","taxpayer","vehicles"],"properties":{"lang":{"type":"string","enum":["en","es"],"default":"en","description":"The language of refusal messages."},"taxYear":{"type":"string","example":"2026","description":"The year the tax period begins (July 1). 2026 or 2025."},"firstUsedMonth":{"type":"string","example":"2026-07","description":"Inside the period, and no later than next month. A month that has not begun yet holds the return until the filer confirms it (hold kind first_use)."},"returnType":{"type":"string","enum":["firstTime","amended","vinCorrection","final"]},"amendedReason":{"type":"string","enum":["tgwIncrease","mileageExceeded"],"description":"With returnType amended."},"amendedMonth":{"type":"string","example":"2026-09","description":"With amendedReason mileageExceeded."},"paymentMethod":{"type":"string","enum":["eftps","credit_debit_card","efw"]},"payment":{"type":"object","description":"Only with paymentMethod efw (direct debit). The amount debited is the balance due.","properties":{"routingNumber":{"type":"string","description":"Nine digits with a valid ABA check digit."},"accountNumber":{"type":"string"},"accountType":{"type":"string","enum":["checking","savings"]},"paymentAmount":{"type":"string","example":"550.00"},"phone":{"type":"string","description":"Ten digits; the IRS payment record requires it."}}},"taxCredits":{"type":"string","example":"0.00","description":"Line 5. When more than zero, statements.credits must list each vehicle and add up to it."},"mileage5000OrLess":{"type":"boolean","description":"Line 7 — required exactly when a Category W vehicle is listed."},"agricMileage7500OrLess":{"type":"boolean"},"notSubjectToTax":{"type":"boolean","description":"Line 8a; needs statements.suspendedVin."},"addressChange":{"type":"boolean"},"form8822bAttached":{"type":"boolean"},"responsiblePartyCurrent":{"type":"boolean"},"disasterRelief":{"type":"string"},"specialConditions":{"type":"array","items":{"type":"string"}},"signatureOption":{"type":"string","enum":["pin"],"default":"pin"},"taxpayer":{"type":"object","required":["name","ein","addressLine1","city","state","zip"],"properties":{"name":{"type":"string"},"ein":{"type":"string","description":"Nine digits."},"inCareOf":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string","description":"Folded into line 1 on the wire; the IRS takes one line."},"city":{"type":"string"},"state":{"type":"string","description":"Two-letter code; the ZIP must belong to it."},"zip":{"type":"string"}}},"vehicles":{"type":"array","minItems":1,"items":{"type":"object","required":["vin","category"],"properties":{"vin":{"type":"string","description":"1–17 characters, or 19; a 17-character VIN has no I, O or Q. Each VIN once."},"category":{"type":"string","description":"Weight category A–V, or W for a suspended vehicle."},"logging":{"type":"boolean","default":false}}}},"businessOfficer":{"type":"object","description":"The person signing for the business.","properties":{"name":{"type":"string"},"title":{"type":"string"},"phone":{"type":"string","description":"Ten digits."},"email":{"type":"string"},"taxpayerPin":{"type":"string","description":"Overridden by authorization.taxpayerPin."}}},"signingOfficer":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"ssn":{"type":"string"}}},"originalSubmission":{"type":"object","description":"For a superseding return: the submission it replaces.","properties":{"id":{"type":"string"},"date":{"type":"string","example":"2026-07-15"}}},"statements":{"type":"object","properties":{"credits":{"type":"array","items":{"type":"object","properties":{"vin":{"type":"string"},"explanation":{"type":"string"},"date":{"type":"string","example":"2026-01-15","description":"The day sold/destroyed/stolen, or June 30 for a low-mileage credit."},"amount":{"type":"string","example":"275.00"}}}},"tgwIncrease":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string","example":"2026-09"},"previousCategory":{"type":"string"},"category":{"type":"string"},"logging":{"type":"boolean"}}}},"suspensionSupport":{"type":"array","items":{"type":"object","properties":{"vin":{"type":"string"},"businessName":{"type":"string"},"date":{"type":"string"}}}},"suspendedVin":{"type":"array","items":{"type":"object","properties":{"vin":{"type":"string"}}}},"privateSale":{"type":"array","items":{"type":"object","properties":{"vin":{"type":"string"},"buyerName":{"type":"string"},"buyerIsPerson":{"type":"boolean"},"buyerStreet1":{"type":"string"},"buyerCity":{"type":"string"},"buyerState":{"type":"string"},"buyerZip":{"type":"string"}}}},"vinCorrectionExplanation":{"type":"string","description":"With returnType vinCorrection."}}}},"example":{"lang":"en","taxYear":"2026","firstUsedMonth":"2026-07","returnType":"firstTime","paymentMethod":"eftps","signatureOption":"pin","taxCredits":"0.00","taxpayer":{"name":"Kitty Cats Transport LLC","ein":"003800011","addressLine1":"12 Whisker Way","city":"Nashville","state":"TN","zip":"37201"},"vehicles":[{"vin":"1FUJGLDR7CLBP8834","category":"V","logging":false}],"businessOfficer":{"name":"Pat Whiskers","title":"Owner","phone":"6155550100","email":"pat@example.com"}}},"Authorization":{"type":"object","description":"What the taxpayer's signature on Form 8879-EX said. The API fills Part I from the validated return and Part III from your profile, files the PDF with the return, and puts the PIN on the return. You keep the signed form for three years; the IRS holds the ERO to that.","required":["signerName","signedOn","signedFormRetained"],"properties":{"signerName":{"type":"string","description":"Who signed for the taxpayer."},"signedOn":{"type":"string","example":"2026-09-22","description":"YYYY-MM-DD; not in the future."},"taxpayerPin":{"type":"string","description":"The taxpayer's five-digit PIN (not 00000)."},"authorizeEro":{"type":"boolean","description":"True when the taxpayer ticked the first box in Part II — authorizing you, the ERO, to enter a PIN for them. Then taxpayerPin may be omitted and one is chosen."},"signedFormRetained":{"type":"boolean","description":"Must be true: your attestation that the signed form exists and is kept."}},"example":{"signerName":"Pat Whiskers","signedOn":"2026-09-22","taxpayerPin":"24680","signedFormRetained":true}},"Return2290":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"form":{"type":"string","enum":["2290"]},"status":{"type":"string","enum":["prepared","held","transmitting","transmitted","accepted","rejected","error","voided","paper_filed"],"description":"prepared: saved, not sent. held: prepared, but waiting on the filer's answer (see hold). transmitting/transmitted: on its way / with the IRS, ack pending. accepted/rejected: the IRS's answer (see ack). error: the transmission failed before the IRS took it (see lastError)."},"taxYear":{"type":"string","example":"2026"},"firstUsedMonth":{"type":"string","example":"2026-07"},"taxpayer":{"type":"object","properties":{"name":{"type":"string"},"ein":{"type":"string"}}},"vehicles":{"type":"integer"},"totalTaxCents":{"type":"integer","description":"The federal tax on the return — the taxpayer's, paid to the IRS, never to Gideon."},"balanceDueCents":{"type":"integer","description":"What the taxpayer still owes the IRS after credits."},"serviceFeeCents":{"type":["integer","null"],"description":"Gideon's service fee for this return: on a software partner's return, min(trucks × $3, $15), debited from the partner's prepaid credit when the return is first e-filed. Null on a preparer's return — the plan covers it."},"submissionId":{"type":["string","null"],"description":"The IRS submission id, once transmitted."},"createdAt":{"type":"string","format":"date-time"},"transmittedAt":{"type":["string","null"],"format":"date-time"},"acceptedAt":{"type":["string","null"],"format":"date-time"},"ack":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["accepted","rejected"]},"receivedAt":{"type":"string","format":"date-time"},"errors":{"type":"array","items":{"type":"object","properties":{"ruleNum":{"type":"string"},"message":{"type":"string"}}}}}},"hold":{"type":["object","null"],"properties":{"kind":{"type":"string","enum":["first_use"]},"message":{"type":"string"}}},"lastError":{"type":["string","null"]},"schedule1Url":{"type":["string","null"],"description":"Set once the IRS has accepted the return."},"authorizationUrl":{"type":"string","description":"GET the Form 8879-EX (the signed original once posted, else the filled form); POST the taxpayer-signed original there."},"authorization":{"type":"object","description":"On a software partner's return the taxpayer-signed Form 8879-EX original must be posted before e-file; a preparer's return needs none.","properties":{"signedOriginalRequired":{"type":"boolean"},"signedOriginalReceivedAt":{"type":["string","null"],"format":"date-time"}}}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"A sentence a person can act on."}},"required":["code","message"]}}}}},"paths":{"/me":{"get":{"summary":"Who this key is","responses":{"200":{"description":"Who the key acts as. A preparer's key: the preparer, their plan, and which forms it files. A software partner's key: the partner, the ERO its returns file under (Gideon), its prepaid credit and annual term, and the fee formula.","content":{"application/json":{"schema":{"type":"object","properties":{"preparer":{"type":"object","description":"On a preparer's key.","properties":{"name":{"type":"string"},"email":{"type":"string"},"ptin":{"type":"string"},"efin":{"type":"string"},"firm":{"type":["string","null"]}}},"partner":{"type":"object","description":"On a software partner's key.","properties":{"name":{"type":"string"},"email":{"type":"string"}}},"ero":{"type":"object","description":"On a software partner's key: who e-files its returns.","properties":{"name":{"type":"string"},"firm":{"type":["string","null"]},"efin":{"type":"string"}}},"credit":{"type":"object","description":"On a software partner's key.","properties":{"balanceCents":{"type":"integer"},"termStartedAt":{"type":["string","null"],"format":"date-time"},"termEndsAt":{"type":["string","null"],"format":"date-time"}}},"pricing":{"type":"object","description":"On a software partner's key.","properties":{"tier":{"type":"string","enum":["standard","volume"]},"annualCommitmentCents":{"type":"integer"},"perTruckCents":{"type":"integer"},"returnCapCents":{"type":"integer"},"topUpOptionsCents":{"type":"array","items":{"type":"integer"}},"rule":{"type":"string"}}},"authorization":{"type":"object","description":"On a software partner's key.","properties":{"signedOriginalRequired":{"type":"boolean"},"rule":{"type":"string"}}},"plan":{"type":["string","null"]},"forms":{"type":"object","additionalProperties":{"type":"boolean"}}}}}}},"401":{"description":"No key, or a key that is not recognised.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"A sentence a person can act on."}},"required":["code","message"]}}}}}}}}},"/2290/check":{"post":{"summary":"Would this return be accepted?","description":"Runs the validator and computes the figures. Stores nothing. Use it while a return is being put together; every refusal is a sentence you can show.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["return"],"properties":{"return":{"$ref":"#/components/schemas/Return2290Input"}}}}}},"responses":{"200":{"description":"The return would be accepted.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"return":{"type":"object","properties":{"taxYear":{"type":"string"},"firstUsedMonth":{"type":"string"},"returnType":{"type":"string"},"vehicles":{"type":"integer"},"totalTaxCents":{"type":"integer","description":"The federal tax — paid to the IRS."},"balanceDueCents":{"type":"integer"},"serviceFeeCents":{"type":["integer","null"],"description":"On a software partner's key: what Gideon would charge to file this return. Null on a preparer's key."},"paymentMethod":{"type":"string"},"wouldBeHeld":{"type":["string","null"],"enum":["first_use",null]}}}}}}}},"401":{"description":"No key, or a key that is not recognised.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"A sentence a person can act on."}},"required":["code","message"]}}}}}},"402":{"description":"The plan does not include Form 2290.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"A sentence a person can act on."}},"required":["code","message"]}}}}}},"422":{"description":"Refused: `error.message` says what to change. (`ok` is false.)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"A sentence a person can act on."}},"required":["code","message"]}}}}}}}}},"/2290/returns":{"get":{"summary":"Your Form 2290 returns","responses":{"200":{"description":"Newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"returns":{"type":"array","items":{"$ref":"#/components/schemas/Return2290"}}}}}}},"401":{"description":"No key, or a key that is not recognised.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"A sentence a person can act on."}},"required":["code","message"]}}}}}}}},"post":{"summary":"Prepare a return","description":"Validates, generates the signed Form 8879-EX, and stores the return as prepared. Nothing goes to the IRS from this call — use `POST /2290/returns/{id}/efile` — unless you have opted into unattended filing on /pro, in which case a routine return that clears the automatic review is filed right after, as from /pro.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["return","authorization"],"properties":{"return":{"$ref":"#/components/schemas/Return2290Input"},"authorization":{"$ref":"#/components/schemas/Authorization"}}},"example":{"return":{"lang":"en","taxYear":"2026","firstUsedMonth":"2026-07","returnType":"firstTime","paymentMethod":"eftps","signatureOption":"pin","taxCredits":"0.00","taxpayer":{"name":"Kitty Cats Transport LLC","ein":"003800011","addressLine1":"12 Whisker Way","city":"Nashville","state":"TN","zip":"37201"},"vehicles":[{"vin":"1FUJGLDR7CLBP8834","category":"V","logging":false}],"businessOfficer":{"name":"Pat Whiskers","title":"Owner","phone":"6155550100","email":"pat@example.com"}},"authorization":{"signerName":"Pat Whiskers","signedOn":"2026-09-22","taxpayerPin":"24680","signedFormRetained":true}}}}},"responses":{"201":{"description":"Prepared.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Return2290"}}}},"401":{"description":"No key, or a key that is not recognised.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"A sentence a person can act on."}},"required":["code","message"]}}}}}},"402":{"description":"The plan does not include Form 2290.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"A sentence a person can act on."}},"required":["code","message"]}}}}}},"422":{"description":"Refused (`refused`), or the authorization is incomplete (`authorization_required`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"A sentence a person can act on."}},"required":["code","message"]}}}}}}}}},"/2290/returns/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"A return's status","description":"Poll this after e-filing. The IRS answers within minutes as a rule; `ack` carries the answer and, on a rejection, the rule numbers.","responses":{"200":{"description":"The return.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Return2290"}}}},"404":{"description":"Not this preparer's, or not a Form 2290.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"A sentence a person can act on."}},"required":["code","message"]}}}}}}}}},"/2290/returns/{id}/efile":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"E-file the return","description":"Sends the prepared return to the IRS. At most once: a return already sent, answered, held, voided or paper-filed is a 409 carrying its current state, not a second transmission — two requests for one id cannot file or charge twice. Never retry this call on a timeout or a 5xx — read the return back first; if it is `transmitting` or later, it went. For a software partner this is the billing event: the return's `serviceFeeCents` is taken from the prepaid credit the first time the return goes to the IRS, and never again for that return — re-sending it after a rejection or an error is free. A refusal by the filing service before sending reverses the debit.","responses":{"200":{"description":"Transmitted; `submissionId` is set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Return2290"}}}},"402":{"description":"`plan_required` (a preparer's plan does not include Form 2290) or `insufficient_credit` (a partner's balance cannot cover the fee — `error.credit` has the fee and the balance; nothing was sent or debited).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"A sentence a person can act on."}},"required":["code","message"]}}}}}},"409":{"description":"Not filable now: `held`, `signed_original_required` (a partner's return with no taxpayer-signed 8879-EX on file), `not_filable`, `voided` or `paper_filed`; `error.return` is the current state.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"A sentence a person can act on."}},"required":["code","message"]}}}}}},"502":{"description":"The transmission failed (`transmit_failed`); the return is in `error` and can be sent again after the cause is fixed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"A sentence a person can act on."}},"required":["code","message"]}}}}}}}}},"/2290/returns/{id}/schedule1":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"The stamped Schedule 1","responses":{"200":{"description":"PDF.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Not yet (`not_yet`) — the IRS has not accepted the return.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"A sentence a person can act on."}},"required":["code","message"]}}}}}}}}},"/2290/returns/{id}/authorization":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"The Form 8879-EX on file","description":"The taxpayer-signed original once a partner has posted it; else the form the API filled at prepare time.","responses":{"200":{"description":"PDF.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Not this account's, or no form stored.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"A sentence a person can act on."}},"required":["code","message"]}}}}}}}},"post":{"summary":"Send the taxpayer-signed Form 8879-EX original back (software partners)","description":"Gideon is the ERO on a software partner's return and keeps the signed original. Post the PDF the taxpayer signed; until one is on file the return's e-file call answers 409 `signed_original_required`. Posting again keeps every copy and serves the newest. A preparer's return does not need this.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["pdfBase64"],"properties":{"pdfBase64":{"type":"string","description":"The signed PDF, base64 (a data: prefix is tolerated). About 6 MB at most."},"filename":{"type":"string","description":"Optional; letters, digits, dot, dash and underscore, ending .pdf."}}}}}},"responses":{"201":{"description":"Received and kept.","content":{"application/json":{"schema":{"type":"object","properties":{"received":{"type":"boolean"},"filename":{"type":"string"},"receivedAt":{"type":"string","format":"date-time"},"bytes":{"type":"integer"}}}}}},"404":{"description":"Not this account's.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"A sentence a person can act on."}},"required":["code","message"]}}}}}},"413":{"description":"Too large (`too_large`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"A sentence a person can act on."}},"required":["code","message"]}}}}}},"422":{"description":"`pdf_required` or `not_a_pdf`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"A sentence a person can act on."}},"required":["code","message"]}}}}}}}}}}}