E-File Magic

Imports

Create an import

Start a filer-bound spreadsheet import and obtain create-only upload instructions.

POST
/api/v1/imports/submissions/create
Authentication
OAuth 2.0 access token
Required scopes
imports.write
Idempotency key
Required
Rate-limit cost
5 units

Request fields

12 fields
content_typeRequiredstring

Media type of the source file. Minimum characters: 1. Maximum characters: 128.

file_nameRequiredstring

Name of the source file being uploaded. Minimum characters: 1. Maximum characters: 180.

providerRequiredstring

Allowed values: "spreadsheet", "custom_spreadsheet", "generic_spreadsheet".

size_bytesRequiredinteger

Size of the source file in bytes. Minimum: 1. Maximum: 26214400.

default_form_idOptionalstring | null

Form used for imported rows that do not select one explicitly. Maximum characters: 64.

default_schema_revOptionalinteger | null

Schema revision used for rows that do not select one explicitly. Minimum: 1.

default_tax_yearOptionalinteger | null

Tax year used for rows that do not select one explicitly. Allowed values: 2022, 2023, 2024, 2025, 2026.

filer_idOptionalstring (uuid) | null

ID of the filer that owns this operation's records.

mappingOptionalobject | null

Source-column mappings for the import. Expand the nested fields for the mapping structure.

notify_emailOptionalstring (email) | null

Maximum characters: 254.

rows_per_chunkOptionalinteger | null

Minimum: 100. Maximum: 2000.

sha256Optionalstring | null

SHA-256 digest of the source file. Pattern: ^[a-f0-9]{64}$

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, actor, exact route, and request. Capability retries revalidate the durable target and mint a fresh URL.
DPoPConditional / optional
Required when the application, connection, or credential is proof-of-possession bound.

Complete request schema: ApiV1ImportCreateRequest

cURL request
curl --request POST 'https://api.efilemagic.com/api/v1/imports/submissions/create' \
  --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.

Retrying a request? Keep the same idempotency key and body after an uncertain result. A different key can repeat the action.