Dashboard
Read dashboard totals
Read the saved account dashboard for a selected tax year.
/api/v1/dashboard/summary- Authentication
- OAuth 2.0 access token
- Required scopes
filers.readrecipients.readorders.read- Idempotency key
- Not required
- Rate-limit cost
- 2 units
How to use this endpoint
Requires filers.read, recipients.read and orders.read, plus access to all filers. A connection restricted to selected filers must use filing readiness for an allowed filer.
Counts use the normal dashboard projection and may lag edits. Preserve generated_at and freshness when presenting them. Reading a summary does not submit an order.
curl --request POST 'https://api.efilemagic.com/api/v1/dashboard/summary' \
--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
1 fieldstax_yearRequiredinteger
Tax year of the filer and forms being processed. Allowed values: 2022, 2023, 2024, 2025, 2026.
Headers (1)
AuthorizationRequired- OAuth Bearer token with current resource authorization and the required scopes.
curl --request POST 'https://api.efilemagic.com/api/v1/dashboard/summary' \
--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
6 fieldsfreshnessAlways returnedstring
Allowed values: "fresh", "stale", "building".
generated_atAlways returnedstring
Type: string.
last_materialized_atAlways returnedstring | null
Type: string | null.
next_actionsAlways returnedarray<object>
Maximum items: 100.
Nested fields (5)
countAlways returnedinteger
Minimum: 0.
hrefAlways returnedstring
Type: string.
kindAlways returnedstring
Allowed values: "create_filer", "add_recipients", "review_recipients", "preview_pdfs", "release_order", "review_order", "view_orders".
labelAlways returnedstring
Type: string.
severityAlways returnedstring
Allowed values: "info", "warning", "danger", "success".
summaryAlways returnedobject
Unknown fields are rejected.
Nested fields (11)
active_recipient_countAlways returnedinteger
Minimum: 0.
filer_countAlways returnedinteger
Minimum: 0.
orders_completed_countAlways returnedinteger
Minimum: 0.
orders_needs_attention_countAlways returnedinteger
Minimum: 0.
orders_processing_countAlways returnedinteger
Minimum: 0.
orders_total_countAlways returnedinteger
Minimum: 0.
release_ready_recipient_countAlways returnedinteger
Minimum: 0.
released_recipient_countAlways returnedinteger
Minimum: 0.
tin_match_needed_countAlways returnedinteger
Minimum: 0.
tin_match_pending_countAlways returnedinteger
Minimum: 0.
unvalidated_recipient_countAlways returnedinteger
Minimum: 0.
tax_yearAlways returnedinteger | null
Allowed values: 2022, 2023, 2024, 2025, 2026.
{
"data": {
"freshness": "string",
"generated_at": "string",
"last_materialized_at": "string | null",
"next_actions": "array<object>",
"summary": "object",
"tax_year": "integer | 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.