Events

The Events and Profiles API is in early access. The API can be enabled by an admin in your account. In Admin Center, go to Sunshine > Settings (https://your_subdomain.zendesk.com/admin/sunshine/settings), select the Events and Profiles API, and click Save.

The Events API lets you build a timeline of all your customers' interactions from any source. An event can be any programmatic event that your application or system can associate with a user. Examples include purchase transactions, website visits, or customer service interactions.

Each event is associated with a customer who triggered the event.

In addition to this API reference, the following resources are available in the Develop Help Center:

JSON Format

An event consists of a JSON object describing both the event and the user who triggered the event. All properties are writable.

Name Type Required Comment
profile object yes The user who triggered the event. See profile object
event object yes The event triggered by the user. See event object below
profile object

A profile object describes a user known by your application or system. The object has the following properties.

Name Type Required Comment
source string yes The product or service associated with the profile. Examples: "Support", "Salesforce", "Chat"
type string no The type of profile. Examples: "Contact", "Lead"
identifiers object yes One or more user identities. See identifiers object

To specify a Zendesk Support user

  1. Specify the "source" as "support".
  2. Omit the "type" property.
  3. Add a "user_id" identifier to the identifiers object.

Example:

"profile": {
  "source": "support",
  "identifiers": {
    "user_id": "361959350832"
  }
}
event object

An event object has the following properties.

Name Type Required Comment
type string yes An event name such as "login" or "checkout"
source string yes Application or system that sent the event, such as "shopify" or "twitter"
description string no Friendlier version of the event. Examples: "Check out" or "5 stars", if the event is a rating
created_at string no ISO-8601-compliant date-time. If you don't specify a value, the API sets the value to when it received the event. Example: "2018-08-07T19:23:13Z"
properties object no A custom JSON object with details about the event. Must comply with the JSON Schema specification
Example
{
  "profile": {
    "source": "shopify",
    "identifiers": {
      "user_id": "361959350832"
    }
  },
  "event": {
    "type": "order_completed",
    "created_at": "2018-11-05T22:26:00Z",
    "description": "Added item to cart",
    "properties": {
      "item": {
        "name": "Canon 429 EOS HD",
        "query": "camera",
        "price": "499.99"
      },
      "shipping": {
        "eta_date": "2019/01/02",
        "address": {
          "address1": "1019 Market Street",
          "city": "San Francisco",
          "state": "CA",
          "zipcode": "94103"
        }
      }
    }
  }
}

Track Event

POST /api/sunshine/events

OR

POST /api/sunshine/track (deprecating soon)

Stores an event in Zendesk. An event can be any programmatic event that your application or system can associate with a user.

Allowed For
  • Agents
Using cURL

In the example that follows, the cURL command reads JSON event data from a file.

data.json

{
  "profile": {
    "source": "support",
    "identifiers": {
      "user_id": "361959350832"
    }
  },
  "event": {
    "source": "shopify",
    "type": "remove_from_cart",
    "description": "Blue suede shoes",
    "created_at": "2019-01-07T21:19:00Z",
    "properties": {
       "size": 6,
       "model": 221
    }
  }
}

cURL command

curl https://{{subdomain}}.zendesk.com/api/sunshine/track \
  -d @data.json \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -v -u {email_address}:{password} -X POST
Example Response
Status: 202

Retrieve Events of Profile

GET /api/sunshine/events?{query}

Returns events associated with a profile.

The following query string parameters are required:

You can also include any of the following optional query string parameters:

  • source - Include only events of the specified source. Example: source=amazon
  • type - Include only events of the specified type for a given event source. Example: source=amazon&type=checkout
  • start_time - Include only events with a later or equal to created_at time
  • end_time - Include only events with an earlier or equal to created_at time
  • items - Include only the specified number of events

Make sure to url-encode the query string before sending the request. In cURL, you can use the --data-urlencode option with the -G option. The -G option ensures the command makes a GET request instead of the POST request it would otherwise make.

Allowed For
  • Agents
Using cURL
curl -G "https://{subdomain}.zendesk.com/api/sunshine/events" \
  --data-urlencode "identifier=support:user_id:361959350832" \
  -H "Accept: application/json" \
  -v -u {email_address}:{password}
Example Response
Status: 200

{
  "data":[
    {
      "id":"5c42123e98326c0001b0b25c",
      "type":"remove_from_cart",
      "source":"shopify",
      "description":"",
      "created_at":"2019-01-07T21:19:00Z",
      "received_at":"2019-01-07T21:19:58Z",
      "properties":{
        "model":221,
        "size":6
      }
    },
    ...
  ],
  "links":null
}