Authenticating with Zapier is required to build alongside this guide. This is covered separately here.
First Step
Whenever there is a new lead in SuperExampleCRM…
Second Step
…a new engagement report is sent to PlatformAdManager
Zap Step Requirements
Each Zap step in turn, is comprised of:An Action
An Action is an operation that can be performed against a third-party API; such as a
READ
or a WRITE
.An Authentication
An Authentication is a set of user credentials for an App that is stored securely by Zapier.
A Group of Inputs
Inputs are fields that are provided to an Action so that it can run. They are analogous to the arguments that a function takes.
Configuring the first step
“When there is a new lead in SuperExampleCRM …”*
The first step of a Zap will usually have a
READ
or SEARCH
action type.Selecting an Action
The first thing that we need to do is select an Action for the first step of the Zap. See Selecting an Action for more details. Let’s say that theid
of the SuperExampleCRM app is 4b3920d6-1d5a-4071-b837-9383dc511b80
. Given that id and that the first action of an app will usually have the action_type
READ
, we can fetch a list of available actions for the selected app by making a request to the /actions
endpoint.
Selecting an Authentication
The next step is to select an authentication for the first step of the Zap. See Selecting an Authentication for more details. We can make a request toGET /authentications?app=4b3920d6-1d5a-4071-b837-9383dc511b80
and allow the user to select which one of the returned Authentications they wish to use. (See Selecting an Authentication for what to do when there are no Authentications, Authentication isn’t required, or if a new Authentication should be created)
For this guide, we’ll say that the user chose the authentication with id
"49509"
Configuring Inputs
The last thing that we need to do for step 1 of the Zap is to select input values. Please see Fields and Fieldsets for more details on fetching available Input Fields for a given Action, and reloading Input Fields as the user provides input data. In an above step, the user selected the “New Lead” action with idcore:wJ3PxHpNArZ8MqvloW3L1ZyMDQ4nJ
. With the /actions/{action_id}/inputs
endpoint, we can get a list of the input fields that our first action requires
Please see Fields and Fieldsets for more details on fetching available Input Fields for a given Action, fetching Choices for Input Fields, and reloading Input Fields as the user provides input data.
Lead type
.
This gives the user the opportunity to configure the action so that it only
returns a certain type of lead.
In this example, the format
of this input field is SELECT
, which means we
now need to fetch the possible values which are available:
inputs
field object, as the user has not yet
provided any input. If there are multiple input fields, this object should be
populated as the user progresses through them.
In this case, there are two available choices for the lead_type
field:
company
and person
. With this information, we can render a dropdown field
and allow the user to select one of them.
For this guide, we’ll say that the user selected person
from the dropdown.
Configuring the second step
”… a new engagement report is sent to PlatformAdManager”*
Selecting an Action
Selecting an Action for the second step of a Zap follows the same process and uses the same API endpoints as selecting an Action for the first step of a Zap, with the two exceptions that a different App id should be used, and that theaction_type
of the second action will usually be a WRITE
. In this case, let’s say that the id of the PlatformAdManager App is 9c29df46-f9b9-48e2-a879-8f5479d8401d
. We can fetch a list of available actions for PlatformAdManager by making a request to the /actions
endpoint.
Selecting an Authentication
Selecting an Authentication for the second step of a Zap follows the same process and uses the same API endpoints as selecting an Authentication for the first step of a Zap, with the exception that a a different App id should be used. In this case, we would make a request toGET /authentications?app=9c29df46-f9b9-48e2-a879-8f5479d8401d
Again, our user can select which of the available authentications they would like to use with this Zap. For this guide, we’ll say that the user chose the authentication with id
"857610"
Configuring Inputs
For the second step of a Zap, you can follow the same process outlined above to fetch Input Fields, Choices, and reload Input fields as a user provides input data. For this guide, lets say that we make the following request and get the below fields in response.Again, please see Fields and Fieldsets for more details on fetching available Input Fields for a given Action, fetching Choices for Input Fields, and reloading Input Fields as the user provides input data.
Mapping Outputs to Inputs
We get the available output fields of our first action from the outputs endpoint:full_name
to step 2’s Input Field engaged_party
by using double curly braces {{step1_field_id}}
, or in this case {{full_name}}
.
Create a Zap
Now that we have an Action, Authentication, and Inputs for each step of our Zap, we can use the POST /zaps endpoint to create a fully configured Zap.It is expected that the returned Zap doesn’t include any step
inputs
- The
action
of each step is theid
of the Action that the user selected. - The
authentication
of each step is theid
of the Authentication that the user selected. - The
inputs
of each step is an object where each key is theid
of an Input Field- In the case of
engaged_party
(where we mapped an Output Field from step 1 to an Input Field of step 2), the value is theid
of the Output Field from step 1 wrapped in double curly braces{{...}}
- In all other cases, the value is a static value that was selected or otherwise configured by the user
- In the case of