Filers
Get a filer
Read one filer, including its current validation results.
/api/v1/filers/get- Authentication
- OAuth 2.0 access token
- Required scopes
filers.read- Idempotency key
- Not required
- Rate-limit cost
- 1 unit
How to use this endpoint
Use the filer ID from a list or create response. Full Tax ID access requires the additional Tax ID read permission.
import_validation_status, import_validation_issue_count and import_validation_issues are read-only. An invalid filer remains readable; save corrected filer details to clear its current issues before dependent work.
Request example
curl --request POST 'https://api.efilemagic.com/api/v1/filers/get' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{"filer_id":"11111111-1111-4111-8111-111111111111"}'Replace placeholders with your own values. Use the API resource origin provided for your environment.
Request fields
1 fieldsfiler_idRequiredstring (uuid)
ID of the filer that owns this operation's records.
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/filers/get' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{"filer_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
97 fieldsaddress1Always returnedstring | null
Type: string | null.
address2Always returnedstring | null
Type: string | null.
address_line1Always returnedstring | null
Type: string | null.
address_line2Always returnedstring | null
Type: string | null.
app_revisionMay be omittedstring
Type: string.
arch_bucketAlways returnedstring
Archive compatibility indicator. Use is_archived for application logic.
can_edit_released_detailsAlways returnedboolean
Always false. Released-recipient history locks filer details, including migrated filers. Retained for response compatibility; never a request control.
chapter3_status_codeAlways returnedstring | null
Type: string | null.
chapter4_status_codeAlways returnedstring | null
Type: string | null.
cityAlways returnedstring | null
Type: string | null.
codeAlways returnedstring | null
Type: string | null.
contact_nameAlways returnedstring | null
Type: string | null.
{
"data": {
"address1": "string | null",
"address2": "string | null",
"address_line1": "string | null",
"address_line2": "string | null",
"app_revision": "string",
"arch_bucket": "string",
"can_edit_released_details": "boolean",
"chapter3_status_code": "string | null",
"chapter4_status_code": "string | null",
"city": "string | null",
"code": "string | null",
"contact_name": "string | null",
"country": "string | null",
"country_code": "string | null",
"created_at": "string",
"data_app": "object",
"department_title": "string | null",
"description": "string | null",
"ein_type_ind": "string | null",
"email": "string | null",
"entity_type_cd": "string | null",
"filer_contact_email": "string | null",
"filer_contact_first_name": "string | null",
"filer_contact_last_name": "string | null",
"filer_contact_phone": "string | null",
"filer_id": "string (uuid)",
"filer_program": "string",
"filing_year": "integer | null",
"filing_year_text": "string | null",
"fire_revision": "string",
"foreign_city_state_zip": "string | null",
"foreign_entity": "boolean | null",
"foreign_postal_cd": "string | null",
"foreign_tax_id": "string | null",
"from_import": "boolean",
"giin": "string | null",
"has_recipients": "boolean",
"has_released_recipients": "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",
"import_validation_issue_count": "integer",
"import_validation_issues": "array<object>",
"import_validation_status": "string",
"imported_at": "string",
"iris_revision": "string",
"is_archived": "boolean",
"is_tin_matched": "boolean",
"issuer_country_code": "string | null",
"last_filing_year_ind": "boolean | null",
"last_tin_match_result": "string",
"last_year_filing": "boolean | null",
"name": "string",
"name1": "string | null",
"name2": "string | null",
"notes": "string | null",
"person_first_nm": "string | null",
"person_last_nm": "string | null",
"person_middle_nm": "string | null",
"person_suffix_nm": "string | null",
"phone": "string | null",
"postal_code": "string | null",
"pro_rata_basis_rep_ind": "boolean | null",
"province_code": "string | null",
"recipient_contact_email": "string | null",
"recipient_contact_name": "string | null",
"recipient_filing": "object",
"recipient_ops_lock_expires_at": "string | null",
"recipient_ops_lock_reason": "string | null",
"recipient_ops_lock_run_id": "string | null",
"recipient_ops_lock_started_at": "string | null",
"recipient_ops_locked": "boolean",
"second_name_line_t_agent": "boolean | null",
"source_correction_system": "string",
"source_digest": "string",
"source_external_id": "string",
"source_external_ref": "string",
"source_filing_system": "string",
"source_platform": "string",
"state": "string | null",
"status": "string",
"target_filing_system": "string",
"tax_id": "string | null",
"telephone_number_and_extension": "string | null",
"tin": "string | null",
"tin_kind": "string | null",
"tin_last4": "string | null",
"transition_correction_policy": "string",
"updated_at": "string",
"version": "integer",
"withholding_ind": "string | null",
"zip_code": "string | null",
"zip_or_post_code": "string | 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.