Fields and Fieldsets

There are two main types of fields to consider when dealing with the Zapier API: input fields and output fields:

​

Input Fields

To fetch the input fields for an Action, make a request to the /actions/{action_id}/inputs endpoint:

​

Invalidation

The invalidates_input_fields field signifies whether the input fields should be refetched from /inputs when the value of the given field is changed. A real-world example of when this might be required is for spreadsheet apps. When adding a new row to a sheet, the first input field allows the user to select the relevant sheet and, once that is selected, more input fields become available (one for each column in the selected sheet). If the user changes the sheet, then the input fields must be refetched.

When making a request to refetch the input fields, make sure to include all the fields that have been populated so far:

In this example, if the user changes the value of spreadsheet, we should refetch /inputs and pass this new value to reload all fields. If worksheet is modified, once again we’d refetch /inputs and reload the non-dependant fields. This is because both spreadsheet and worksheet have invalidates_input_fields field set to true.

​

Dependencies

Sometimes one input field depends on one or more other fields, meaning /inputs should be refetched if any of the dependent fields are changed. This is represented via the depends_on array field, which has strings of field IDs in it. Continuing with the spreadsheet example, the worksheet field depends on the spreadsheet field. That is, if the user changes which spreadsheet they are working in, the value of the worksheet field must be cleared (and /inputs refetched)---as the set of inputs available for the action will now be different.

​

Invalidation & Dependancy Flow

​

Input Field Types

Per the schema, the options for value_type are: STRING, NUMBER, INTEGER, BOOLEAN, ARRAY, and OBJECT. The following variants warrant additional consideration:

"column_names": {
  "value_type": "ARRAY",
  "items": {
    "type": "STRING"
  }
}

"column_names": ["Word", "Definition"]

"dictionary": {
  "value_type": "OBJECT"
}

"dictionary": {
  "apple": "A fruit!",
  "salmon": "A fish!"
}

{
  "type": "input_field",
  "id": "replace_all_rows",
  "format": "SELECT",
  "value_type": "BOOLEAN"
  ...
}

// repsonse from POST https://api.zapier.com/v2/actions/core:gq7MXdsdsaaqqDBj/inputs/replace_all_rows/choices
{
  "id": "False",
  "type": "choice",
  "label": "No",
  "value": "False"
},
{
  "id": "True",
  "type": "choice",
  "label": "Yes",
  "value": "True"
}

"False"

​

Input Formats

The format key indicates how to present a given input field to the user, per the schema. Its options are: DATETIME, MULTILINE, PASSWORD, CODE, READONLY, FILE, SELECT. Additional information on how these fields are processed by Zapier can be found in our help docs.

The following variants warrant additional consideration:

"format": "READONLY"

"format": "FILE"

"format": "SELECT"

​

Choices

When the format key is equal to SELECT, the /choices endpoint returns a list of options from which the user should select.

Continuing the spreadsheet example, the first input field is (spreadsheet) which is a string type. The format is SELECT, which implies this field has a set of choices for the user to select from (which would normally be rendered as a dropdown menu in the UI).

To fetch these, use the /actions/{action_id}/inputs/{input_id}/choices endpoint:

So, this input field has only two choices available. When making a zap pass the id of the selected choice for the desired input.

​

Fieldsets

Input fields may be grouped together into fieldsets (just like in HTML). This gives a hint as to how the fields should be rendered in the UI.

Only one level of nesting is supported (a Fieldset cannot be contained within another Fieldset).

​

Informational Fields

An informational field is one that has no input, but contains some markdown-formatted text which should be rendered in the relevant position in the form. This is often used to give helpful tips to the user.

​

Output Fields

Once the user has populated all the input fields, we can determine which output fields are available from the given action using the /actions/{action_id}/outputs endpoint:

In reality, many more output fields would likely be available. For details on how these can be mapped into the input fields of subsequent steps in a Zap, see Building a Zap.