Imports
Map import columns
Match the uploaded file's columns to E-File Magic fields.
/api/v1/imports/submissions/configure_mapping- Authentication
- OAuth 2.0 access token
- Required scopes
imports.write- Idempotency key
- Required
- Rate-limit cost
- 5 units
How to use this endpoint
Inspect the file first, then save the mapping before starting the import. A replacement target filer must also be authorized.
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/configure_mapping' \
--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
7 fieldsmappingRequiredobject
Source-column mappings for the import. Expand the nested fields for the mapping structure.
submission_idRequiredstring (uuid)
Import submission ID returned when the import was created.
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.
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/configure_mapping' \
--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.