Imports
Create an import
Start a filer-bound spreadsheet import and obtain create-only upload instructions.
/api/v1/imports/submissions/create- Authentication
- OAuth 2.0 access token
- Required scopes
imports.write- Idempotency key
- Required
- Rate-limit cost
- 5 units
How to use this endpoint
Provide an authorized filer_id. Upload the file using the returned URL and headers, then inspect and configure its mapping before starting. Retrying the same key and body can return fresh upload instructions for the same pending submission.
Native IRS 1220 imports create multiple filers and run through Imports → Spreadsheets & 1220 in the signed-in application. This public API requires a destination filer and does not launch that workflow.
The signed-in application accepts native file suffixes .irs, .txt, .1220, .dat, and .fire, and probes at most 1,504 bytes for an unknown/no suffix before upload. Filename recognition is only a hint: existing byte-size, checksum, object binding, malware, full structural/control-total, and annual validation checks still apply. This does not expand the public API destination-filer contract.
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/imports/submissions/create' \
--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
12 fieldscontent_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.
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.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
4 fieldssubmissionAlways returnedobject
Unknown fields are rejected.
Nested fields (37)
chunk_checksumsMay be omittedarray<object>
Type: array<object>.
completed_atMay be omittedstring (date-time) | null
Type: string (date-time) | null.
content_typeAlways returnedstring
Maximum characters: 128.
created_atAlways returnedstring (date-time)
Type: string (date-time).
created_byAlways returnedobject
Type: object.
created_by_user_idMay be omittedstring (uuid) | null
Type: string (uuid) | null.
default_form_idMay be omittedstring | null
Type: string | null.
default_schema_revMay be omittedinteger | null
Type: integer | null.
default_tax_yearMay be omittedinteger | null
Type: integer | null.
detected_import_kindAlways returnedstring
Determined from uploaded file contents. Native Publication 1220 uses pub1220. Allowed values: "unknown", "standard_template", "inline_filer_template", "pub1220", "advanced_mapping".
file_nameAlways returnedstring
Maximum characters: 180.
filer_idMay be omittedstring (uuid) | null
Type: string (uuid) | null.
final_checksum_sha256May be omittedstring | null
Type: string | null.
imported_countAlways returnedinteger
Minimum: 0.
last_errorMay be omittedstring | null
Maximum characters: 2000.
mappingMay be omittedobject | null
Type: object | null.
next_row_numberAlways returnedinteger
Minimum: 1.
notification_sent_atMay be omittedstring (date-time) | null
Type: string (date-time) | null.
notify_emailMay be omittedstring (email) | null
Type: string (email) | null.
providerAlways returnedstring
Allowed values: "spreadsheet", "custom_spreadsheet", "generic_spreadsheet", "quickbooks_online", "xero", "bill", "zoho_books", "freshbooks", "business_central".
pub1220_corrections_skippedMay be omittedinteger
Minimum: 0.
pub1220_counts_completeMay be omittedboolean
Type: boolean.
pub1220_modeMay be omittedstring
Allowed values: "general_information", "with_details".
rolling_checksum_sha256May be omittedstring | null
Type: string | null.
row_count_processedAlways returnedinteger
Minimum: 0.
row_count_totalAlways returnedinteger
Minimum: 0.
rows_per_chunkAlways returnedinteger
Minimum: 1.
sha256May be omittedstring | null
Pattern: ^[a-f0-9]{64}$
size_bytesAlways returnedinteger
Minimum: 0.
skip_reason_countsMay be omittedobject | null
Additional values: integer.
skipped_countAlways returnedinteger
Minimum: 0.
statusAlways returnedstring
Type: string.
submission_idAlways returnedstring (uuid)
Type: string (uuid).
target_scopeAlways returnedstring
Type: string.
updated_atAlways returnedstring (date-time)
Type: string (date-time).
validation_issue_countAlways returnedinteger
Minimum: 0.
versionAlways returnedinteger
Minimum: 1.
upload_headersAlways returnedobject
Additional values: string.
upload_methodAlways returned"PUT"
Value: "PUT".
upload_urlAlways returnedstring (uri)
Type: string (uri).
{
"data": {
"submission": "object",
"upload_headers": "object",
"upload_method": "\"PUT\"",
"upload_url": "string (uri)"
},
"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.
- 402
service_capacity_required - Purchase the required service capacity in E-File Magic before creating records.