Deliverables
Get a deliverable
Read the available files and instructions for one order's deliverable.
/api/v1/orders/deliverables/get- Authentication
- OAuth 2.0 access token
- Required scopes
deliverables.read- Idempotency key
- Not required
- Rate-limit cost
- 1 unit
How to use this endpoint
The default service is irs_spec_file. State groups include filing instructions and official links when available. Request a file separately when you are ready to download it.
reviewed_at is a calendar date. Display it in the viewer’s regional format without shifting the day for their time zone. Update and expiry timestamps represent instants and should use the viewer’s time zone.
For efile and tin_matching results, materialization_status and each format status govern file availability. Final IRS outcomes may precede ready downloads. Excel is the xlsx wire format. Refresh metadata while preparation is pending; do not infer download readiness from accepted counts or request a new filing to obtain result files.
curl --request POST 'https://api.efilemagic.com/api/v1/orders/deliverables/get' \
--header 'Authorization: Bearer <access-token>' \
--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
2 fieldsorder_idRequiredstring (uuid)
ID of the order to read or download from.
service_codeOptionalstring | null
Service whose deliverable you want to read or request. Allowed values: "efile", "e_delivery", "state_efile", "print_mail", "irs_spec_file".
Headers (2)
AuthorizationRequired- OAuth RS256 access token issued for the EFM API resource. Interactive EFM session tokens are rejected.
DPoPConditional / optional- Required when the application, connection, or credential is proof-of-possession bound.
curl --request POST 'https://api.efilemagic.com/api/v1/orders/deliverables/get' \
--header 'Authorization: Bearer <access-token>' \
--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.
On success, data contains the fields below. meta includes api_version and request_id. Keep request_id when reporting a problem.
Response fields
3 fieldsgroupsAlways returnedarray<object>
Type: array<object>.
Nested fields (18)
artifact_idMay be omittedstring | null
Maximum characters: 512.
artifact_option_idMay be omittedstring | null
Allowed values: "state_accepted", "iris_xml_candidate", "pub1220_candidate".
documentationAlways returnedobject
Unknown fields are rejected.
Nested fields (10)
availableAlways returnedboolean
Type: boolean.
official_sourcesAlways returnedarray<object>
Type: array<object>.
Nested fields (2)
titleAlways returnedstring
Minimum characters: 1. Maximum characters: 512.
urlAlways returnedstring (uri)
Pattern: ^https://
reviewed_atMay be omittedstring (date) | null
Type: string (date) | null.
sectionsAlways returnedarray<object>
Type: array<object>.
Nested fields (3)
bulletsAlways returnedarray<string>
Type: array<string>.
headingAlways returnedstring
Minimum characters: 1. Maximum characters: 512.
paragraphsAlways returnedarray<string>
Type: array<string>.
state_codeAlways returnedstring
Pattern: ^[A-Z]{2}$
state_nameAlways returnedstring
Minimum characters: 1. Maximum characters: 128.
summaryMay be omittedstring | null
Minimum characters: 1.
tax_yearAlways returnedinteger
Allowed values: 2022, 2023, 2024, 2025, 2026.
titleAlways returnedstring
Minimum characters: 1. Maximum characters: 512.
unavailable_reasonMay be omittedstring | null
Minimum characters: 1.
expires_atMay be omittedstring (date-time) | null
Type: string (date-time) | null.
file_record_scopeMay be omittedstring | null
Allowed values: "qualified_records", "all_state_records", "withholding_only".
file_statusAlways returnedstring
Allowed values: "not_requested", "queued", "processing", "ready", "expired", "failed".
form_idAlways returnedstring
Minimum characters: 1. Maximum characters: 64.
last_errorMay be omittedstring | null
Maximum characters: 2048.
materialization_statusAlways returnedstring
Allowed values: "snapshot_pending", "materializing", "ready", "failed", "canceled".
order_idAlways returnedstring (uuid)
Type: string (uuid).
recipient_countAlways returnedinteger
Minimum: 0.
record_countAlways returnedinteger
Minimum: 0.
service_codeAlways returnedstring
Allowed values: "efile", "e_delivery", "state_efile", "print_mail", "irs_spec_file".
state_codeAlways returnedstring
Pattern: ^[A-Z]{2}$
state_metricsAlways returnedobject
Unknown fields are rejected.
Nested fields (8)
local_withholding_recipient_countAlways returnedinteger
Minimum: 0.
local_withholding_total_centsAlways returnedinteger
Minimum: 0.
missing_state_account_recipient_countAlways returnedinteger
Minimum: 0.
state_income_recipient_countAlways returnedinteger
Minimum: 0.
state_income_total_centsAlways returnedinteger
Minimum: 0.
state_withholding_recipient_countAlways returnedinteger
Minimum: 0.
state_withholding_total_centsAlways returnedinteger
Minimum: 0.
withholding_missing_state_account_recipient_countAlways returnedinteger
Minimum: 0.
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.
tax_yearAlways returnedinteger
Allowed values: 2022, 2023, 2024, 2025, 2026.
updated_atAlways returnedstring (date-time)
Type: string (date-time).
orderAlways returnedobject
Unknown fields are rejected.
Nested fields (14)
created_atAlways returnedstring (date-time)
Type: string (date-time).
filer_idAlways returnedstring (uuid)
Type: string (uuid).
filer_nameMay be omittedstring | null
Maximum characters: 512.
group_countAlways returnedinteger
Minimum: 0.
last_errorMay be omittedstring | null
Maximum characters: 2048.
materialization_statusAlways returnedstring
Allowed values: "snapshot_pending", "materializing", "ready", "failed", "canceled".
order_idAlways returnedstring (uuid)
Type: string (uuid).
public_order_refMay be omittedstring | null
Maximum characters: 128.
recipient_countAlways returnedinteger
Minimum: 0.
record_countAlways returnedinteger
Minimum: 0.
service_codeAlways returnedstring
Allowed values: "efile", "e_delivery", "state_efile", "print_mail", "irs_spec_file".
service_nameAlways returnedstring
Minimum characters: 1. Maximum characters: 128.
tax_yearAlways returnedinteger
Allowed values: 2022, 2023, 2024, 2025, 2026.
updated_atAlways returnedstring (date-time)
Type: string (date-time).
transmitter_defaultsMay be omittedobject | 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 (13)
cityAlways returnedstring
Type: string.
company_nameAlways returnedstring
Type: string.
contact_emailAlways returnedstring
Type: string.
contact_first_nameAlways returnedstring
Type: string.
contact_last_nameAlways returnedstring
Type: string.
contact_phoneAlways returnedstring
Type: string.
foreign_entityAlways returnedboolean
Type: boolean.
legal_nameAlways returnedstring
Type: string.
mailing_addressAlways returnedstring
Type: string.
postal_codeAlways returnedstring
Type: string.
stateAlways returnedstring
Type: string.
tin_last_fourAlways returnedstring
Pattern: ^[0-9]{0,4}$
tin_submitted_type_cdAlways returnedstring
Allowed values: "BUSINESS_TIN", "INDIVIDUAL_TIN".
{
"data": {
"groups": "array<object>",
"order": "object",
"transmitter_defaults": "object | null"
},
"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.
- 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; retry with bounded backoff.
- 503
service_unavailable - Retry with bounded backoff.