Events API

The Profiles API and Events API are in early access. The APIs 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:

Run in Postman

You can import the Events API endpoints as a collection into your Postman app, then try out different requests to learn how the API works. Click the following button to download the collection:

Run in Postman

If you don't use Postman, you can sign up for a free account on the Postman website and download the app.

JSON Format

Events are represented as JSON objects which have the following keys:

Name Type Read-only Mandatory Description
created_at string false false ISO-8601 compliant date-time reflecting the time the event was created. If not set, the API sets the value when it receives the event
description string false false An event description
id string true false ID of the event
properties object false true A custom JSON object with details about the event. Must comply with the JSON Schema specification
received_at string true false ISO-8601 compliant date-time reflecting the time the event was received
source string false true Application which sent the event
type string false true Event name

An event consists of a JSON object describing both the event and the user who triggered the event.

Name Type Required Description
profile object yes The user who triggered the event. For more information, see profile object
event object yes The event triggered by the user. For more information, see the event object
Profile Object

A profile object describes a user associated with an application or system. The object has the following properties:

Name Type Required Description
source string yes The product or service associated with the profile. For example, "Support", "Salesforce", or "Chat"
type string yes The type of profile. For example, "Contact" or "Lead"
identifiers object yes One or more user identities. See the identifiers array
Example
{
  "profile": {
    "source": "shoppingnow",
    "type": "customer",
    "identifiers": [
      {
        "type": "shoppingnow_id",
        "value": "361959350832"
      }
    ]
  },
  "event": {
    "source": "shoppingnow",
    "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"
        }
      }
    }
  }
}

Get events by Sunshine profile

GET /api/v2/user_profiles/events?identifier={identifier}

Returns events for a Sunshine profile.

To locate the specific profile, you must specify an identifier query as a URL paramater in a request. For more information, see Identifier queries.

You can also include any of the following optional query string parameters in the format of filter[{optional parameter}]=:

  • source - Include only events of the specified source. For example, filter[source]=amazon
  • type - Include only events of the specified type for a given event source. For example, filter[source]=amazon&filter[type]=checkout
  • start_time - Include only events with a later or equal to filter[created_at] time
  • end_time - Include only events with an earlier or equal to filter[created_at] time

page[size] specifies the number of events. Note, it is a parameter in itself and not a filter[] parameter value.

To understand how to use the optional filter[] path parameter, see Filtering Sunshine events.

The query string must be url-encoded before sending the request. In cURL, use the --data-urlencode option with the -G flag. The -G flag forces the command to make a GET request instead of a default POST request.

Allowed For
  • Agents
Available Parameters
Name Type In Required Description
filter[end_time] string Query false Include events equal to or before the created_at time
filter[source] string Query false Include events of the specified source
filter[start_time] string Query false Include events equal to or later than the created_at time
filter[type] string Query false Include events of the specified type for the given event source. The filter[source] parameter must be included
identifier string Query true Pass a profile identifier query to filter for a specific profile in the format source:type:identifier_type:identifier_value. For more information, see https://developer.zendesk.com/rest_api/docs/sunshine/profiles_api#identifier-queries
page[size] string Query false Include the specified number of events
Using curl
curl "https://{subdomain}.zendesk.com/api/v2/user_profiles/events?identifier={identifier_query}" \
  -u {email_address}:{password}
Example Response
Status 200

{
  "events": [
    {
      "created_at": "2020-01-31T00:44:07+00:00",
      "description": "Order complete",
      "properties": {
        "billing": {
          "address1": "1019 Market St",
          "city": "San Francisco",
          "state": "CA",
          "zipcode": "94103"
        },
        "item": {
          "name": "Zendesk Swag"
        }
      },
      "source": "shoppingnow",
      "type": "checkout"
    }
  ],
  "links": [
    {
      "next": "https://yoursubdomain.zendesk.com/api/v2/user_profiles/1/events?page[token]=hkjhdjk"
    }
  ]
}

Track event against a Sunshine profile

POST /api/v2/user_profiles/events

Stores an event against the given Sunshine profile. If the profile does not exist, it will be created. Any additional identifier information provided is added to the profile.

Allowed For
  • Agents
Example Body
{
  "event": {
    "created_at": "2020-01-31T00:44:07+00:00",
    "description": "Order complete",
    "properties": {
      "billing": {
        "address1": "1019 Market St",
        "city": "San Francisco",
        "state": "CA",
        "zipcode": "94103"
      },
      "item": {
        "name": "Zendesk Swag"
      }
    },
    "source": "shoppingnow",
    "type": "checkout"
  },
  "profile": {
    "identifiers": [
      {
        "type": "email",
        "value": "[email protected]"
      }
    ],
    "source": "shoppingnow",
    "type": "customer"
  }
}
Using curl
curl "https://{subdomain}.zendesk.com/api/v2/user_profiles/events" \
  -d {"profile":{"source":"shoppingnow","type":"customer","identifiers":[{"type":"email","value":"[email protected]"}]},"event":{"source":"shoppingnow","type":"checkout","description":"Order complete","created_at":"2020-01-31T00:44:07.000Z","properties":{"item":{"name":"Zendesk Swag"},"billing":{"address1":"1019 Market St","city":"San Francisco","state":"CA","zipcode":"94103"}}}} \
  -H "Content-Type: application/json" \
  -u {email_address}:{password}
Example Response
Status 202

{
  "status": "received"
}

Get events by Sunshine profile ID

GET /api/v2/user_profiles/{profile_id}/events

Returns events for a given Sunshine profile. To retrieve a profile ID, see Get profile by identifier.

Allowed For
  • Agents
Available Parameters
Name Type In Required Description
filter[end_time] string Query false Include events equal to or before the created_at time
filter[source] string Query false Include events of the specified source
filter[start_time] string Query false Include events equal to or later than the created_at time
filter[type] string Query false Include events of the specified type for the given event source. This requires the filter[source] parameter to be included
page[size] string Query false Include the specified number of events
profile_id string Path true Sunshine profile ID
Using curl
curl "https://{subdomain}.zendesk.com/api/v2/user_profiles/{profile_id}/events" \
  -u {email_address}:{password}
Example Response
Status 200

{
  "events": [
    {
      "created_at": "2020-01-31T00:44:07+00:00",
      "description": "Order complete",
      "properties": {
        "billing": {
          "address1": "1019 Market St",
          "city": "San Francisco",
          "state": "CA",
          "zipcode": "94103"
        },
        "item": {
          "name": "Zendesk Swag"
        }
      },
      "source": "shoppingnow",
      "type": "checkout"
    }
  ],
  "links": [
    {
      "next": "https://yoursubdomain.zendesk.com/api/v2/user_profiles/1/events?page[token]=hkjhdjk"
    }
  ]
}

Track event against a Sunshine profile using profile_id

POST /api/v2/user_profiles/{profile_id}/events

Stores an event against the given Sunshine profile. If the profile does not exist, it will be created.

Allowed For
  • Agents
Available Parameters
Name Type In Required Description
profile_id string Path true Sunshine profile ID
Example Body
{
  "event": {
    "created_at": "2020-01-31T00:44:07+00:00",
    "description": "Order complete",
    "properties": {
      "billing": {
        "address1": "1019 Market St",
        "city": "San Francisco",
        "state": "CA",
        "zipcode": "94103"
      },
      "item": {
        "name": "Zendesk Swag"
      }
    },
    "source": "shoppingnow",
    "type": "checkout"
  },
  "profile": {
    "identifiers": [
      {
        "type": "email",
        "value": "[email protected]"
      }
    ],
    "source": "shoppingnow",
    "type": "customer"
  }
}
Using curl
curl "https://{subdomain}.zendesk.com/api/v2/user_profiles/{profile_id}/events" \
  -d {"profile":{"source":"shoppingnow","type":"customer","identifiers":[{"type":"email","value":"[email protected]"}]},"event":{"source":"shoppingnow","type":"checkout","description":"Order complete","created_at":"2020-01-31T00:44:07.000Z","properties":{"item":{"name":"Zendesk Swag"},"billing":{"address1":"1019 Market St","city":"San Francisco","state":"CA","zipcode":"94103"}}}} \
  -H "Content-Type: application/json" \
  -u {email_address}:{password}
Example Response
Status 202

{
  "status": "received"
}

Get Zendesk user events

GET /api/v2/users/{user_id}/events

Returns events for a given Zendesk user.

Allowed For
  • Agents
Available Parameters
Name Type In Required Description
filter[end_time] string Query false Include events equal to or before the created_at time
filter[source] string Query false Include events of the specified source
filter[start_time] string Query false Include events equal to or later than the created_at time
filter[type] string Query false Include events of the specified type for the given event source. The filter[source] parameter must be included
page[size] string Query false Include the specified number of events
user_id string Path true Zendesk user ID
Using curl
curl "https://{subdomain}.zendesk.com/api/v2/users/{user_id}/events" \
  -u {email_address}:{password}
Example Response
Status 200

{
  "events": [
    {
      "created_at": "2020-01-31T00:44:07+00:00",
      "description": "Order complete",
      "properties": {
        "billing": {
          "address1": "1019 Market St",
          "city": "San Francisco",
          "state": "CA",
          "zipcode": "94103"
        },
        "item": {
          "name": "Zendesk Swag"
        }
      },
      "source": "shoppingnow",
      "type": "checkout"
    }
  ],
  "links": [
    {
      "next": "https://yoursubdomain.zendesk.com/api/v2/user_profiles/1/events?page[token]=hkjhdjk"
    }
  ]
}

Track event against Zendesk user and given profile

POST /api/v2/users/{user_id}/events

Stores an event for a given Zendesk user and profile.

Allowed For
  • Agents
Available Parameters
Name Type In Required Description
user_id string Path true Zendesk user ID
Example Body
{
  "event": {
    "created_at": "2020-01-31T00:44:07+00:00",
    "description": "Order complete",
    "properties": {
      "billing": {
        "address1": "1019 Market St",
        "city": "San Francisco",
        "state": "CA",
        "zipcode": "94103"
      },
      "item": {
        "name": "Zendesk Swag"
      }
    },
    "source": "shoppingnow",
    "type": "checkout"
  },
  "profile": {
    "identifiers": [
      {
        "type": "email",
        "value": "[email protected]"
      }
    ],
    "source": "shoppingnow",
    "type": "customer"
  }
}
Using curl
curl "https://{subdomain}.zendesk.com/api/v2/users/{user_id}/events" \
  -d {"profile":{"source":"shoppingnow","type":"customer","identifiers":[{"type":"email","value":"[email protected]"}]},"event":{"source":"shoppingnow","type":"checkout","description":"Order complete","created_at":"2020-01-31T00:44:07.000Z","properties":{"item":{"name":"Zendesk Swag"},"billing":{"address1":"1019 Market St","city":"San Francisco","state":"CA","zipcode":"94103"}}}} \
  -H "Content-Type: application/json" \
  -u {email_address}:{password}
Example Response
Status 202

{
  "status": "received"
}