PDFs
Preview recipient PDFs
Generate recipient forms using the selected annual template.
/api/v1/recipients/print- Authentication
- OAuth 2.0 access token
- Required scopes
recipients.readforms.readdocuments.readtax_ids.read- Idempotency key
- Required
- Rate-limit cost
- 25 units
How to use this endpoint
This operation requires a delegated user and both documents.read and tax_ids.read. Immediate results contain url; scheduled results contain export_id; pass that value in job_ids when polling. No email is sent. Missing templates return an error. After an uncertain result, keep the original idempotency key; do not automatically create another print request with a fresh key.
This endpoint prints current saved recipient data. Historical order-snapshot PDFs are available through the authenticated application’s Recipient History → View released PDF action; this public API endpoint does not accept an order_id selector.
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/recipients/print' \
--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
5 fieldsfiler_idRequiredstring (uuid)
ID of the filer that owns this operation's records.
form_idRequiredstring
Form identifier from the catalog for this tax year and schema revision.
recipient_idRequiredstring (uuid)
ID of the recipient within the selected filer.
schema_revRequiredinteger
Exact application schema revision selected from the form catalog. Minimum: 1.
tax_yearRequiredinteger
Tax year of the filer and forms being processed. Allowed values: 2022, 2023, 2024, 2025, 2026.
Headers (2)
AuthorizationRequired- OAuth Bearer token with the listed scopes and current resource authorization.
Idempotency-KeyRequired- Reuse the same key and request after an uncertain response.
curl --request POST 'https://api.efilemagic.com/api/v1/recipients/print' \
--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.
immediate response
immediate response fields
11 fieldsexecution_modeAlways returned"immediate"
Value: "immediate".
expires_at_epochAlways returnedinteger
Type: integer.
filer_idAlways returnedstring (uuid)
Type: string (uuid).
form_idAlways returnedstring
Type: string.
page_countAlways returnedinteger
Type: integer.
recipient_idAlways returnedstring (uuid)
Type: string (uuid).
schema_revAlways returnedinteger
Type: integer.
statement_countAlways returnedinteger
Type: integer.
tax_yearAlways returnedinteger
Allowed values: 2022, 2023, 2024, 2025, 2026.
transaction_countAlways returnedinteger
Type: integer.
urlAlways returnedstring (uri)
Type: string (uri).
scheduled response
scheduled response fields
11 fieldsalready_scheduledAlways returnedboolean
Type: boolean.
chunk_sizeAlways returnedinteger
Type: integer.
download_urlMay be omittedstring (uri)
Type: string (uri).
execution_modeAlways returned"scheduled"
Value: "scheduled".
export_idAlways returnedstring (uuid)
Type: string (uuid).
filer_idAlways returnedstring (uuid)
Type: string (uuid).
form_idMay be omittedstring
Type: string.
modeAlways returnedstring
Allowed values: "all", "corrected", "uncorrected".
recipient_form_countAlways returnedinteger
Type: integer.
statusAlways returnedstring
Allowed values: "queued", "processing", "merging", "completed", "failed".
tax_yearAlways returnedinteger
Allowed values: 2022, 2023, 2024, 2025, 2026.
{
"data": "object | object",
"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.