Imports
Start an import
Process a configured spreadsheet for its authorized destination filer.
/api/v1/imports/submissions/start- Authentication
- OAuth 2.0 access token
- Required scopes
imports.write- Idempotency key
- Required
- Rate-limit cost
- 25 units
How to use this endpoint
Upload, inspect and configure the spreadsheet mapping before starting. Start accounting-system imports from Integrations in the application. Read submission status and row results to check the outcome.
Native IRS 1220 imports are started in the application. The wizard requires either Import Filers and Recipients or Import Filers and Recipients with Details, with neither preselected. Both choices exclude G/C corrections. General-information imports keep amounts and form details blank and recipients invalid for completion.
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/start' \
--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
3 fieldssubmission_idRequiredstring (uuid)
Import submission ID returned when the import was created.
expected_versionOptionalinteger | null
Version from the latest read of the record. A changed version requires review before updating. Minimum: 1.
target_filer_idOptionalstring (uuid) | null
Filer that will receive the imported records; your connection must be allowed to use it.
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/imports/submissions/start' \
--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
37 fieldschunk_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.
{
"data": {
"chunk_checksums": "array<object>",
"completed_at": "string (date-time) | null",
"content_type": "string",
"created_at": "string (date-time)",
"created_by": "object",
"created_by_user_id": "string (uuid) | null",
"default_form_id": "string | null",
"default_schema_rev": "integer | null",
"default_tax_year": "integer | null",
"detected_import_kind": "string",
"file_name": "string",
"filer_id": "string (uuid) | null",
"final_checksum_sha256": "string | null",
"imported_count": "integer",
"last_error": "string | null",
"mapping": "object | null",
"next_row_number": "integer",
"notification_sent_at": "string (date-time) | null",
"notify_email": "string (email) | null",
"provider": "string",
"pub1220_corrections_skipped": "integer",
"pub1220_counts_complete": "boolean",
"pub1220_mode": "string",
"rolling_checksum_sha256": "string | null",
"row_count_processed": "integer",
"row_count_total": "integer",
"rows_per_chunk": "integer",
"sha256": "string | null",
"size_bytes": "integer",
"skip_reason_counts": "object | null",
"skipped_count": "integer",
"status": "string",
"submission_id": "string (uuid)",
"target_scope": "string",
"updated_at": "string (date-time)",
"validation_issue_count": "integer",
"version": "integer"
},
"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.