Saved filing reviews
Prepare a saved filing review
Prepare a fixed selection for the authorizing user to review.
/api/v1/filing-reviews/prepare- Authentication
- OAuth 2.0 access token
- Required scopes
orders.previewrecipients.readforms.readfilers.read- Idempotency key
- Required
- Rate-limit cost
- 15 units
How to use this endpoint
This REST workflow requires delegated agent authorization and 1–10 distinct original recipients with their current versions and exact annual form contract. It returns a review link and expiration without approving, charging or submitting. For the MCP checkout workflow, use orders/checkout/request instead; its filer/year workflow has no form-count ceiling.
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/filing-reviews/prepare' \
--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.
filer_versionRequiredinteger
Current filer version used to check that the reviewed filer has not changed. Minimum: 1.
recipientsRequiredarray<object>
Recipients and current versions included in the saved filing review. Distinct original recipients and their current versions. Minimum items: 1. Maximum items: 10.
Nested fields (2)
recipient_idRequiredstring (uuid)
Type: string (uuid).
versionRequiredinteger
Minimum: 1.
servicesRequiredobject
Unknown fields are rejected.
Nested fields (3)
irs_spec_fileRequiredboolean
Type: boolean.
print_mailRequiredboolean
Type: boolean.
state_efileRequiredfalse
Direct State E-File is unavailable. Value: false.
tupleRequiredobject
Unknown fields are rejected.
Nested fields (4)
form_idRequiredstring
Exact form identifier from the annual catalog.
schema_releaseRequiredstring
Exact release returned for this form/year/revision.
schema_revRequired3
Value: 3.
tax_yearRequiredinteger
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/filing-reviews/prepare' \
--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
4 fieldsexpires_atAlways returnedinteger
Unix seconds.
order_idAlways returnedstring (uuid)
Type: string (uuid).
review_idAlways returnedstring (uuid)
Type: string (uuid).
review_urlAlways returnedstring (uri)
Open in the browser for the originating user's review and explicit checkout.
{
"data": {
"expires_at": "integer",
"order_id": "string (uuid)",
"review_id": "string (uuid)",
"review_url": "string (uri)"
},
"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.