Docs / API Overview

Events

Data references

An event is an action performed by a customer, such as browsing a product page or subscribing to a newsletter.

Event types

Type Description
BROWSE A generic browsing event, see the required supplemental fields below.
MAIL_SUBSCRIBE Add email marketing permission for given customer. If no customers are found with the given email address new customer will be created.
MAIL_UNSUBSCRIBE Unsubscribe customer from the email list.
ORDER_SHIPPED An order related to a sale has been shipped. You may supply sale_id and tracking_number, if you want to identify the shipment and the associated sale.
BASKET_ADD Product added to shopping basket. Identify the product added with product_id key, with the identifier of your product.
SENTIMENT Customer satisfaction survey result. Whenever the customer responds to a customer satisfaction survey, you may send this event with key sentiment_value, being an integer.

Additional company specific event types can be specified in the Custobar advanced settings page.

Common fields

Mandatory fields

Field Type Description
type string The event type in capital letters, see the table above for possible event types.
date datetime Date of the event, e.g. 2015-08-28 or 2015-08-28T14:10:00Z. If the timezone is not given, the timezone will be defaulted to the timezone configured in the Custobar's settings.

The customer generating the event is identified by supplying at least one of the customer identifying fields customer_id, phone_number or email.

Depending on the event type, some additional fields are required.

Event Field Type Description
BROWSE label string A label that you've assigned to the particular page, and/or
BROWSE product_ean string the EAN for the product, and/or
BROWSE product_id string identifier of the product being browsed that is stored in Custobar, and/or
BROWSE path string the browsed path, and/or
BROWSE utm_campaign string the UTM tag associated with this browse.
MAIL_SUBSCRIBE mailing_lists list of string List of email list names to subscribe.
MAIL_UNSUBSCRIBE mailing_lists list of string List of email list names to unsubscribe from. To unsubscribe from all lists, use a special list name _ as the singular element in the list.
ORDER_SHIPPED tracking_number string Tracking number provided by the shipping company.
SENTIMENT sentiment_value integer The sentiment value as an integer, usually a number between 0 and 10, bounding values included.

Optional fields

In addition to mandatory fields, you may provide additional fields that provide more information on the event.

Field Type Description
reason string A string providing additional information related to the event for the Custobar users.
source string A string designating the source of the event, e.g. "unsubscribe form" or "service desk".
utm_campaign string A campaign identifier, which this event is a part of.
utm_medium string A medium through which the event came through.
utm_content string A content piece related to the event.
utm_source string The UTM source of an event.
tags [set][] of string Tags assigned for this Event.

The following customer fields may also be provided together with the event data:

  • first_name
  • last_name
  • street_address
  • zip_code
  • country
  • language

Company-specific fields

You may add additional fields, that are company specific by prefixing them with a company short name and a double underscore __, e.g. COMPANY__loyalty_level.

Company specific fields are searchable in the Custobar user interface.

Example

To upload events, you may pass them to Custobar using a HTTP POST command, e.g.

curl -X POST -u USER -H "Content-Type: application/json" \
    --data-binary @events.json https://COMPANY.custobar.com/api/events/

The events must be provided as a list of objects, each object containing the information of a single event.

[
  {
    "type": "BROWSE",
    "date": "2016-10-25T12:50:19Z",
    "product_id": "9000",
    "customer_id": "23132",
    "utm_source": "partner-a",
    "COMPANY__loyalty_level": "platinum"
  },
  {
    "type": "MAIL_SUBSCRIBE",
    "date": "2016-10-25T12:51:29Z",
    "email": "john.doe@example.org",
    "mailing_lists": ["carpentry", "new_products"]
  },
  {
    "type": "MAIL_UNSUBSCRIBE",
    "date": "2016-10-25T13:00:19Z",
    "email": "jane.doe@example.org",
    "mailing_lists": ["new_products"]
  },
  {
    "type": "ORDER_SHIPPED",
    "date": "2016-10-30T12:04:51Z",
    "email": "jane.doe@example.org",
    "sale_id": "20140980234098",
    "COMPANY__tracking_number": "JJFIFAKE234082984"
  }
]