Filers
Get multiple filers
Read a batch of filers in request order and identify IDs that were not found.
/api/v1/filers/get_many- Authentication
- OAuth 2.0 access token
- Required scopes
filers.read- Idempotency key
- Not required
- Rate-limit cost
- 1 unit
How to use this endpoint
Send 1–100 unique filer IDs. Tax IDs are masked in batch results. Every requested filer must be allowed by the connection.
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_many' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{"filer_ids":["11111111-1111-4111-8111-111111111111"]}'Replace placeholders with your own values. Use the API resource origin provided for your environment.
Request fields
1 fieldsfiler_idsRequiredarray<string (uuid)>
Filer IDs to read in request order. Minimum items: 1. Maximum items: 100. Items must be unique.
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_many' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{"filer_ids":["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
2 fieldsitemsAlways returnedarray<object>
Maximum items: 100.
Nested fields (97)
address1Always 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.
countryAlways returnedstring | null
Type: string | null.
country_codeAlways returnedstring | null
Type: string | null.
created_atAlways returnedstring
Type: string.
data_appMay be omittedobject
Unknown fields are rejected.
Nested fields (3)
dataMay be omittedvalue
Type: value.
schema_revAlways returnedinteger
Type: integer.
updated_atAlways returnedstring
Type: string.
department_titleAlways returnedstring | null
Type: string | null.
descriptionAlways returnedstring | null
Type: string | null.
ein_type_indAlways returnedstring | null
Type: string | null.
emailAlways returnedstring | null
Type: string | null.
entity_type_cdAlways returnedstring | null
Type: string | null.
filer_contact_emailAlways returnedstring | null
Type: string | null.
filer_contact_first_nameAlways returnedstring | null
Type: string | null.
filer_contact_last_nameAlways returnedstring | null
Type: string | null.
filer_contact_phoneAlways returnedstring | null
Type: string | null.
filer_idAlways returnedstring (uuid)
Type: string (uuid).
filer_programAlways returnedstring
Type: string.
filing_yearAlways returnedinteger | null
Type: integer | null.
filing_year_textAlways returnedstring | null
Type: string | null.
fire_revisionMay be omittedstring
Type: string.
foreign_city_state_zipAlways returnedstring | null
Type: string | null.
foreign_entityAlways returnedboolean | null
Type: boolean | null.
foreign_postal_cdAlways returnedstring | null
Type: string | null.
foreign_tax_idAlways returnedstring | null
Type: string | null.
from_importAlways returnedboolean
Type: boolean.
giinAlways returnedstring | null
Type: string | null.
has_recipientsMay be omittedboolean
Whether this filer has recipients, when included by the read operation.
has_released_recipientsAlways 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.
import_validation_issue_countAlways returnedinteger
Minimum: 0.
import_validation_issuesAlways returnedarray<object>
Type: array<object>.
Nested fields (4)
codeAlways returnedstring
Type: string.
fieldMay be omittedstring
Type: string.
messageAlways returnedstring
Type: string.
originAlways returnedstring
Allowed values: "import".
import_validation_statusAlways returnedstring
Allowed values: "valid", "invalid".
imported_atMay be omittedstring
Type: string.
iris_revisionMay be omittedstring
Type: string.
is_archivedAlways returnedboolean
Type: boolean.
is_tin_matchedAlways returnedboolean
Type: boolean.
issuer_country_codeAlways returnedstring | null
Type: string | null.
last_filing_year_indAlways returnedboolean | null
Type: boolean | null.
last_tin_match_resultMay be omittedstring
Type: string.
last_year_filingAlways returnedboolean | null
Type: boolean | null.
nameAlways returnedstring
Type: string.
name1Always returnedstring | null
Type: string | null.
name2Always returnedstring | null
Type: string | null.
notesAlways returnedstring | null
Type: string | null.
person_first_nmAlways returnedstring | null
Type: string | null.
person_last_nmAlways returnedstring | null
Type: string | null.
person_middle_nmAlways returnedstring | null
Type: string | null.
person_suffix_nmAlways returnedstring | null
Type: string | null.
phoneAlways returnedstring | null
Type: string | null.
postal_codeAlways returnedstring | null
Type: string | null.
pro_rata_basis_rep_indAlways returnedboolean | null
Type: boolean | null.
province_codeAlways returnedstring | null
Type: string | null.
recipient_contact_emailAlways returnedstring | null
Type: string | null.
recipient_contact_nameAlways returnedstring | null
Type: string | null.
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_ops_lock_expires_atAlways returnedstring | null
Type: string | null.
recipient_ops_lock_reasonAlways returnedstring | null
Type: string | null.
recipient_ops_lock_run_idAlways returnedstring | null
Type: string | null.
recipient_ops_lock_started_atAlways returnedstring | null
Type: string | null.
recipient_ops_lockedAlways returnedboolean
Type: boolean.
second_name_line_t_agentAlways returnedboolean | null
Type: boolean | null.
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.
stateAlways returnedstring | null
Type: string | null.
statusAlways returnedstring
Type: string.
target_filing_systemMay be omittedstring
Type: string.
tax_idAlways returnedstring | null
Type: string | null.
telephone_number_and_extensionAlways returnedstring | null
Type: string | null.
tinAlways returnedstring | null
Type: string | null.
tin_kindAlways returnedstring | null
Type: string | null.
tin_last4Always returnedstring | null
Type: string | null.
transition_correction_policyMay be omittedstring
Type: string.
updated_atAlways returnedstring
Type: string.
versionAlways returnedinteger
Type: integer.
withholding_indAlways returnedstring | null
Type: string | null.
zip_codeAlways returnedstring | null
Type: string | null.
zip_or_post_codeAlways returnedstring | null
Type: string | null.
missingAlways returnedarray<string (uuid)>
Maximum items: 100.
{
"data": {
"items": "array<object>",
"missing": "array<string (uuid)>"
},
"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.