Orders
List orders
Find orders and track their filing and delivery progress.
/api/v1/orders/list- Authentication
- OAuth 2.0 access token
- Required scopes
orders.read- Idempotency key
- Not required
- Rate-limit cost
- 1 unit
How to use this endpoint
Provide filer_id when your connection is limited to selected filers. Follow next_cursor with the same filters.
curl --request GET 'https://api.efilemagic.com/api/v1/orders/list' \
--header 'Authorization: Bearer <access-token>' \
--get \
--data-urlencode 'limit=25'Replace placeholders with your own values. Use the API resource origin provided for your environment.
Request fields
7 fieldsquery.qOptionalstring
Search text used to filter this collection. Maximum characters: 256.
query.filer_idOptionalstring (uuid)
ID of the filer that owns this operation's records.
query.snapshot_statusOptionalstring
Allowed values: "not_started", "queued", "processing", "completed", "failed".
query.sort_byOptionalstring
Field used to order results. Allowed values: "updated_at", "relevance".
query.sort_orderOptionalstring
Ascending or descending result order. Allowed values: "asc", "desc".
query.limitOptionalinteger
Maximum number of results requested for this page. Minimum: 1. Maximum: 100.
query.cursorOptionalstring
Opaque next_cursor from the previous page. Keep the other filters unchanged. Minimum characters: 1. Maximum characters: 2048.
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 GET 'https://api.efilemagic.com/api/v1/orders/list' \
--header 'Authorization: Bearer <access-token>' \
--get \
--data-urlencode 'limit=25'Replace placeholders with your own values. Use the API resource origin provided for your environment.
On success, data contains the fields below. meta includes api_version and request_id. Keep request_id when reporting a problem.
Response fields
3 fieldsitemsAlways returnedarray<object>
Maximum items: 100.
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.
next_cursorMay be omittedstring | null
Maximum characters: 4096.
total_countMay be omittedinteger | null
Minimum: 0.
{
"data": {
"items": [],
"next_cursor": null,
"total_count": null
},
"meta": {
"api_version": "v1",
"request_id": "example-request-id"
}
}No matching records. Synthetic empty-page example. Follow a non-null next_cursor even when items is empty. A null total_count means no count was supplied.
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.