Orders
Submit an order
Purchase the selected services and submit an order for processing.
/api/v1/orders/submit- Authentication
- OAuth 2.0 access token
- Required scopes
orders.submit- Idempotency key
- Required
- Rate-limit cost
- 100 units
How to use this endpoint
Review a fresh preview, terms and funding before calling this endpoint. Explicit terms_accepted=true, the current terms_version and order_signature_crypto remain required when customer deposits cover the full total. After an uncertain 500 or 503, retry the exact body with the same Idempotency-Key. Do not start a replacement order while the outcome is uncertain. Review a 409 or 412 and obtain a fresh preview before submitting again.
Invoice PDFs show the recorded card/ACH payment ending or approved A/R terms. Totals end Total, Paid, Balance Due; authorization alone is not payment. New invoice copies reflect confirmed payments. Historical originals remain unchanged; unavailable legacy payment-ending evidence does not prevent an invoice download.
The efile service is displayed as Combined Federal/State e-File (CF/SF). E-File Magic participates in the IRS CF/SF program for eligible filings. The API service_code remains efile; this display name does not change pricing or filing eligibility.
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/orders/submit' \
--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
9 fieldsexpected_policy_versionRequiredinteger
Policy version returned by the order preview. Minimum: 1.
expected_total_minorRequiredinteger
Expected order total from preview, in the currency's minor units. Minimum: 0.
filer_idRequiredstring (uuid)
ID of the filer that owns this operation's records.
funding_aliasRequiredstring
Approved funding alias configured for the connection. Minimum characters: 1. Maximum characters: 64.
order_signature_cryptoRequiredstring
Minimum characters: 1. Maximum characters: 16384.
service_codesRequiredarray<string>
Services to include in the order. Review availability and pricing with preview first. Must include efile and e_delivery. State E-File is not currently available: new state_efile requests return HTTP 400 invalid_request with message 'State E-File is not currently available.'. State Reporting File (irs_spec_file) remains available. Historical response identities are unchanged. Minimum items: 2. Maximum items: 4. Items must be unique.
terms_acceptedRequiredtrue
Records the caller's acceptance of the specified terms. Value: true.
terms_versionRequiredstring
Version of the terms accepted for this order. Minimum characters: 1. Maximum characters: 64.
tax_yearOptionalinteger | null
Tax year of the filer and forms being processed. Allowed values: 2022, 2023, 2024, 2025, 2026.
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/orders/submit' \
--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 fieldsfunding_kindAlways returnedstring
Allowed values: "deposit", "terms", "vaulted_instrument".
orderAlways returnedobject
Unknown fields are rejected.
Nested fields (4)
invoiceAlways returnedobject
Type: object.
orderAlways returnedobject
Unknown fields are rejected.
Nested fields (33)
balance_due_minorAlways returnedinteger
Minimum: 0.
created_atAlways returnedstring (date-time)
Type: string (date-time).
currencyAlways returned"USD"
Value: "USD".
customer_deposit_applied_minorAlways returnedinteger
Minimum: 0.
customer_deposit_reserved_minorAlways returnedinteger
Minimum: 0.
filer_idAlways returnedstring (uuid)
Type: string (uuid).
from_importAlways returnedboolean
Type: boolean.
fulfillment_statusAlways returnedstring
Type: string.
holdAlways returnedobject
Type: object.
import_run_idMay be omittedstring | null
Type: string | null.
import_sourceMay be omittedstring | null
Type: string | null.
imported_atMay be omittedstring (date-time) | null
Type: string (date-time) | null.
last_errorMay be omittedstring | null
Type: string | null.
order_idAlways returnedstring (uuid)
Type: string (uuid).
payment_due_minorAlways returnedinteger
Minimum: 0.
payment_statusAlways returnedstring
Type: string.
public_order_refMay be omittedstring | null
Type: string | null.
snapshot_chunk_completedAlways returnedinteger
Minimum: 0.
snapshot_chunk_totalAlways returnedinteger
Minimum: 0.
snapshot_copied_recipientsAlways returnedinteger
Minimum: 0.
snapshot_statusAlways returnedstring
Type: string.
snapshot_total_recipientsAlways returnedinteger
Minimum: 0.
source_digestMay be omittedstring | null
Type: string | null.
source_external_idMay be omittedstring | null
Type: string | null.
source_external_refMay be omittedstring | null
Type: string | null.
source_filing_systemMay be omittedstring | null
Type: string | null.
source_platformMay be omittedstring | null
Type: string | null.
statusAlways returnedstring
Type: string.
tax_yearMay be omittedinteger | null
Type: integer | null.
tenant_idAlways returnedstring (uuid)
Type: string (uuid).
total_minorAlways returnedinteger
Minimum: 0.
updated_atAlways returnedstring (date-time)
Type: string (date-time).
versionAlways returnedinteger
Minimum: 1.
order_confirmationAlways returnedobject
Type: object.
servicesAlways returnedarray<object>
Type: array<object>.
payment_statusAlways returnedstring
Type: string.
policy_versionAlways returnedinteger
Minimum: 1.
{
"data": {
"funding_kind": "string",
"order": "object",
"payment_status": "string",
"policy_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.