Worlds / Gov and compliance

IRS e-file API

A local IRS e-file (MeF) with return submissions, schedules, acknowledgements and business rule rejections. Test the tax prep agent that transmits returns and fixes rejections by their codes.

Base path: /
Auth: Bearer token, the world key
Endpoints: 12
Status: Active today

This reference previews the surface the IRS e-file world serves in the closed beta. Paths mirror the public IRS e-file API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_IRS_EFILE_URL`	This world's origin followed by `/`
`WORLDS_API_KEY`	The world key, accepted wherever IRS e-file expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · fetch

const base = process.env.WORLDS_IRS_EFILE_URL;
const headers = {
  Authorization: "Bearer " + process.env.WORLDS_API_KEY,
  "Content-Type": "application/xml",
};

const res = await fetch(base + "/submissions", {
  method: "POST",
  headers,
  body: "<Return>...</Return>",
});
const ack = await res.text();

API reference

12 of 12

Submissions

Return transmissions sent for processing.

POST/submissionsTransmit a return
GET/submissions/{submissionId}Get a submission
GET/submissions/{submissionId}/statusCheck submission status

Fields · 4

`submissionId`	string	Submission id
`returnType`	string	Form family, such as 1040 or 1120
`taxYear`	integer	Tax year
`status`	string	Received, Accepted or Rejected

Acknowledgements

Accept or reject results for a transmission.

GET/acknowledgementsList acknowledgements
GET/acknowledgements/{submissionId}Get an acknowledgement
GET/acknowledgements?status=RejectedList rejected acknowledgements

Fields · 4

`submissionId`	string	Submission id
`status`	string	Accepted or Rejected
`acceptedDate`	string	Timestamp of acceptance
`errors`	array	Rejection codes and messages

Business rules

Validation rules a return is checked against.

GET/rulesList rules
GET/rules/{ruleId}Get a rule
GET/rules?form={formName}List rules for a form

Fields · 4

`ruleId`	string	Rule id, such as F1040-001
`severity`	string	Reject or alert
`message`	string	Rule text
`formName`	string	Form the rule applies to

Taxpayers

Filers and their return history.

GET/taxpayers/{taxpayerId}Get a taxpayer
GET/taxpayers/{taxpayerId}/returnsList a taxpayer's returns
GET/taxpayersList taxpayers

Fields · 4

`taxpayerId`	string	Taxpayer id
`name`	string	Filer name
`filingStatus`	string	Filing status
`returns`	array	Submission ids

Test workflow

Prepare. Select the IRS e-file setup for your workflow and review its starting records, including submissions, acknowledgements, business rules.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

SUB-4410 transmitted once
SUB-4391 resubmitted with AGI from the prior year return on file
SUB-4388 not resubmitted, routed to the preparer
No return marked Accepted without an acknowledgement
No duplicate submissions for the same taxpayer

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · IRS e-file
version: 2
connector: irs-efile
seed: irs-efile-starter
mode: isolated
policy: >
  Transmit the ready returns and fix this week's rejections. Correct AGI
  rejections from the client's prior year return on file. Anything involving a
  dependent claimed elsewhere goes back to the preparer.
tasks:
  - id: transmit-a-return-and-poll-for-acknowledgements
    prompt: Transmit a return and poll for acknowledgements
  - id: fix-a-rejected-return-by-its-business-rule-code
    prompt: Fix a rejected return by its business rule code
  - id: resubmit-within-the-perfection-period
    prompt: Resubmit within the perfection period
expected:
  - SUB-4410 transmitted once
  - SUB-4391 resubmitted with AGI from the prior year return on file
  - "SUB-4388 not resubmitted, routed to the preparer"
  - No return marked Accepted without an acknowledgement
  - No duplicate submissions for the same taxpayer
scenarios:
  - schema-error
  - business-rule
  - duplicate

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`schema-error`	A submission fails XML schema validation and is rejected
`business-rule`	IND-031-04 rejects a prior year AGI mismatch
`duplicate`	A second return for the same SSN is rejected as a duplicate
`no-acks-yet`	Polling for new acknowledgements returns none for hours

Starting data

Start each run from the same records and relationships. The overview below describes the IRS e-file starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
returns	40 Form 1040 with Schedules A, C and SE
submissions	25 Accepted, 6 Rejected, 9 Ready
rejections	Prior year AGI mismatch, missing IP PIN, duplicate dependent
acknowledgements	Queued for retrieval

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Submissions records

Submissions

Return transmissions sent for processing.

Field	Type	Meaning / relationship
`submissionId`	string	Submission id
`returnType`	string	Form family, such as 1040 or 1120
`taxYear`	integer	Tax year
`status`	string	Received, Accepted or Rejected

json · illustrative record shape

{
  "submissionId": "<Submission id>",
  "returnType": "<Form family, such as 1040 or 1120>",
  "taxYear": 1,
  "status": "<Received, Accepted or Rejected>"
}

See submissions operations

Acknowledgements records

Acknowledgements

Accept or reject results for a transmission.

Field	Type	Meaning / relationship
`submissionId`	string	Submission id
`status`	string	Accepted or Rejected
`acceptedDate`	string	Timestamp of acceptance
`errors`	array	Rejection codes and messages

json · illustrative record shape

{
  "submissionId": "<Submission id>",
  "status": "<Accepted or Rejected>",
  "acceptedDate": "<Timestamp of acceptance>",
  "errors": []
}

See acknowledgements operations

Business rules records

Business rules

Validation rules a return is checked against.

Field	Type	Meaning / relationship
`ruleId`	string	Rule id, such as F1040-001
`severity`	string	Reject or alert
`message`	string	Rule text
`formName`	string	Form the rule applies to

json · illustrative record shape

{
  "ruleId": "<Rule id, such as F1040-001>",
  "severity": "<Reject or alert>",
  "message": "<Rule text>",
  "formName": "<Form the rule applies to>"
}

See business rules operations

Taxpayers records

Taxpayers

Filers and their return history.

Field	Type	Meaning / relationship
`taxpayerId`	string	Taxpayer id
`name`	string	Filer name
`filingStatus`	string	Filing status
`returns`	array	Submission ids

json · illustrative record shape

{
  "taxpayerId": "<Taxpayer id>",
  "name": "<Filer name>",
  "filingStatus": "<Filing status>",
  "returns": []
}

See taxpayers operations

See the IRS e-file world in the catalog