Recipients
List recipients
Find recipients under a filer your connection can access.
/api/v1/recipients/list- Authentication
- OAuth 2.0 access token
- Required scopes
recipients.read- Idempotency key
- Not required
- Rate-limit cost
- 1 unit
How to use this endpoint
Provide filer_id and follow next_cursor with the same filters. Tax IDs are masked in list responses.
curl --request GET 'https://api.efilemagic.com/api/v1/recipients/list' \
--header 'Authorization: Bearer <access-token>' \
--get \
--data-urlencode 'filer_id=<filer_id>' \
--data-urlencode 'limit=25'Replace placeholders with your own values. Use the API resource origin provided for your environment.
Request fields
9 fieldsquery.filer_idRequiredstring (uuid)
ID of the filer that owns this operation's records.
query.qOptionalstring
Search text used to filter this collection. Maximum characters: 256.
query.is_archivedOptionalboolean
Filter by archive state.
query.state_filterOptionalstring
Allowed values: "all", "unvalidated", "corrected".
query.form_idOptionalstring
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".
query.sort_byOptionalstring
Field used to order results. Allowed values: "created_at", "name", "relevance".
query.sort_orderOptionalstring
Ascending or descending result order. Allowed values: "asc", "desc".
query.limitOptionalinteger
Maximum number of results requested for this page. Minimum: 1. Maximum: 100.
query.cursorOptionalstring
Opaque next_cursor from the previous page. Keep the other filters unchanged. Minimum characters: 1. Maximum characters: 2048.
Headers (2)
AuthorizationRequired- OAuth RS256 access token issued for the EFM API resource. Interactive EFM session tokens are rejected.
DPoPConditional / optional- Required when the application, connection, or credential is proof-of-possession bound.
curl --request GET 'https://api.efilemagic.com/api/v1/recipients/list' \
--header 'Authorization: Bearer <access-token>' \
--get \
--data-urlencode 'filer_id=<filer_id>' \
--data-urlencode 'limit=25'Replace placeholders with your own values. Use the API resource origin provided for your environment.
On success, data contains the fields below. meta includes api_version and request_id. Keep request_id when reporting a problem.
Response fields
3 fieldsitemsAlways returnedarray<object>
Maximum items: 100.
Nested fields (58)
address_line1May be omittedstring
Common projection maintained by the backend from canonical APP form data on writes. Read-only as a business value: supplying this field to recipient upsert does not change it. Use data_app.forms for authoritative IRS field values. Existing historical records are not rewritten by reads; Tax ID redaction still applies.
address_line2May be omittedstring
Common projection maintained by the backend from canonical APP form data on writes. Read-only as a business value: supplying this field to recipient upsert does not change it. Use data_app.forms for authoritative IRS field values. Existing historical records are not rewritten by reads; Tax ID redaction still applies.
app_revisionMay be omittedstring
Type: string.
arch_bucketAlways returnedstring
Type: string.
cityMay be omittedstring
Common projection maintained by the backend from canonical APP form data on writes. Read-only as a business value: supplying this field to recipient upsert does not change it. Use data_app.forms for authoritative IRS field values. Existing historical records are not rewritten by reads; Tax ID redaction still applies.
company_nameMay be omittedstring
Common projection maintained by the backend from canonical APP form data on writes. Read-only as a business value: supplying this field to recipient upsert does not change it. Use data_app.forms for authoritative IRS field values. Existing historical records are not rewritten by reads; Tax ID redaction still applies.
correction_typeAlways returnedstring
Type: string.
countryMay be omittedstring
Common projection maintained by the backend from canonical APP form data on writes. Read-only as a business value: supplying this field to recipient upsert does not change it. Use data_app.forms for authoritative IRS field values. Existing historical records are not rewritten by reads; Tax ID redaction still applies.
created_atAlways returnedstring
Type: string.
data_appAlways returnedobject
Unknown fields are rejected.
Nested fields (1)
formsMay be omittedarray<object>
Type: array<object>.
Nested fields (21)
app_revisionAlways returnedinteger
Type: integer.
correction_codeAlways returnedstring
Type: string.
correction_typeMay be omittedstring
Type: string.
dataMay be omittedvalue
Form values under the exact annual APP contract returned by the form catalog.
data_refMay be omittedstring
Type: string.
data_sha256May be omittedstring
Type: string.
error_countAlways returnedinteger
Type: integer.
filer_revisionMay be omittedinteger
Type: integer.
fire_revisionMay be omittedinteger
Type: integer.
fire_translation_contract_idMay be omittedstring
Type: string.
form_idAlways returnedstring
Type: string.
has_errorsAlways returnedboolean
Type: boolean.
iris_revisionAlways returnedinteger
Type: integer.
iris_translation_contract_idAlways returnedstring
Type: string.
is_correctedMay be omittedboolean
Type: boolean.
schema_revAlways returnedinteger
Type: integer.
statusAlways returnedstring
Type: string.
tax_yearAlways returnedinteger
Type: integer.
unique_record_idMay be omittedstring
Type: string.
updated_atAlways returnedstring
Type: string.
validation_issuesMay be omittedarray<object>
Type: array<object>.
Nested fields (4)
codeAlways returnedstring
Type: string.
fieldMay be omittedstring
Type: string.
messageAlways returnedstring
Type: string.
originMay be omittedstring
Type: string.
display_nameAlways returnedstring
Type: string.
emailMay be omittedstring
Type: string.
filer_idAlways returnedstring (uuid)
Type: string (uuid).
filing_outcomeMay be omittedobject
Latest recorded IRS filing outcome and response summary. Absent until an outcome has been recorded. Provider acceptance and required customer action are distinct. Unknown fields are rejected.
Nested fields (20)
attempt_started_atAlways returnedstring
Type: string.
bucket_idAlways returnedstring
Type: string.
decision_digestAlways returnedstring
Type: string.
evidence_digestAlways returnedstring
Type: string.
filing_kindAlways returnedstring
Allowed values: "original", "correction".
generationAlways returnedinteger
Type: integer.
item_idAlways returnedstring
Type: string.
observed_atAlways returnedstring
Type: string.
order_idAlways returnedstring (uuid)
Type: string (uuid).
received_atAlways returnedstring | null
Type: string | null.
record_idAlways returnedinteger
Type: integer.
record_priorityAlways returnedinteger
Type: integer.
recovery_case_idAlways returnedstring | null
Type: string | null.
response_generationAlways returnedinteger
Type: integer.
retry_source_run_idAlways returnedstring | null
Type: string | null.
run_idAlways returnedstring
Type: string.
submission_idAlways returnedstring
Type: string.
submitted_atAlways returnedstring | null
Type: string | null.
summaryAlways returnedobject
Unknown fields are rejected.
Nested fields (9)
acceptanceAlways returnedstring
Allowed values: "accepted", "rejected", "processing", "undetermined".
conditionsAlways returnedarray<string>
Type: array<string>.
contract_digestAlways returnedstring
Type: string.
contract_versionAlways returnedstring
Historical outcomes retain their recorded response-policy version; this is independent of the APP form revision. Allowed values: "iris_response_contract_v1", "iris_response_contract_v2".
inherited_rejectionAlways returnedboolean
Type: boolean.
issue_countAlways returnedinteger
Minimum: 0.
next_actionAlways returnedstring
Allowed values: "none", "correct", "repair_rejected", "review", "technical_handling", "new_original".
terminal_reasonAlways returnedstring | null
Type: string | null.
unmatched_issue_countAlways returnedinteger
Minimum: 0.
transmission_idAlways returnedstring
Type: string.
fire_revisionMay be omittedstring
Type: string.
first_nameMay be omittedstring
Common projection maintained by the backend from canonical APP form data on writes. Read-only as a business value: supplying this field to recipient upsert does not change it. Use data_app.forms for authoritative IRS field values. Existing historical records are not rewritten by reads; Tax ID redaction still applies.
from_importAlways returnedboolean
Type: boolean.
immutableAlways returnedboolean
Type: boolean.
immutable_reasonMay be omittedstring
Type: string.
import_entity_type_cdMay be omittedstring
Type: string.
import_entity_type_reasonMay be omittedstring
Type: string.
import_entity_type_sourceMay be omittedstring
Type: string.
import_run_idMay be omittedstring
Type: string.
import_sourceMay be omittedstring
Type: string.
imported_atMay be omittedstring
Type: string.
iris_repair_submissionAlways returnedobject | null
Recorded authorization to repair rejected filing records. Null when no repair has been submitted; this is not IRS acceptance. Unknown fields are rejected.
Nested fields (6)
case_idsAlways returnedarray<string>
Type: array<string>.
generationAlways returnedinteger
Type: integer.
request_sha256Always returnedstring | null
Type: string | null.
source_run_idAlways returnedstring
Type: string.
source_versionAlways returnedinteger
Type: integer.
submitted_atAlways returnedstring
Type: string.
iris_revisionMay be omittedstring
Type: string.
is_archivedAlways returnedboolean
Type: boolean.
is_btin_validatedAlways returnedboolean
Type: boolean.
is_correctedAlways returnedboolean
Type: boolean.
is_releasedAlways returnedboolean
Type: boolean.
is_tin_match_pendingAlways returnedboolean
Type: boolean.
is_tin_matchedAlways returnedboolean
Type: boolean.
is_validatedAlways returnedboolean
Type: boolean.
last_nameMay be omittedstring
Common projection maintained by the backend from canonical APP form data on writes. Read-only as a business value: supplying this field to recipient upsert does not change it. Use data_app.forms for authoritative IRS field values. Existing historical records are not rewritten by reads; Tax ID redaction still applies.
last_tin_match_resultMay be omittedstring
Type: string.
middle_nameMay be omittedstring
Common projection maintained by the backend from canonical APP form data on writes. Read-only as a business value: supplying this field to recipient upsert does not change it. Use data_app.forms for authoritative IRS field values. Existing historical records are not rewritten by reads; Tax ID redaction still applies.
phoneMay be omittedstring
Type: string.
postal_codeMay be omittedstring
Common projection maintained by the backend from canonical APP form data on writes. Read-only as a business value: supplying this field to recipient upsert does not change it. Use data_app.forms for authoritative IRS field values. Existing historical records are not rewritten by reads; Tax ID redaction still applies.
recipient_filingMay be omittedobject
Historical filing provenance. This metadata alone does not authorize a correction. Unknown fields are rejected.
Nested fields (6)
accepted_amendment_countMay be omittedinteger
Minimum: 0. Maximum: 65535.
external_predecessor_sha256May be omittedstring
Type: string.
scopeAlways returnedstring
Type: string.
source_filing_stateAlways returnedstring
Allowed values: "unfiled", "fire_released".
source_group_sha256Always returnedstring
Type: string.
source_is_correctedAlways returnedboolean
Type: boolean.
recipient_idAlways returnedstring (uuid)
Type: string (uuid).
source_correction_systemMay be omittedstring
Type: string.
source_digestMay be omittedstring
Type: string.
source_external_idMay be omittedstring
Type: string.
source_external_refMay be omittedstring
Type: string.
source_filing_systemMay be omittedstring
Type: string.
source_platformMay be omittedstring
Type: string.
stateMay be omittedstring
Common projection maintained by the backend from canonical APP form data on writes. Read-only as a business value: supplying this field to recipient upsert does not change it. Use data_app.forms for authoritative IRS field values. Existing historical records are not rewritten by reads; Tax ID redaction still applies.
statusAlways returnedstring
Type: string.
target_filing_systemMay be omittedstring
Type: string.
tinMay be omittedstring
Common projection maintained by the backend from canonical APP form data on writes. Read-only as a business value: supplying this field to recipient upsert does not change it. Use data_app.forms for authoritative IRS field values. Existing historical records are not rewritten by reads; Tax ID redaction still applies.
tin_kindMay be omittedstring
Type: string.
tin_last4May be omittedstring
Type: string.
transition_correction_policyMay be omittedstring
Type: string.
updated_atAlways returnedstring
Type: string.
validation_issue_countAlways returnedinteger
Type: integer.
validation_issuesMay be omittedarray<object>
Type: array<object>.
Nested fields (4)
codeAlways returnedstring
Type: string.
fieldMay be omittedstring
Type: string.
messageAlways returnedstring
Type: string.
originMay be omittedstring
Type: string.
versionAlways returnedinteger
Type: integer.
next_cursorMay be omittedstring | null
Maximum characters: 4096.
total_countMay be omittedinteger | null
Minimum: 0.
{
"data": {
"items": [],
"next_cursor": null,
"total_count": null
},
"meta": {
"api_version": "v1",
"request_id": "example-request-id"
}
}No matching records. Synthetic empty-page example. Follow a non-null next_cursor even when items is empty. A null total_count means no count was supplied.
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.