Login

Security and Compliance

How to Use the Generate event API Resource

Using the Generate event API resource, you can send events from your website and store them in our system. These events can be used for triggering a workflow or for segmentation purposes.

Note

Version 2 API methods do not require escaping in nested JSON.

The method has the following body parameters explained in the table below.

Important

The maximum size of content for events sent in the request body is 20 kilobytes. Please contact Support if you need to adjust the maximum size.

Parameter Type Description
eventTypeKey string, required Event type ID key. If no such event type exists with such a key, a new one is created.
All characters are allowed except < ; ’ \ / | " ` ' ^ ? ! , >
Max length: 100 symbols
keyValue string Event key. Determines event uniqueness.
The key must contain a unique value for each contact (for example, email, phone number, external contact id, etc.)
If this parameter is not set, params must contain one of the following contact identifiers:
  • contactId
  • externalCustomerId (see the note below)
  • email
  • phone
  • pushToken: web or mobile
All characters are allowed except < ; ’ \ / | " ` ' ^ ? ! , >
Max length: 300 symbols
params array of objects List of event parameters represented as an array of "key" - "value" pairs. The parameter keys are arbitrary.
Used in campaigns and for creating dynamic content in messages.

Important

When passing events using the Generate event v2 method, externalCustomerId in params  is ignored if it contains the empty or null value. For example, "", " ", " ", "null", null.

You can use this API resource for sending the following requests, as described below.

Abandoned Browses and Carts

Request example:

{
    "eventTypeKey": "abandoned_cart",
    "keyValue": "site@com.net",
    "params":
    [
        {
            "name": "email",
            "value": "site@ukr.net"
        },
        {
            "name": "items",
            "value":
            {
                "array":
                [
                    {
                        "name": "Hair styler",
                        "price": "341",
                        "url": "https://site.com/catalog/suhaya-detskaya-molochnaya-smes-hipp-combiotic-2-750-g",
                        "imageurl": "https://site.com/uploads/product/big/20161122/20161122_7zvb.jpg",
                        "brand": "Le Petit Olivier",
                        "tags_weight": "200",
                        "tags_oldprice": "467"
                    },
                    {
                        "name": "Magnolia Nobile Парфумована вода",
                        "price": "2341",
                        "url": "https://site.com/catalog/suhaya-detskaya-molochnaya-smes-hipp-combiotic-2-750-g",
                        "imageurl": "https://site.com/uploads/product/big/20161122/20161122_7zvb.jpg",
                        "brand": "Acqua Di Parma",
                        "tags_weight": "100",
                        "tags_oldprice": "4467"
                    }
                ]
            }
        }
    ]
}

eventTypeKey is a string identifier for the event type. If it did not exist before, after the first request it appears in the account, and you can see it in the AutomationEvent types section.

New event

To view the event body, go to Automation → Event history and click the event.

Event body

  • keyValue is the event key.
  • params are event parameters that can be used in a workflow. Their number is unlimited.

An array is a required format of an event {"name," "value": "site@en.net."}

This means that the data contains a variable email with the value of site@en.net. It must be specified in the workflow > block Email > Contact’s email for the email to be sent to site@en.net.

Workflow with the selected contact's email

The array contains two items (two products here) with a set of variables: name, price, url, imageurl, brand, tags_weight, tags_oldprice. The number of items is unlimited. The names of variables are arbitrary.

To use the array data in a message, in the block Email > JSON, specify the name of the field items:

Where to select JSON

You insert the data from the request into the message using Velocity.

To refer to the data, use the following loop:

#foreach($!item in $!data.get('array'))
$!item.get('name')
$!item.get('price')
$!item.get('url')
$!item.get('imageurl')
$!item.get('brand')
$!item.get('tags_weight')
$!item.get('tags_oldprice')
#end

You can refer to the array elements straight with the index (order starts at 0). This method can cause errors in content substitution if an element is missing.

First element:

$!data.get('array').get(0).get('name')
$!data.get('array').get(0).get('price')
$!data.get('array').get(0).get('url')
$!data.get('array').get(0).get('imageurl')
$!data.get('array').get(0).get('brand')
$!data.get('array').get(0).get(''tags_weight')
$!data.get('array').get(0).get('tags_oldprice')

Second element:

$!data.get('array').get(1).get('name')
$!data.get('array').get(1).get('price')
$!data.get('array').get(1).get('url')
$!data.get('array').get(1).get('imageurl')
$!data.get('array').get(1).get('brand')
$!data.get('array').get(1).get(''tags_weight')
$!data.get('array').get(1).get('tags_oldprice')

The number of elements is unlimited.

Important!

Variables are case-sensitive. If an email contains $!item.get ('ImageUrl') and the request transfers imageurl, the variable will not be inserted.

To view and check dynamic data in an email, click Additional settings > Configuring dynamic content.

How to view dynamic data in the email

Insert an array with dynamic data and click View message.

Parameters of dynamic content

  • In case of an error in the dynamic content substitution, check the Velocity syntax in the message.
  • If you see the Wrong Format error, check the JSON request body.
  • If there are no errors, but the data is not inserted in the preview, check whether the variables in the request and variables in the email correspond and whether variables are referred to correctly.
  • If there are no errors and the data is substituted correctly, run a test by sending an API request to the account.

Create or Update a Contact

Request sample:

{
    "eventTypeKey": "create_contact",
    "keyValue": "site@com.net",
    "params":
    [
        {
            "name": "email",
            "value": "site@ukr.net"
        },
        {
            "name": "phone",
            "value": "380501234567"
        },
        {
            "name": "externalCustomerId",
            "value": "AV13760"
        },
        {
            "name": "json",
            "value":
            {
                "profileInputs":
                [
                    {
                        "profileInputId": 10001,
                        "value": "2020-11-23"
                    }
                ]
            }
        }
    ]
}

where,

  • 10001 is the ID of the additional field.
  • 2020-11-23 is the value of the additional field.

Check that the transferred data comply with the following requirements:

  • The name and surname length is up to 60 characters.
  • The phone number is in the international format. For example, +1-541-754-3010.
  • The value of an additional contact field is in the required format.

If the transferred data contains errors, the system ignores the entire array and does not add or update data in the contact card.

For a workflow to run correctly, in the block Task (Create contact/Update contact), specify a variable ${email} in the field Contact’s email and a variable ${json} in the field JSON.

Specify Contact's email and JSON

Learn more about the Task block

In addition to that, the Generate event resource can be used to create or update a contact and to trigger a workflow that sends messages with the dynamic content. It can also be used to send orders to the system.

Send Transactional Letters

Let's consider the example of launching a password recovery letter.

Request example:

{
"eventTypeKey": "password_recovery",
"keyValue": "site@com.net",
"params": [{
"name": "EmailAddress",
"value": "site@ukr.net"
},
{
"name": "password",
"value": "12345678"
}
]
}

In the workflow, it is necessary to use the Task - Send obligatory (transactional) email block. Enter the $!data.get('password') variable in the letter you want to send.

Transactional Email Workflow

To learn more about the Task block, read this manual.

Validate Contact Data in Events

You can validate the contact data in events using the Generate event v2 API method.

To validate contact data in events, you have to set contactJson in params as a parameter name.

{
  "params": [
    {
      "name": "contactJson",
      "value": "..."
    }
  ]
}

Indicate the data you want to validate in the value field.

Example:

{"firstname":"...","lastname":"...","sms":"...","town":"...","timeZone":"Etc/GMT+03","languageCode":"uk","profileInputs":
[{"profileInputId":10001,"value":"..."}],"confirmed":false}

When you send this request using the Generate event v2 API method, REST API understands it as receiving a new contact and performs data validation.

If the data is not valid, the method returns the 400 Bad Request response. The response contains the non-valid fields and the error details.

Read Validating event parameters to learn more.

Any Questions?
We’re always happy to help!
Discount services
Schedule a Call
Fill in the form, and our specialists will call you back as soon as possible.
Discount services
Chat Support
We’re waiting for your questions!
Discount services
Email
Contact the support team