Recipients
Get a recipient
Read one recipient and its form information. When present, filing_outcome describes the latest projected IRS acceptance and required review. Missing outcome data does not mean accepted. When iris_repair_submission is present, the current recipient is locked pending the authorized repair result; this does not change the historical IRS acceptance in filing_outcome. Accepted corrections and explicit repair of rejected filings use the recipient workflow in the authenticated application; ordinary upsert does not submit an IRS correction or retry.
/api/v1/recipients/get- 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 the recipient's filer_id and recipient_id. Full Tax ID detail requires the additional Tax ID read permission.
Request example
curl --request POST 'https://api.efilemagic.com/api/v1/recipients/get' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{"filer_id":"11111111-1111-4111-8111-111111111111","recipient_id":"11111111-1111-4111-8111-111111111111"}'Replace placeholders with your own values. Use the API resource origin provided for your environment.
Request fields
2 fieldsfiler_idRequiredstring (uuid)
ID of the filer that owns this operation's records.
recipient_idRequiredstring (uuid)
ID of the recipient within the selected filer.
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.
Request example
curl --request POST 'https://api.efilemagic.com/api/v1/recipients/get' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{"filer_id":"11111111-1111-4111-8111-111111111111","recipient_id":"11111111-1111-4111-8111-111111111111"}'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
58 fieldsaddress_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.
{
"data": {
"address_line1": "string",
"address_line2": "string",
"app_revision": "string",
"arch_bucket": "string",
"city": "string",
"company_name": "string",
"correction_type": "string",
"country": "string",
"created_at": "string",
"data_app": "object",
"display_name": "string",
"email": "string",
"filer_id": "string (uuid)",
"filing_outcome": "object",
"fire_revision": "string",
"first_name": "string",
"from_import": "boolean",
"immutable": "boolean",
"immutable_reason": "string",
"import_entity_type_cd": "string",
"import_entity_type_reason": "string",
"import_entity_type_source": "string",
"import_run_id": "string",
"import_source": "string",
"imported_at": "string",
"iris_repair_submission": "object | null",
"iris_revision": "string",
"is_archived": "boolean",
"is_btin_validated": "boolean",
"is_corrected": "boolean",
"is_released": "boolean",
"is_tin_match_pending": "boolean",
"is_tin_matched": "boolean",
"is_validated": "boolean",
"last_name": "string",
"last_tin_match_result": "string",
"middle_name": "string",
"phone": "string",
"postal_code": "string",
"recipient_filing": "object",
"recipient_id": "string (uuid)",
"source_correction_system": "string",
"source_digest": "string",
"source_external_id": "string",
"source_external_ref": "string",
"source_filing_system": "string",
"source_platform": "string",
"state": "string",
"status": "string",
"target_filing_system": "string",
"tin": "string",
"tin_kind": "string",
"tin_last4": "string",
"transition_correction_policy": "string",
"updated_at": "string",
"validation_issue_count": "integer",
"validation_issues": "array<object>",
"version": "integer"
},
"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.