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

On success, data contains the fields below. meta includes api_version and request_id. Keep request_id when reporting a problem.

Response fields

4 fields
submissionAlways 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).

Complete response schema: ApiV1ImportCreateResponse

Structure · HTTP 200
{
  "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.