E-File Magic

Filings

Read filing readiness

Read saved readiness counts and a few focused examples for a filer or account year.

POST
/api/v1/filings/readiness
Authentication
OAuth 2.0 access token
Required scopes
filers.readrecipients.readforms.read
Idempotency key
Not required
Rate-limit cost
10 units

How to use this endpoint

Requires filers.read, recipients.read and forms.read. Provide filer_id, or tax_year for an account overview. Account overview additionally requires orders.read and access to all filers.

Reuses the built-in assistant readiness service. Counts describe recipients, not error totals; updating or unavailable counts are unknown. At most five examples are returned. The agent does not run validation or certify filing eligibility.

Per-filer tin_matching observations distinguish unchecked, already matched, pending and adverse results for filing-ready unreleased recipients. Only offer_matching recommends an optional separate purchase. Up to two sparse-index pages and 100 strong metadata rereads keep the operation bounded; partial/unknown coverage never means all matched. Existing indexes and lifecycle flags are reused without a projection backfill.

cURL request
curl --request POST 'https://api.efilemagic.com/api/v1/filings/readiness' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data-binary @request.json

Replace 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.