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
Those that are provided to an Action so that it can run. They are analogous to the arguments that a function takes.
Output fields
Those that are returned by an Action. These may then be mapped into the input fields of a subsequent Action in a Zap.
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
The sequencing of inputs can be complex for certain actions, this flow demonstrates how to present these inputs to users.
Input Field Types
Thevalue_type
key indicates what type of user data is accepted for a given field.
Per the schema, the options for value_type
are: STRING
, NUMBER
, INTEGER
, BOOLEAN
, ARRAY
, and OBJECT
.
The following variants warrant additional consideration:
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:
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.