Filers
Create or update a filer
Save a filer and validate its business details.
/api/v1/filers/upsert- Authentication
- OAuth 2.0 access token
- Required scopes
filers.write- Idempotency key
- Required
- Rate-limit cost
- 5 units
How to use this endpoint
For an update, send the current version. A connection limited to selected filers cannot create a new filer. Submitted Tax IDs are not echoed.
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.
Saving an imported filer with unchanged business fields still runs strict validation and can clear retained import review issues. Supply its current expected_version. A provisional Business classification does not waive required-field, Tax ID, lock, or permission checks; failed validation leaves saved review issues intact.
An ordinary filer save requires a valid issuer telephone, resolved from telephone_number_and_extension or the compatibility phone field. The exact annual filer contract supplies its normalization and validation rules. filer_contact_phone is a separate contact field and is not a substitute. Existing permission, version and filing locks still apply.
Any released-recipient history blocks updates to filer filing details, including migrated filers with protected historical snapshots. has_released_recipients is sticky; can_edit_released_details is retained in responses for compatibility and always false. An update prepared before the first release also fails if release wins the commit race. Create a separate filer for different payer details.
Retrying a request? Keep the same idempotency key and body after an uncertain result. A different key can repeat the action.
curl --request POST 'https://api.efilemagic.com/api/v1/filers/upsert' \
--header 'Authorization: Bearer <access-token>' \
--header 'Idempotency-Key: <unique-operation-key>' \
--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
56 fieldsfiler_programRequiredstring
Allowed values: "app_1099_class", "app_1042s".
nameRequiredstring
Minimum characters: 1. Maximum characters: 256.
address1Optionalstring | null
Maximum characters: 2000.
address2Optionalstring | null
Maximum characters: 2000.
address_line1Optionalstring | null
Maximum characters: 2000.
address_line2Optionalstring | null
Maximum characters: 2000.
chapter3_status_codeOptionalstring | null
Maximum characters: 2000.
chapter4_status_codeOptionalstring | null
Maximum characters: 2000.
cityOptionalstring | null
Maximum characters: 2000.
codeOptionalstring | null
Maximum characters: 2000.
contact_nameOptionalstring | null
Maximum characters: 2000.
countryOptionalstring | null
Maximum characters: 2000.
Headers (3)
AuthorizationRequired- OAuth RS256 access token issued for the EFM API resource. Interactive EFM session tokens are rejected.
Idempotency-KeyRequired- Opaque caller-generated key bound to resolved tenant, connection, and actor scope.
DPoPConditional / optional- Required when the application, connection, or credential is proof-of-possession bound.
curl --request POST 'https://api.efilemagic.com/api/v1/filers/upsert' \
--header 'Authorization: Bearer <access-token>' \
--header 'Idempotency-Key: <unique-operation-key>' \
--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.
Retrying a request? Keep the same idempotency key and body after an uncertain result. A different key can repeat the action.
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.
- 409
conflict - Read the current state and resolve the conflict. Do not change the body under an existing idempotency key.
- 412
precondition_failed - Read the current version or preview again; a required precondition has changed.
- 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 and retry an uncertain result with the same body and idempotency key.
- 503
service_unavailable - Retry with bounded backoff, preserving the body and idempotency key.