Forms
Read the form catalog
Find supported forms and their exact annual field contracts.
/api/v1/forms/catalog- Authentication
- OAuth 2.0 access token
- Required scopes
forms.read- Idempotency key
- Not required
- Rate-limit cost
- 1 unit
How to use this endpoint
Start with view=inventory. Then choose filer or recipient view and supply filer_class, tax_year and schema_rev; recipient view also requires form_id. Only selectors for the chosen view are accepted. Do not infer support or fields from another tax year.
curl --request GET 'https://api.efilemagic.com/api/v1/forms/catalog' \
--header 'Authorization: Bearer <access-token>' \
--get \
--data-urlencode 'view=inventory'Replace placeholders with your own values. Use the API resource origin provided for your environment.
Request fields
5 fieldsquery.viewRequiredstring
Choose inventory to find supported contracts, then filer or recipient to read an exact contract. inventory takes only view. filer also requires filer_class, tax_year and schema_rev. recipient additionally requires form_id. No extra selectors are accepted. Allowed values: "inventory", "filer", "recipient".
query.filer_classOptionalstring
Filer class selected from the form catalog. Allowed values: "app_1099_class", "app_1042s", "ssa_w2".
query.tax_yearOptionalinteger
Tax year of the filer and forms being processed. Allowed values: 2022, 2023, 2024, 2025, 2026.
query.schema_revOptionalinteger
Exact application schema revision selected from the form catalog. Exact admitted application revision; use the returned inventory. Minimum: 1.
query.form_idOptionalstring
Form identifier from the catalog for this tax year and schema revision. Exact admitted form identifier, required only for recipient view.
Headers (1)
AuthorizationRequired- OAuth Bearer token with the listed scopes and current resource authorization.
curl --request GET 'https://api.efilemagic.com/api/v1/forms/catalog' \
--header 'Authorization: Bearer <access-token>' \
--get \
--data-urlencode 'view=inventory'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
6 fieldscatalog_viewAlways returnedstring
Allowed values: "inventory", "filer", "recipient".
filer_classesAlways returnedarray<object>
Type: array<object>.
Nested fields (4)
class_codeAlways returnedstring
Type: string.
class_labelAlways returnedstring
Type: string.
filer_classAlways returnedstring
Type: string.
schema_familyAlways returnedstring
Type: string.
filer_fieldsAlways returnedarray<object>
Type: array<object>.
Nested fields (9)
class_codeAlways returnedstring
Type: string.
class_labelAlways returnedstring
Type: string.
field_idsAlways returnedarray<string>
Type: array<string>.
fieldsAlways returnedarray<object>
Type: array<object>.
Nested fields (28)
amount_semanticsMay be omittedstring
Type: string.
annual_change_reasonMay be omittedstring
Type: string.
applicability_rule_idMay be omittedstring
Type: string.
box_refMay be omittedstring
Type: string.
cardinalityAlways returnedstring
Type: string.
descriptionMay be omittedstring
Type: string.
display_labelMay be omittedstring
Type: string.
display_orderAlways returnedinteger
Type: integer.
exposureAlways returnedobject
Unknown fields are rejected.
Nested fields (7)
api_readableAlways returnedboolean
Type: boolean.
api_writableAlways returnedboolean
Type: boolean.
import_acceptedAlways returnedboolean
Type: boolean.
operator_editableAlways returnedboolean
Type: boolean.
operator_visibleAlways returnedboolean
Type: boolean.
print_includedAlways returnedboolean
Type: boolean.
server_derivedAlways returnedboolean
Type: boolean.
field_idAlways returnedstring
Type: string.
group_idAlways returnedstring
Type: string.
help_textAlways returnedstring
Type: string.
import_aliasesAlways returnedarray<string>
Type: array<string>.
input_kindAlways returnedstring
Type: string.
labelAlways returnedstring
Type: string.
max_lenAlways returnedinteger
Type: integer.
normalizersAlways returnedarray<string>
Type: array<string>.
output_scopeAlways returnedstring
Type: string.
repeat_group_idMay be omittedstring
Type: string.
repeat_group_max_itemsMay be omittedinteger
Type: integer.
repeatedAlways returnedboolean
Type: boolean.
requiredAlways returnedboolean
Type: boolean.
sectionAlways returnedstring
Type: string.
source_provenanceAlways returnedstring
Type: string.
special_handlingAlways returnedarray<string>
Type: array<string>.
storage_typeAlways returnedstring
Type: string.
unique_itemsAlways returnedboolean
Type: boolean.
validatorsAlways returnedarray<string>
Type: array<string>.
filer_classAlways returnedstring
Type: string.
schema_familyAlways returnedstring
Type: string.
schema_releaseAlways returnedstring
Type: string.
schema_revAlways returnedinteger
Type: integer.
tax_yearAlways returnedinteger
Type: integer.
recipient_fieldsAlways returnedarray<object>
Type: array<object>.
Nested fields (30)
app_supportAlways returnedstring
Type: string.
class_codeAlways returnedstring
Type: string.
class_labelAlways returnedstring
Type: string.
common_field_idsAlways returnedarray<string>
Type: array<string>.
correction_supportedAlways returnedboolean
Type: boolean.
editing_supportedAlways returnedboolean
Type: boolean.
field_idsAlways returnedarray<string>
Type: array<string>.
fieldsAlways returnedarray<object>
Type: array<object>.
Nested fields (28)
amount_semanticsMay be omittedstring
Type: string.
annual_change_reasonMay be omittedstring
Type: string.
applicability_rule_idMay be omittedstring
Type: string.
box_refMay be omittedstring
Type: string.
cardinalityAlways returnedstring
Type: string.
descriptionMay be omittedstring
Type: string.
display_labelMay be omittedstring
Type: string.
display_orderAlways returnedinteger
Type: integer.
exposureAlways returnedobject
Unknown fields are rejected.
Nested fields (7)
api_readableAlways returnedboolean
Type: boolean.
api_writableAlways returnedboolean
Type: boolean.
import_acceptedAlways returnedboolean
Type: boolean.
operator_editableAlways returnedboolean
Type: boolean.
operator_visibleAlways returnedboolean
Type: boolean.
print_includedAlways returnedboolean
Type: boolean.
server_derivedAlways returnedboolean
Type: boolean.
field_idAlways returnedstring
Type: string.
group_idAlways returnedstring
Type: string.
help_textAlways returnedstring
Type: string.
import_aliasesAlways returnedarray<string>
Type: array<string>.
input_kindAlways returnedstring
Type: string.
labelAlways returnedstring
Type: string.
max_lenAlways returnedinteger
Type: integer.
normalizersAlways returnedarray<string>
Type: array<string>.
output_scopeAlways returnedstring
Type: string.
repeat_group_idMay be omittedstring
Type: string.
repeat_group_max_itemsMay be omittedinteger
Type: integer.
repeatedAlways returnedboolean
Type: boolean.
requiredAlways returnedboolean
Type: boolean.
sectionAlways returnedstring
Type: string.
source_provenanceAlways returnedstring
Type: string.
special_handlingAlways returnedarray<string>
Type: array<string>.
storage_typeAlways returnedstring
Type: string.
unique_itemsAlways returnedboolean
Type: boolean.
validatorsAlways returnedarray<string>
Type: array<string>.
filer_classAlways returnedstring
Type: string.
fire_fileableAlways returnedboolean
Type: boolean.
fire_target_releaseMay be omittedstring
Type: string.
fire_target_schema_revMay be omittedinteger
Type: integer.
fire_translation_contract_idMay be omittedstring
Type: string.
fire_unavailable_reasonMay be omittedstring
Type: string.
form_field_idsAlways returnedarray<string>
Type: array<string>.
form_idAlways returnedstring
Type: string.
form_labelAlways returnedstring
Type: string.
import_supportedAlways returnedboolean
Type: boolean.
iris_fileableAlways returnedboolean
Type: boolean.
iris_target_releaseMay be omittedstring
Type: string.
iris_target_schema_revMay be omittedinteger
Type: integer.
iris_translation_contract_idMay be omittedstring
Type: string.
iris_unavailable_reasonMay be omittedstring
Type: string.
presentation_groupsAlways returnedarray<object>
Type: array<object>.
Nested fields (5)
columnsAlways returnedinteger
Type: integer.
descriptionAlways returnedstring
Type: string.
field_idsAlways returnedarray<string>
Type: array<string>.
group_idAlways returnedstring
Type: string.
titleAlways returnedstring
Type: string.
print_supportedAlways returnedboolean
Type: boolean.
schema_familyAlways returnedstring
Type: string.
schema_releaseAlways returnedstring
Type: string.
schema_revAlways returnedinteger
Type: integer.
support_reasonAlways returnedstring
Type: string.
tax_yearAlways returnedinteger
Type: integer.
schema_familyAlways returnedstring
Type: string.
validator_catalogAlways returnedarray<object>
Type: array<object>.
Nested fields (3)
descriptionAlways returnedstring
Type: string.
input_kindAlways returnedstring
Type: string.
validator_idAlways returnedstring
Type: string.
{
"data": {
"catalog_view": "string",
"filer_classes": "array<object>",
"filer_fields": "array<object>",
"recipient_fields": "array<object>",
"schema_family": "string",
"validator_catalog": "array<object>"
},
"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.