Imports
Inspect an import
Inspect the uploaded file and return its detected format and preview.
/api/v1/imports/submissions/inspect- Authentication
- OAuth 2.0 access token
- Required scopes
imports.readtax_ids.read- Idempotency key
- Not required
- Rate-limit cost
- 2 units
How to use this endpoint
Upload the source file before inspection. This public endpoint is read-only; configure spreadsheet mapping before starting. Inspection alone does not create recipients.
A detected pub1220 file uses a separate multi-filer workflow in the signed-in application. Its preview describes original returns, excludes G/C corrections, and reports whether counts are partial. Use Imports → Spreadsheets & 1220 to acquire that file; the filer-bound public API cannot launch it. Malformed framing or control totals can block inspection. Security format_error contains only a redacted record/byte diagnostic.
The signed-in Imports and Import Services screens share one combined standard template for 2022–2026. Its required Filer Information Filing Year drives standard-template acquisition, and missing or year-inapplicable columns and deleted optional form tabs are tolerated. This download change adds no endpoint or request field; the External Filing API retains its documented filer-bound mapping workflow and annual validation.
curl --request POST 'https://api.efilemagic.com/api/v1/imports/submissions/inspect' \
--header 'Authorization: Bearer <access-token>' \
--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
2 fieldssubmission_idRequiredstring (uuid)
Import submission ID returned when the import was created.
preview_rowsOptionalinteger | null
Number of source rows to include in the inspection preview. Minimum: 1. Maximum: 100.
Headers (2)
AuthorizationRequired- OAuth RS256 access token issued for the EFM API resource. Interactive EFM session tokens are rejected.
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/inspect' \
--header 'Authorization: Bearer <access-token>' \
--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.
On success, data contains the fields below. meta includes api_version and request_id. Keep request_id when reporting a problem.
Response fields
11 fieldscontent_typeAlways returnedstring
Type: string.
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
Type: string.
filer_idMay be omittedstring | null (uuid)
Type: string | null (uuid).
has_moreAlways returnedboolean
Type: boolean.
providerAlways returnedstring
Allowed values: "spreadsheet", "custom_spreadsheet", "generic_spreadsheet", "quickbooks_online", "xero", "bill", "zoho_books", "freshbooks", "business_central".
submission_idAlways returnedstring (uuid)
Type: string (uuid).
target_scopeAlways returnedstring
Allowed values: "single_filer", "multi_filer".
total_rowsAlways returnedinteger
Minimum: 0.
total_rows_exactAlways returnedboolean
Type: boolean.
versionAlways returnedinteger
Minimum: 1.
{
"data": {
"content_type": "string",
"detected_import_kind": "string",
"file_name": "string",
"filer_id": "string | null (uuid)",
"has_more": "boolean",
"provider": "string",
"submission_id": "string (uuid)",
"target_scope": "string",
"total_rows": "integer",
"total_rows_exact": "boolean",
"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.
- 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; retry with bounded backoff.
- 503
service_unavailable - Retry with bounded backoff.