E-File Magic

Filers

Create or update a filer

Save a filer and validate its business details.

POST
/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
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.json

Replace 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.