This article explains the custom API event trigger and how to use it to build a workflow.

Ⓘ Available to Plus, HQ, Essentials, Teams, and Corporate accounts

When using our automation tool, there are multiple trigger types to choose from: email signup, date-based, contact import, field change, link click, and custom API event. The custom API event trigger fires a workflow when events that are shared with Emma from other platforms using Emma’s Event API meet certain criteria.

In this article How do custom API events work? How to use the custom API event trigger Custom API event example Additional resources

How do custom API events work?

Custom API events use specific API calls to communicate with other applications outside of Emma. When an application sends a call to Emma's Event API, the call contains information in a special format called key/value pairs. Emma uses the information in those key/value pairs to determine which contacts meet the criteria for an automation.

Ⓘ	If your goal is a trigger a workflow when someone signs up through an integration, custom form, or API call, the custom API event trigger is not the best option. Instead, please refer to this article about the email signup trigger.

How to use the custom API event trigger

To select the custom API event trigger, follow the steps below:

1. Navigate to your Campaigns tab.
2. Click on the Automations section in the panel on the left.
3. Click on the Create new workflow button.
4. Click on Choose your trigger event.
5. In the panel on the right, select Custom API event.
6. Click on the Next button.
7. In the Key field, enter the desired key.
8. Click on the Equals box to choose a condition. You can choose from the operators listed below. Numeric operators will not work with text values.
   • Equals
   • Does not equal
   • Contains
   • Does not contain
   • Greater than
   • Greater than or equal to
   • Less than
   • Less than or equal to
9. In the Value field enter the desired value for the key.
10. To add more key/value pairs, click on Add criteria. You can add up to five key/value pairs.
11. Click on the Next button.
12. Select whether you'd like for the workflow to fire only once per contact, or if you'd like it to fire every time a contact triggers the event.
13. Click on the Next button.
14. Click on the Confirm button.

Ⓘ	Only contacts who are currently in the Active status within your audience can be entered into event-powered workflows.

Custom API event example

The following snippet is a simplified sample of an event that might be shared with Emma using the Event API. Note that the information contained within the order is stored in key/value pairs.

{
  "event_name": "order-completed",
  "id": 1028374857,
  "email": "test@test.com",
  "closed_at": null,
  "created_at": "2016-04-12T11:00:00-09:00",
  "total_price": "145.53",
  "total_discounts": "14.70",
  "order_number": 1001,
  "discount_codes": [
    {  
    "code": "TEN16",
      "amount": "10.00",
      "type": "percentage"
    }
  ],
  "line_items": [
    {
      "id": 998327818,
      "variant_id": 59284621,
      "title": "Slim Short Sleeve Linen Shirt",
      "quantity": 1,
      "price": "68.00",
      "sku": "SLSSLNSHRT",
      "variant_title": "white",
      "size": "medium",
      "product_id": 632910392,
      "requires_shipping": true,
      "taxable": true,
      "gift_card": false,
      "name": "Slim Short Sleeve Linen Shirt - White",
      "tax_lines": [
        {
          "title": "State Tax",
          "price": "6.12",
          "rate": 0.09
        }
      ]
    },
    {
      "id": 789327523,
      "variant_id": 89137513,
      "title": "Slim Mens Chino",
      "quantity": 1,
      "price": "79.00",
      "sku": "SLMNCHNO",
      "variant_title": "green",
      "size": "32W32L",
      "product_id": 948517351,
      "requires_shipping": true,
      "taxable": true,
      "gift_card": false,
      "name": "Slim Mens Chino - Green",
      "tax_lines": [
        {
          "title": "State Tax",
          "price": "7.11",
          "rate": 0.09
        }
      ]
    },
    "shipping_lines": [
      {
        "id": 0928273492,
        "title": "Free Shipping",
        "price": "0.00",
        "code": "Free Shipping",
        "source": "shopify",
        "phone": null,
        "carrier_identifier": null,
        "tax_lines": [
        ]
      }
    ]
  ]
}

In the above example, the key event_name contains the value order-completed. Top-level key/value pairs like this can be used to power automated workflows.

Ⓘ	If you want to trigger a workflow with the event_name parameter, the value must be all lower case. For example, "event_name": "order-completed" will work, but "event_name": "Order_Completed" will not.

 

However, you’ll also see that, in addition to simple key/value pairs like event_name, total_price, and email, there are keys that include much more than a single value. For example, line_items not only includes the names and IDs of the two products purchased in this order, it also contains detailed information about their price, size and other attributes. The line_items key is therefore said to contain nested attributes, and the individual items within the line_items section contain nested attributes of their own (for the information in the tax_lines section).

Ⓘ	Workflows cannot be triggered or filtered based on data contained in nested attributes.

Additional resources

• How to use the automation workflow builder
• How to edit an automated mailing
• Trigger events: Email signup
• Trigger events: Date-based
• Trigger events: Field change
• Trigger events: Link click
• Trigger events: Contact import