Field

Fields describe properties of the document itself. Fields are often used to get metadata such as the perceived language or the type of document from a list of possible types.

Parameter

Type

Description

field_id

string

Unique identifier.

title (optional)

string

Display title. It can be formatted as a short label or a longer question or sentence.

required (optional)

boolean

If the field is required there will always be a corresponding value in the response.

per_page (optional)

boolean

If the field is defined for each page, or for the entire document

type

string

The specified FieldType. See below for details.

options (conditional)

object array

Only for select type. A list of OptionType. See below for details.

conditions (optional)

object array

An array of conditions, one of which needs to be satisfied to display this field. See below for details.

📘

Field vs Feature: What is the difference?

Every feature represents a class of content in the document that can be annotated with a location in the pages of the document. Every field represents a question about the document as a whole.

Params FieldParams Object TypeResponse FieldResponse Object Type
featuresFeatureannotationsDocument Transcription Annotation
fieldsFieldvaluesDocument Transcription Value

Conditional Fields

Sometimes a field should only be presented if specific choices are selected for other fields. In these cases, you can specify the conditions — the dependent questions and corresponding sets of choices.

The conditions property should have the following structure: an array of objects which define a set of conditions allowing the field to be shown. Each object should have the following structure:

  • Key: the field_id of the dependent field.
  • Value: an array of strings representing the acceptable field values for the dependent field.
// Example of fields with conditional rendering
[
  {
    "field_id": "document_type",
    "title": "What type of document is this?",
    "type": "select",
    "options": [
      {
        "title": "Invoice",
        "value": "invoice"
      },
      {
        "title": "Other",
        "value": "other"
      }
    ]
  },
  {
    "field_id": "currency",
    "title": "What currency is used in this document?",
    "type": "select",
    "options": [
      {
        "title": "Euro",
        "value": "EUR"
      },
      {
        "title": "United States dollar",
        "value": "USD"
      }
    ]
  },
  {
    "field_id": "language",
    "title": "What language is this document in?",
    "type": "select",
    "options": [
      { "title": "English", "value": "en" },
      { "title": "French", "value": "fr" }
    ],
    "conditions": [
      {
        "document_type": ["invoice"] // Only display this field for invoices
      }
    ]
  },
  {
    "field_id": "tax_type",
    "title": "What type of tax is referenced in this document?",
    "type": "select",
    "options": [
      {
        "title": "VAT",
        "value": "vat"
      },
      {
        "title": "Other",
        "value": "other"
      }
    ],
    "conditions": [
      // Display this field for French invoices or documents with EUR currency
      {
        "document_type": ["invoice"],
        "language": ["fr"]
      },
      {
        "currency": ["EUR"]
      }
    ]
  }
]