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.
/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 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.jsonReplace 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.
Request fields
9 fieldsform_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 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.jsonReplace 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.
On success, data contains the fields below. meta includes api_version and request_id. Keep request_id when reporting a problem.
Response fields
13 fieldsartifact_idMay be omittedstring | null
Maximum characters: 512.
artifact_option_idAlways returnedstring
Allowed values: "state_accepted", "iris_xml_candidate", "pub1220_candidate".
download_urlMay be omittedstring (uri) | null
Short-lived artifact-scoped capability; never a raw storage key. Maximum characters: 4096.
execution_modeAlways returnedstring
Allowed values: "cached", "immediate", "scheduled", "not_generated", "supplemental_required".
expires_atMay be omittedstring (date-time) | null
Type: string (date-time) | null.
form_idAlways returnedstring
Maximum characters: 64.
messageMay be omittedstring | null
Maximum characters: 1024.
order_idAlways returnedstring (uuid)
Type: string (uuid).
record_scopeAlways returnedstring
Allowed values: "qualified_records", "all_state_records", "withholding_only".
service_codeAlways returnedstring
Allowed values: "efile", "e_delivery", "state_efile", "print_mail", "irs_spec_file".
state_codeAlways returnedstring
Pattern: ^[A-Z]{2}$
state_outputAlways returnedobject
Unknown fields are rejected.
Nested fields (24)
actionableAlways returnedboolean
Type: boolean.
allowed_record_scopesMay be omittedarray<string>
Items must be unique.
artifact_optionsMay be omittedarray<object>
Type: array<object>.
Nested fields (5)
candidateAlways returnedboolean
Type: boolean.
descriptionAlways returnedstring
Minimum characters: 1.
labelAlways returnedstring
Minimum characters: 1.
option_idAlways returnedstring
Allowed values: "state_accepted", "iris_xml_candidate", "pub1220_candidate".
requires_documentation_acknowledgementAlways returnedboolean
Type: boolean.
cfsf_statusAlways returnedstring
Allowed values: "not_applicable", "not_selected", "planned", "included_in_attempt", "accepted", "failed".
decisionAlways returnedstring
Allowed values: "generated", "not_required", "manual_review_required", "unsupported_format", "blocked_by_missing_data".
default_record_scopeMay be omittedstring | null
Allowed values: "qualified_records", "all_state_records", "withholding_only".
formatAlways returnedstring
Allowed values: "pub1187", "pub1220", "pub1220_variant", "pub1220_zip", "duplicate_irs_pub1220", "csv", "xml", "fixed_text", "portal_manual", "manual_verify", "unsupported".
format_labelAlways returnedstring
Maximum characters: 256.
generation_capabilityAlways returnedstring
Allowed values: "generated", "manual", "unsupported", "no_artifact".
obligationAlways returnedstring
Allowed values: "direct_required", "direct_optional", "satisfied_by_cfsf", "not_required", "required_missing_information", "required_manual", "required_unsupported".
package_profileAlways returnedstring
Allowed values: "no_artifact", "single_form_artifact", "hawaii_n196", "enc3", "rev1667", "wht434".
qualified_recipient_countAlways returnedinteger
Minimum: 0.
qualified_recipient_digestMay be omittedstring | null
Pattern: ^[a-f0-9]{64}$
reasonMay be omittedstring | null
Maximum characters: 2048.
reason_codeAlways returnedstring
Minimum characters: 1. Maximum characters: 128.
renderer_revisionAlways returnedstring
Minimum characters: 1. Maximum characters: 128.
rule_catalog_digestAlways returnedstring
Minimum characters: 1. Maximum characters: 128.
rule_idAlways returnedstring
Minimum characters: 1. Maximum characters: 256.
rule_revisionAlways returnedstring
Minimum characters: 1. Maximum characters: 128.
source_evidence_sha256Always returnedarray<string>
Items must be unique.
source_refAlways returnedstring
Maximum characters: 4096.
spec_urlAlways returnedstring
Maximum characters: 4096.
supplemental_fieldsMay be omittedarray<object>
Maximum items: 20.
Nested fields (9)
field_idAlways returnedstring
Minimum characters: 1. Maximum characters: 64.
help_textAlways returnedstring
Maximum characters: 1024.
labelAlways returnedstring
Minimum characters: 1. Maximum characters: 128.
max_lenAlways returnedinteger
Minimum: 1. Maximum: 128.
redactedAlways returnedboolean
Type: boolean.
requiredAlways returnedboolean
Type: boolean.
scopeAlways returnedstring
Minimum characters: 1. Maximum characters: 64.
validation_ruleAlways returnedstring
Minimum characters: 1. Maximum characters: 64.
write_targetAlways returnedstring
Minimum characters: 1. Maximum characters: 128.
triggerAlways returnedstring
Maximum characters: 256.
{
"data": {
"artifact_id": "string | null",
"artifact_option_id": "string",
"download_url": "string (uri) | null",
"execution_mode": "string",
"expires_at": "string (date-time) | null",
"form_id": "string",
"message": "string | null",
"order_id": "string (uuid)",
"record_scope": "string",
"service_code": "string",
"state_code": "string",
"state_output": "object",
"status": "string"
},
"meta": {
"api_version": "v1",
"request_id": "string"
}
}Successful response structure. This outline shows field types, not a response to copy. Expand Response fields for nested properties and optional values.
Errors to handle
Errors use {error: {code, message}, meta}. Check the code and message before retrying. Authentication, validation and availability errors can occur before the operation runs.
- 400
invalid_request - Check required fields, selectors and supported values.
- 401
invalid_token - Obtain a valid OAuth token for this resource. Check its expiry and current authorization.
- 403
insufficient_scope - Request the listed scopes through the application's authorization flow.
- 403
forbidden - Check the connection's permissions and allowed filers. More scopes alone may not grant access.
- 404
not_found - Check the resource ID and its owning filer. Batch reads report missing IDs as documented.
- 409
conflict - Read the current state and resolve the conflict. Do not change the body under an existing idempotency key.
- 412
precondition_failed - Read the current version or preview again; a required precondition has changed.
- 422
validation_failed - Correct the reported validation issues before retrying.
- 429
rate_limited - Wait for Retry-After before retrying. Avoid concurrent retries.
- 500
internal_error - Retain request_id and retry an uncertain result with the same body and idempotency key.
- 503
service_unavailable - Retry with bounded backoff, preserving the body and idempotency key.