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_token
response = 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_token
response = 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_token
response = 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"
}