How to Build a Workflow

For this guide, let’s assume that we want give our users the ability to automate workflows with the (imaginary) apps SuperExampleCRM and PlatformAdManager so that when there is a new lead in SuperExampleCRM, a new engagement report is sent to PlatformAdManager. We need to build a zap in your product with SuperExampleCRM and PlatformAdManager. Zaps are comprised of a series of steps, so in this example our two steps would be:

​

Zap Step Requirements

Each Zap step in turn, is comprised of:

To build a Zap, we’ll need to select an Action, Authentication, and Inputs for each step.

​

Configuring the first step

”When there is a new lead in SuperExampleCRM …”*

​

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 the id of the SuperExampleCRM app is 4b3920d6-1d5a-4071-b837-9383dc511b80. Given that id and the constraint that the first action of an app must 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.

GET /actions?app=4b3920d6-1d5a-4071-b837-9383dc511b80&action_type=READ

Our user can then select one of these Actions that they wish to use as the Trigger for their Zap. For this guide, we’ll say that the user chose the “New Lead” Action:

{
  "id": "core:wJ3PxHpNArZ8MqvloW3L1ZyMDQ4nJ",
  "key": "new_lead"
  "app": "4b3920d6-1d5a-4071-b837-9383dc511b80",
  "type": "action",
  "action_type": "READ",
  "is_instant": true,
  "title": "New Lead",
  "description": "Triggers when a new lead is added to SuperExampleCRM"
}

​

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 to GET /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"

{
  "type": "authentication",
  "id": "49509",
  "app": "4b3920d6-1d5a-4071-b837-9383dc511b80",
  "title": "SuperExampleCRM (wade@zapier.com)",
  "is_expired": false
}

​

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 id core:wJ3PxHpNArZ8MqvloW3L1ZyMDQ4nJ. With the /actions/{action_id}/inputs endpoint, we can get a list of the input fields that our first action requires

As you can see, this action only has a single input field: the 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:

Again, we’ve provided an empty 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 the action_type of the second action should be 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.

GET /actions?app=9c29df46-f9b9-48e2-a879-8f5479d8401d&action_type=WRITE

Again, our user can then select one of these Actions that they wish to use. For this guide, we’ll say that the user chose the “Create Engagement Report” Action:

{
  "id": "core:3ZYFzZKkjbDK2AwQopVqrZWL9pK",
  "key": "create_engagement_report"
  "app": "9c29df46-f9b9-48e2-a879-8f5479d8401d",
  "type": "action",
  "action_type": "WRITE",
  "is_instant": true,
  "title": "Create Engagement Report",
  "description": "Creates a report of as engagement"
}

​

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 to GET /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"

{
  "type": "authentication",
  "id": "857610",
  "title": "PlatformAdManager (wade@zapier.com)",
  "app": "9c29df46-f9b9-48e2-a879-8f5479d8401d",
  "is_expired": false
}

​

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.

We can go through the same process that we did in Step 1 of presenting input fields to the user and receiving input configuration. However, we also have the option of creating dynamic input by mapping the Output Fields of step 1 to the Input Fields of step 2.

​

Mapping Outputs to Inputs

We get the available output fields of our first action from the outputs endpoint:

Now, we can use these output fields when we configure the second action of our Zap.

When we configure the inputs of step 2, we can map Step 1’s Output Field 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.

Notice that we’ve combined all of the configurations we collected above to construct the body of this request.

• The action of each step is the id of the Action that the user selected.
• The authentication of each step is the id of the Authentication that the user selected.
• The inputs of each step is an object where each key is the id 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 the id 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