E-File Magic

Deliverables

Request a download

Generate or reuse the selected format for one authorized order/form/state group and return its download capability or queued status.

POST
/api/v1/orders/deliverables/request_file
Authentication
OAuth 2.0 access token
Required scopes
deliverables.requestdocuments.read
Idempotency key
Required
Rate-limit cost
25 units

How to use this endpoint

Read the deliverable and elect only a listed artifact_option_id. Published state IRIS uses state_accepted with format=xml. Announced transitions use iris_xml_candidate and remain explicitly unconfirmed. Publication 1220 is offered only as an accepted, supported backup; its historical pub1220_candidate identifier does not itself determine acceptance. Use each descriptor’s label, candidate flag and annual instructions.

New requests use qualified_records only, preserving the exact frozen membership of the principal-authorized order/form/state. They cannot select another account or submit their own recipient list. Missing artifact_option_id defaults to state_accepted.

Confirm transmitter_details with the TCC appropriate to the chosen format and set documentation_acknowledged=true after reviewing exact annual guidance. State supplemental accounts also apply to XML when required, filling only a missing account in the transient output. Missing values return supplemental_required without scheduling. New Illinois XML generation uses a fresh transmission ID; ready-file reuse requires the exact transmitter and format cache identity.

Format choices are saved during initial materialization; existing groups retain their exact saved choices, decisions and membership. Reads do not reconstruct or upgrade them. Order materialization ready means the breakdown is ready; file status reports generation separately. Unknown or unavailable format options fail closed.

Retrying the same key and body rechecks access and can return a fresh URL. A different format has an independent cache identity. Treat download URLs as confidential and do not store them in logs.

Use plain file-format labels and explain that generating or downloading a file does not submit it to the state. Keep API option and scope identifiers unchanged; wording and date formatting are presentation only.

transmitter_details is checked against the selected encoder before immediate rendering or queue admission and again when scheduled inputs are read. For Publication 1220 variants, legal_name/company_name each allow 80 printable ASCII characters across two 40-byte fields; mailing_address/city allow 40, combined contact_first_name + space + contact_last_name allows 40, and contact_email allows 50. contact_phone must normalize to 1–15 digits and U.S. postal_code to 5 or 9 digits; foreign postal text is preserved within 9 ASCII characters; unsupported characters and overflows reject without silent truncation. These are export limits, not changes to stored APP contracts.

transmitter_control_code may be empty for state formats that do not require it. XML, Publication 1220 variants and Publication 1187 require five uppercase alphanumeric characters. The service checks structural validity rather than IRS enrollment. State XML downloads use production TestCd=P and exact annual XML/state validation independently of federal ATS configuration; no federal transmission is performed. Cache identity version 4 prevents reuse of older rendering semantics; a previous in-flight generation that no longer matches must be requested afresh.

Retrying a request? Keep the same idempotency key and body after an uncertain result. A different key can repeat the action.

cURL request
curl --request POST 'https://api.efilemagic.com/api/v1/orders/deliverables/request_file' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Idempotency-Key: <unique-operation-key>' \
  --header 'Content-Type: application/json' \
  --data-binary @request.json

Replace placeholders with your own values. Use the API resource origin provided for your environment.

Create request.json using the documented fields. Field descriptions are not sample values.