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

On success, data contains the fields below. meta includes api_version and request_id. Keep request_id when reporting a problem.

Response fields

13 fields
artifact_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.

Complete response schema: ApiV1DocumentCapabilityResponse

Structure · HTTP 200
{
  "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.