Recipients
Read saved validation issues
Identify fields with saved validation issues for one authorized recipient.
/api/v1/recipients/issues- Authentication
- OAuth 2.0 access token
- Required scopes
recipients.readforms.read- Idempotency key
- Not required
- Rate-limit cost
- 2 units
How to use this endpoint
Requires recipients.read and forms.read. Supply both filer_id and recipient_id; optional tax_year, form_id and exact annual field narrow the saved scope.
Returns safe field labels and counts, not private values or raw diagnostic messages. Reads at most five forms, eight field groups and 64 issue entries. Empty or truncated examples do not prove validity.
curl --request POST 'https://api.efilemagic.com/api/v1/recipients/issues' \
--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
5 fieldsfiler_idRequiredstring (uuid)
ID of the filer that owns this operation's records.
recipient_idRequiredstring (uuid)
ID of the recipient within the selected filer.
fieldOptionalstring | null
Exact APP field ID from the saved annual form contract. Minimum characters: 1. Maximum characters: 100.
form_idOptionalstring | null
Form identifier from the catalog for this tax year and schema revision. Allowed values: "1042_s", "1097_btc", "1098", "1098_c", "1098_e", "1098_f", "1098_q", "1098_t", "1098_vli", "1099_a", "1099_b", "1099_c", "1099_cap", "1099_da", "1099_div", "1099_g", "1099_h", "1099_int", "1099_k", "1099_lps", "1099_ls", "1099_ltc", "1099_misc", "1099_nec", "1099_oid", "1099_patr", "1099_q", "1099_qa", "1099_r", "1099_s", "1099_sa", "1099_sb", "3921", "3922", "5498", "5498_esa", "5498_qa", "5498_sa", "5498_ta", "15397", "8027", "8596", "8809", "8955_ssa", "w_2g".
tax_yearOptionalinteger | null
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/recipients/issues' \
--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
2 fieldsevidenceAlways returnedobject
Unknown fields are rejected.
Nested fields (17)
archivedAlways returnedboolean
Type: boolean.
details_truncatedAlways returnedboolean
Type: boolean.
examples_exhaustiveAlways returnedfalse
Value: false.
field_filterAlways returnedstring | null
Type: string | null.
field_limitAlways returnedinteger
Minimum: 0.
fieldsAlways returnedarray<object>
Maximum items: 8.
Nested fields (3)
fieldAlways returnedstring | null
Type: string | null.
labelAlways returnedstring
Type: string.
sampled_issue_countAlways returnedinteger
Minimum: 0.
filer_idAlways returnedstring (uuid)
Type: string (uuid).
formsAlways returnedarray<object>
Maximum items: 5.
Nested fields (4)
error_countAlways returnedinteger
Minimum: 0.
form_idAlways returnedstring
Allowed values: "1042_s", "1097_btc", "1098", "1098_c", "1098_e", "1098_f", "1098_q", "1098_t", "1098_vli", "1099_a", "1099_b", "1099_c", "1099_cap", "1099_da", "1099_div", "1099_g", "1099_h", "1099_int", "1099_k", "1099_lps", "1099_ls", "1099_ltc", "1099_misc", "1099_nec", "1099_oid", "1099_patr", "1099_q", "1099_qa", "1099_r", "1099_s", "1099_sa", "1099_sb", "3921", "3922", "5498", "5498_esa", "5498_qa", "5498_sa", "5498_ta", "15397", "8027", "8596", "8809", "8955_ssa", "w_2g".
has_errorsAlways returnedboolean
Type: boolean.
tax_yearAlways returnedinteger
Allowed values: 2022, 2023, 2024, 2025, 2026.
inspected_issue_entriesAlways returnedinteger
Minimum: 0.
inspection_limitAlways returnedinteger
Minimum: 0.
is_validatedAlways returnedboolean
Type: boolean.
nameAlways returnedstring
Type: string.
notesAlways returnedstring
Type: string.
recipient_idAlways returnedstring (uuid)
Type: string (uuid).
recipient_validation_issue_countAlways returnedinteger
Minimum: 0.
releasedAlways returnedboolean
Type: boolean.
statusAlways returnedstring
Allowed values: "active", "disabled", "archived".
linksAlways returnedarray<object>
Maximum items: 1.
Nested fields (2)
hrefAlways returnedstring
Type: string.
labelAlways returnedstring
Type: string.
{
"data": {
"evidence": "object",
"links": "array<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.
- 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.