File Form 2290 from your own software.

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

1. 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).
2. Have the taxpayer sign Form 8879-EX in your own software. The IRS requires the ERO to keep the signed form for three years.
3. 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.
4. E-file — POST /api/v1/2290/returns/{id}/efile. Once, and only once: see the rules below.
5. 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.gideontax.com/api/v1/2290/check \
  -H "Authorization: Bearer $GIDEON_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.gideontax.com/api/v1/2290/returns \
  -H "Authorization: Bearer $GIDEON_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.gideontax.com/api/v1/2290/returns/$ID/efile \
  -H "Authorization: Bearer $GIDEON_TAX_API_KEY"
# → 200 { "status": "transmitted", "submissionId": "…", … }

# then poll until the IRS answers (minutes, as a rule)
curl -s https://www.gideontax.com/api/v1/2290/returns/$ID \
  -H "Authorization: Bearer $GIDEON_TAX_API_KEY"
# → { "status": "accepted", "ack": { "status": "accepted", … },
#     "schedule1Url": "https://www.gideontax.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.gideontax.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.

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. Forms 720 and 8849 and the employment series (940–945) are e-filed from the dashboard and are next. Ask at ian@gideonsolutions.us if one of them is what you need.