What does the Gideon Trucker Tax API do?

It prepares and e-files IRS Form 2290 from your own software: POST /api/v1/2290/check validates a return and computes the tax; POST /api/v1/2290/returns prepares it with the taxpayer's Form 8879-EX authorization; POST /api/v1/2290/returns/{id}/efile sends it to the IRS once; GET /api/v1/2290/returns/{id} reports the IRS acknowledgement; GET …/schedule1 returns the stamped Schedule 1 PDF. The OpenAPI 3.1 document is at /api/v1/openapi.json.

A tax professional on the $180 plan, whose key files returns under their own PTIN and EFIN with nothing charged per return; or a software partner, whose key prepares returns that Gideon Trucker Tax e-files as the ERO, paid per return from prepaid credit.

Can a return be filed twice by mistake?

No. E-file is at most once per return: a repeated request, a double-click or a network retry answers 409 with the return's current state instead of a second transmission, and a partner's return carries one filing fee however many times it is sent.

Is there a test environment?

Yes. development.gideontruckertax.com runs the same code against the IRS test system (ATS); a key made there files there and nothing reaches the real IRS.

API

File Form 2290 from your own software.

The same validator, the same e-file path and the same IRS acknowledgements as the preparer dashboard, over a small REST API. Returns are prepared under your PTIN and EFIN and filed on your plan; nothing is charged per return.

Two ways in — same API, different keys

A tax professional. You need a Form 2290 plan ($180 a year, unlimited returns), a completed preparer profile (your PTIN, EFIN and ERO PIN), and a key from /pro/api-keys. A key acts as you: whatever it files is filed under your EFIN, on your plan, and nothing is charged per return.
A software partner — a trucking management system or fleet app filing for its own customers. You need a partner account with prepaid credit ($500 annual commitment, credited in full) and a key from /partner/keys. A key acts as your business: what it prepares is yours to see and to send, e-filed by Gideon as the ERO — you hold no PTIN or EFIN, and none is assigned to you. Each return costs $3 a truck, capped at $15, taken from your credit when it is first e-filed. The offer is on /partners.

The endpoints, the request bodies and the responses are identical for both. What differs is who the key resolves to, which returns it can see, and how filing is paid for.

The flow

Check the return as you build it — POST /api/v1/2290/check. A refusal is one sentence you can show the filer; an acceptance carries the tax and the balance due, which the API works out from the vehicles (it never takes them from you).
Have the taxpayer sign Form 8879-EX in your own software. The IRS requires the ERO to keep the signed form for three years.
Prepare — POST /api/v1/2290/returns with the return and what the signature said. The API fills the 8879-EX and stores it with the return. Nothing is sent to the IRS yet.
Software partners: send the signed original back — POST /api/v1/2290/returns/{id}/authorization with the taxpayer-signed PDF (base64). Gideon is the ERO on your returns and keeps the original; until it is on file the e-file call answers 409 signed_original_required. A preparer’s own returns skip this: the preparer keeps the form.
E-file — POST /api/v1/2290/returns/{id}/efile. Once, and only once: see the rules below.
Poll — GET /api/v1/2290/returns/{id} until the IRS answers, then fetch the stamped Schedule 1 from schedule1Url.

Quick start

Check a return:

curl -s https://www.gideontruckertax.com/api/v1/2290/check \
  -H "Authorization: Bearer $GIDEON_TRUCKER_TAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "return": {
      "taxYear": "2026", "firstUsedMonth": "2026-07",
      "returnType": "firstTime", "paymentMethod": "eftps",
      "taxpayer": { "name": "Kitty Cats Transport LLC", "ein": "003800011",
                    "addressLine1": "12 Whisker Way", "city": "Nashville",
                    "state": "TN", "zip": "37201" },
      "vehicles": [ { "vin": "1FUJGLDR7CLBP8834", "category": "V" } ],
      "businessOfficer": { "name": "Pat Whiskers", "title": "Owner",
                           "phone": "6155550100" }
    }
  }'

Prepare it, with the taxpayer’s signature:

curl -s https://www.gideontruckertax.com/api/v1/2290/returns \
  -H "Authorization: Bearer $GIDEON_TRUCKER_TAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "return": { … the same return … },
    "authorization": {
      "signerName": "Pat Whiskers",
      "signedOn": "2026-09-22",
      "taxpayerPin": "24680",
      "signedFormRetained": true
    }
  }'
# → 201 { "id": "…", "status": "prepared", "balanceDueCents": 55000, … }

Send it, then poll:

curl -s -X POST https://www.gideontruckertax.com/api/v1/2290/returns/$ID/efile \
  -H "Authorization: Bearer $GIDEON_TRUCKER_TAX_API_KEY"
# → 200 { "status": "transmitted", "submissionId": "…", … }

# then poll until the IRS answers (minutes, as a rule)
curl -s https://www.gideontruckertax.com/api/v1/2290/returns/$ID \
  -H "Authorization: Bearer $GIDEON_TRUCKER_TAX_API_KEY"
# → { "status": "accepted", "ack": { "status": "accepted", … },
#     "schedule1Url": "https://www.gideontruckertax.com/api/v1/2290/returns/…/schedule1" }

The full reference — every field, every status, every error code — is the OpenAPI document at /api/v1/openapi.json. Point any OpenAPI client generator at it.

Rules that keep you out of trouble

E-file is at most once. A return that is already sent, answered, held, voided or paper-filed answers 409 with its current state. Never retry the e-file call on a timeout or a 5xx: read the return back first; if it says transmitting or later, it went.
No 8879-EX, no filing. authorization.signedFormRetained is your attestation that the taxpayer signed and that you keep the form. Do not set it before it is true.
A hold is a hold. A return listing several taxable trucks with a first-used month other than July waits for the filer to confirm it; the API reports it as held and cannot release it. A person releases it on /pro/returns.
The figures are ours to compute. Send vehicles, months and categories; the tax, the balance due and the 8879-EX amount are derived by the same rules the IRS re-derives them with. A figure you send is ignored.
Keys are passwords. Store them as such; revoke one you cannot account for on /pro/api-keys.
Test against the development site. development.gideontruckertax.com runs the same code against the IRS test system (ATS); a key made there files there. Nothing filed there reaches the IRS proper.

What a partner is charged, and when

The billing event is the first successful e-file of a return. POST …/{id}/efile takes min(trucks × $3, $15) from your credit the first time the return goes to the IRS. Every response carries the number as serviceFeeCents, next to totalTaxCents — which is the federal tax, the taxpayer’s, paid to the IRS and never to Gideon.
Nothing else is charged. /check, GET on a return, the Schedule 1 and the 8879-EX PDF are free. So is sending the same return again after a rejection or a transmission error: the debit is keyed to the return, and a return carries one.
A retry is the same return id; a new return is a new id. Fix a rejected return with POST /2290/returns only if the IRS wants a different return; otherwise re-send the id you have. Two requests for one id — a double-click, a network retry — cannot file or charge twice: the second answers 409 with the return’s state.
Not enough credit is 402 insufficient_credit with the fee and the balance; the return stays exactly as it was, unsent. Add credit on /partner/billing and send it again.
A refusal costs nothing. If the filing service refuses a return before sending, the debit is reversed and shows as such on your ledger.
Credit expires with the term. Whatever is unused when your annual term ends is written off; you are reminded what is left on June 30 and August 31 and get a renewal notice thirty days before the end. Nothing renews or is charged by itself — a new term starts when you pay the next commitment. Top-ups in between are $5, $10, $25, $50 or $100.
No refund for a rejected return you abandon. Its fee was taken when it first went to the IRS; re-sending it is free, dropping it is not refunded. A partner that leaves is refunded half of the credit left.
Volume rate. A partner with 500 or more customers can be put on $2.50 a truck, capped at $12.50, on a $1,000 commitment; /me reports the rate your key is on.

Questions

What does the Gideon Trucker Tax API do?: It prepares and e-files IRS Form 2290 from your own software: POST /api/v1/2290/check validates a return and computes the tax; POST /api/v1/2290/returns prepares it with the taxpayer's Form 8879-EX authorization; POST /api/v1/2290/returns/{id}/efile sends it to the IRS once; GET /api/v1/2290/returns/{id} reports the IRS acknowledgement; GET …/schedule1 returns the stamped Schedule 1 PDF. The OpenAPI 3.1 document is at /api/v1/openapi.json.
Who can use it?: A tax professional on the $180 plan, whose key files returns under their own PTIN and EFIN with nothing charged per return; or a software partner, whose key prepares returns that Gideon Trucker Tax e-files as the ERO, paid per return from prepaid credit.
Can a return be filed twice by mistake?: No. E-file is at most once per return: a repeated request, a double-click or a network retry answers 409 with the return's current state instead of a second transmission, and a partner's return carries one filing fee however many times it is sent.
Is there a test environment?: Yes. development.gideontruckertax.com runs the same code against the IRS test system (ATS); a key made there files there and nothing reaches the real IRS.

For AI agents

If you are an agent filing on someone’s behalf, read /llms.txt first: it says what this site is, what it files, what it costs, what it will refuse, and what you must have from the taxpayer before you press e-file.

Other forms

The API files Form 2290 today. Form 8849 Schedule 6 (the 2290 vehicle credit) is e-filed from the dashboard and is next.