DocumentationAPI Reference

Tracking events

You can store event data in Zendesk using the Events API. Events can be any programmatic event in an application or system. You must be able to listen for and handle the events, either directly or through an API, as well as identify a person associated with each event.

Events are created synchronously. You'll get a response with a "202" status if an event is created successfully.

This article includes curl and Python examples. The Python examples use Python 3.6 or greater and the requests library.

How events work with profiles

Each event is associated with a profile, which is in turn associated with a Zendesk user.

Event ↔ Profile ↔ Zendesk user

Because each profile is associated with a Zendesk user, each event is associated with a Zendesk user.

A profile identifies the person responsible for the event in the application or system.

As a result, creating an event requires both an event object and a profile object:

{  "event": {...},  "profile": {...}}

Example event object:

"event": {  "source": "acme",  "type": "2fa_enabled",  "description": "Customer enabled 2-factor authentication",  "properties": {      "passcode_preference": "SMS"  }}

See Anatomy of an event for more information.

A profile must contain at minimum the following properties:

  • the source application or system
  • a user-defined name for the profile's type, such as "customer" or "rider"
  • at least one identifier that uniquely identifies the person in the application or system

You can include other profile properties but they're not required. See Anatomy of a profile for more information.

Example profile object:

"profile": {    "source": "coolbikes",    "type": "rider",    "identifiers": [      {        "type": "email",        "value": "[email protected]"      }    ]  }

Each profile is associated with a Zendesk user. See How profiles are associated with Zendesk users. You don't need to specify the Zendesk user id of the person in the profile. The system automatically matches profiles and their associated events to existing Zendesk users based on the profile identifiers. If the systen can't find a match, it creates both a profile and an anonymous Zendesk user named "sunshine_user", and associates the profile and its associated events with the new user.

The system does not replace an existing profile with the new profile if a profile is found with an identical combination of source, type, and identifier. However, it may add additional information to the profile and the Zendesk user record. See How profiles affect existing data.

Tracking events

Use the following endpoint to track events:

POST /api/v2/user_profiles/events

The request body takes both an event object and a profile object. See How events work with profiles.

The event object must specify a source, a type, and a properties object.

The profile object must specify a profile source, type, and at least one identifier.

The profile and the event sources are normally the same if they originate in the same system.

For the reference docs, see Track Event Against User Profile.

Example

Data

Request body in event.json file:

{  "event": {    "source": "coolbikes",    "type": "bike_rental_booked",    "description": "A CoolBike rental has been booked",    "properties": {      "booking_date": "2020-02-01",      "return_date": "2020-02-05"    }  },  "profile": {    "source": "coolbikes",    "type": "rider",    "identifiers": [      {        "type": "email",        "value": "[email protected]"      }    ]  }}

curl request

curl https://coolbikes.zendesk.com/api/v2/user_profiles/events \  -d @event.json \  -H "Content-Type: application/json" \  -v -u devs@coolbikes.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv -X POST

Python request

import json
import requests
with open('event.json', mode='r') as f:    event = json.load(f)
url = 'https://coolbikes.zendesk.com/api/v2/user_profiles/events'api_token = '6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv'headers = {'Content-Type': 'application/json'}credentials = '[email protected]/token', api_tokenresponse = requests.post(url, json=event, auth=credentials, headers=headers)if response.status_code != 202:    print(f'{response.status_code}: {response.text}')else:    print(response.json())

Response

Status 202 Accepted
{  "status":"received",  "user_id":"81123613",  "profile_id":"01E1G0NJSQPNPZRV096JXKXFAA"}

Tracking events by profile

If you know the profile id of the person associated with the event, you can associate a new event directly with the profile using the following request:

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

Because the profile is specified in the path, the request body takes only an event object.

For the reference docs, see Track event against user profile using profile_id.

Example

Data

  • Profile id:

    "01E1G0NJSQPNPZRV096JXKXFAA"

  • Request body in event.json file:

    {    "event": {      "source": "coolbikes",      "type": "bike_rental_booked",      "description": "A CoolBike rental has been booked",      "properties": {        "booking_date": "2020-02-01",        "return_date": "2020-02-05"      }    }  }

curl request

curl https://coolplanes.zendesk.com/api/v2/user_profiles/01E1G0NJSQPNPZRV096JXKXFAA/events \  -d @event.json \  -H "Content-Type: application/json" \  -v -u devs@coolplanes.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv -X POST

Python request

import json
import requests

profile_id = '01E1G0NJSQPNPZRV096JXKXFAA'with open('event.json', mode='r') as f:    event = json.load(f)
url = f'https://coolbikes.zendesk.com/api/v2/user_profiles/{profile_id}/events'api_token = '6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv'headers = {'Content-Type': 'application/json'}credentials = '[email protected]/token', api_tokenresponse = requests.post(url, json=event, auth=credentials, headers=headers)if response.status_code != 202:    print(f'{response.status_code}: {response.text}')else:    print(response.json())

Response

Status 202 Accepted
{  "status":"received",  "user_id":"85211553",  "profile_id":"01E24EK9488JWPF55Z6CYDECJ2"}

Tracking events by Zendesk user

If you know the Zendesk user id of the person associated with the event, you can associate a new event directly with the user with the following request:

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

The request body takes both an event object and a profile object. See How events work with profiles.

The event object must specify a source, a type, and a properties object.

The profile object must specify a profile source, type, and at least one identifier.

A collision with an existing Zendesk user is possible with this request. The request will return an error if it occurs. See Making requests with Zendesk user ids in "How profiles affect existing data".

For the reference docs, see Track event against Zendesk user and given profile.

Example

Data

  • User id:

    "85211553"

  • Request body in event.json file:

    {    "event": {      "source": "coolbikes",      "type": "bike_rental_booked",      "description": "A CoolBike rental has been booked",      "properties": {        "booking_date": "2020-02-01",        "return_date": "2020-02-05"      }    },    "profile": {      "source": "coolbikes",      "type": "rider",      "identifiers": [        {          "type": "email",          "value": "[email protected]"        }      ]    }  }

curl request

curl https://coolbikes.zendesk.com/api/v2/users/85211553/events \  -d @event.json \  -H "Content-Type: application/json" \  -v -u devs@coolbikes.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv -X POST

Python request

import json
import requests

user_id = '85211553'with open('event.json', mode='r') as f:    event = json.load(f)
url = f'https://coolbikes.zendesk.com/api/v2/users/{user_id}/events'api_token = '6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv'headers = {'Content-Type': 'application/json'}credentials = '[email protected]/token', api_tokenresponse = requests.post(url, json=event, auth=credentials, headers=headers)if response.status_code != 202:    print(f'{response.status_code}: {response.text}')else:    print(response.json())

Response

Status 202 Accepted
{  "status":"received",  "user_id":"81123613",  "profile_id":"01E1G0NJSQPNPZRV096JXKXFAA"}