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

Request fields

9 fields
form_idRequiredstring

Form identifier from the catalog for this tax year and schema revision. Minimum characters: 1. Maximum characters: 64.

order_idRequiredstring (uuid)

ID of the order to read or download from.

state_codeRequiredstring

State for the requested deliverable. Pattern: ^[A-Z]{2}$

artifact_option_idOptionalstring

Allowed values: "state_accepted", "iris_xml_candidate", "pub1220_candidate".

documentation_acknowledgedOptionalboolean

Default: false.

record_scopeOptionalstring | null

Select the records to include in the requested deliverable. Allowed values: "qualified_records", "all_state_records", "withholding_only".

service_codeOptionalstring | null

Service whose deliverable you want to read or request. Allowed values: "efile", "e_delivery", "state_efile", "print_mail", "irs_spec_file".

state_supplemental_valuesOptionalarray<object>

State-specific values required by the deliverable's current filing instructions. Maximum items: 20.

Nested fields (2)

field_idRequiredstring

Minimum characters: 1. Maximum characters: 64.

valueRequiredstring

Maximum characters: 128.

transmitter_detailsOptionalobject | null

Confirmed submitter details are validated against the selected saved output option before generation and on worker resume. Publication 1220 permits 80 characters each for legal_name and company_name (two 40-position lines), 40 for mailing_address and city, 40 for the combined contact_first_name plus space plus contact_last_name, and 50 for contact_email; text must be printable ASCII. The telephone permits 1-15 digits with formatting punctuation; a U.S. ZIP code must contain 5 or 9 digits; foreign postal text is preserved within 9 ASCII characters. Values are never silently truncated. These export constraints do not restrict canonical APP records or IRIS XML to Publication 1220 widths. Unknown fields are rejected.

Nested fields (15)

cityRequiredstring

Minimum characters: 1. Maximum characters: 120.

company_nameRequiredstring

Minimum characters: 1. Maximum characters: 80.

contact_emailRequiredstring

Minimum characters: 1. Maximum characters: 254.

contact_first_nameRequiredstring

Minimum characters: 1. Maximum characters: 80.

contact_last_nameRequiredstring

Minimum characters: 1. Maximum characters: 80.

contact_phoneRequiredstring

Minimum characters: 1. Maximum characters: 32.

foreign_entityRequiredboolean

Type: boolean.

legal_nameRequiredstring

Minimum characters: 1. Maximum characters: 80.

mailing_addressRequiredstring

Minimum characters: 1. Maximum characters: 160.

override_tinOptionalstring | null

Pattern: ^[0-9]{9}$

postal_codeRequiredstring

Minimum characters: 1. Maximum characters: 12.

stateRequiredstring

Minimum characters: 1. Maximum characters: 2. Pattern: ^[A-Z]{2}$

tin_submitted_type_cdRequiredstring

Allowed values: "BUSINESS_TIN", "INDIVIDUAL_TIN".

transmitter_control_codeRequiredstring

Five uppercase alphanumeric characters are required for IRIS XML, Publication 1220 and Publication 1187. Other output formats may use an empty string. This structural check is not IRS enrollment verification. Pattern: ^([A-Z0-9]{5})?$

use_frozen_filer_tinRequiredboolean

Type: boolean.

Headers (3)
AuthorizationRequired
OAuth RS256 access token issued for the EFM API resource. Interactive EFM session tokens are rejected.
Idempotency-KeyRequired
Opaque caller-generated key bound to resolved tenant, connection, actor, exact route, and request. No presigned URL is stored for replay.
DPoPConditional / optional
Required when the application, connection, or credential is proof-of-possession bound.

Complete request schema: ApiV1OrderDeliverableRequestFileRequest

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.

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