Search
Search account records
Find authorized filers, recipients, orders and other supported records using the same tenant search as the application.
/api/v1/search- Authentication
- OAuth 2.0 access token
- Required scopes
- See authentication requirements
- Idempotency key
- Not required
- Rate-limit cost
- 5 units
How to use this endpoint
Omit domains to search the domains permitted by your token. Explicit domains require their matching read scopes; staff domains and retired print exports are rejected. Optional filer_id narrows results to an authorized filer.
Results are a bounded discovery window. Search can lag a successful save. Filer-filtered results always report partial=true and filtered_window=true; no hidden-record totals or ranking metadata are exposed. Use returned IDs with normal read endpoints.
Use entity_id with the matching record API. For order_deliverables, use the returned order_id and service_code with the deliverable read/download tools; entity_id is a composite search reference.
For recipient names, q may contain complete indexed words followed by a final alphabetic name prefix or initial: chris mal can find Chris Maloney. Earlier terms remain exact. This does not add standalone prefixes, all-partial queries, substring matching or partial email lookup. Existing discovery-window limits and partial semantics apply; no additional matches outside the bounded window are promised.
The first-party Filer and Recipient directories highlight literal query text within existing visible names and locations. This display decoration adds no response field or field-level match attribution and does not change which records the API returns.
curl --request POST 'https://api.efilemagic.com/api/v1/search' \
--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
6 fieldsqRequiredstring
Search text used to filter this collection. Minimum characters: 1. Maximum characters: 256.
archive_scopeOptionalstring | null
Allowed values: "active", "archived", "all". Default: "active".
domainsOptionalarray<string> | null
Minimum items: 1. Maximum items: 10. Items must be unique.
filer_idOptionalstring (uuid) | null
ID of the filer that owns this operation's records.
filing_yearOptionalinteger | null
Filing year to use or filter by. Allowed values: 2022, 2023, 2024, 2025, 2026.
limitOptionalinteger | null
Maximum number of results requested for this page. Minimum: 1. Maximum: 100. Default: 50.
Headers (1)
AuthorizationRequired- OAuth Bearer token with current resource authorization and the required scopes.
curl --request POST 'https://api.efilemagic.com/api/v1/search' \
--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
5 fieldsdomainsAlways returnedarray<string>
Maximum items: 10.
filtered_windowAlways returnedboolean
Type: boolean.
hitsAlways returnedarray<object>
Maximum items: 100.
Nested fields (9)
domainAlways returnedstring
Allowed values: "filers", "recipients", "orders", "file_submissions", "w9_issuers", "w9_requests", "w9_imports", "delivery_artifacts", "order_deliverables", "import_services".
entity_idAlways returnedstring
Type: string.
excerptAlways returnedstring | null
Type: string | null.
filer_idAlways returnedstring (uuid) | null
Type: string (uuid) | null.
is_archivedAlways returnedboolean
Type: boolean.
order_idAlways returnedstring (uuid) | null
Type: string (uuid) | null.
service_codeAlways returnedstring | null
Allowed values: "efile", "e_delivery", "state_efile", "print_mail", "tin_matching", "irs_spec_file", "excel_processing", "professional_services", "w9_collection".
titleAlways returnedstring | null
Type: string | null.
updated_atAlways returnedstring | null
Type: string | null.
limitAlways returnedinteger
Minimum: 1. Maximum: 100.
partialAlways returnedboolean
Type: boolean.
{
"data": {
"domains": "array<string>",
"filtered_window": "boolean",
"hits": "array<object>",
"limit": "integer",
"partial": "boolean"
},
"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.