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.

The Events API is available on the Suite Team plan and above. It is activated in the Admin Center by an admin.

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

Run in Postman

If you use Postman, you can import the Sunshine 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 get started:

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. For more information about using Postman with Zendesk APIs, see Exploring Zendesk APIs with Postman.

JSON format

Events are represented as JSON objects with the following properties:

NameTypeRead-onlyMandatoryDescription
created_atstringfalsefalseISO-8601 compliant date-time reflecting the time the event was created. If not set, the API sets the value when it receives the event
descriptionstringfalsefalseAn event description
idstringtruefalseID of the event
propertiesobjectfalsetrueA custom JSON object with details about the event. Must comply with the JSON Schema specification
received_atstringtruefalseISO-8601 compliant date-time reflecting the time the event was received
sourcestringfalsetrueApplication which sent the event. Note: 'zendesk' is a protected source name for Zendesk standard events. Any attempts to use this source when creating an event results in an error
typestringfalsetrueEvent name

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

NameTypeRequiredDescription
profileobjectyesThe user who triggered the event. For more information, see profile object
eventobjectyesThe 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:

NameTypeRequiredDescription
sourcestringyesThe product or service associated with the profile. For example, "Support", "Salesforce", or "Chat"
typestringyesThe type of profile. For example, "Contact" or "Lead"
identifiersobjectyesOne or more user identities. See the identifiers array

Example

{  "profile": {    "source": "shoppingnow",    "type": "customer",    "identifiers": [      {        "type": "shoppingnow_id",        "value": "361959350832"      },      {       "type": "external_id",       "value": "0987654321"     }    ]  },  "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 Zendesk User Events

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

Returns events for a given Zendesk user.

Allowed For

  • Agents

Parameters

NameTypeInRequiredDescription
filter[end_time]stringQueryfalseInclude events equal to or before the created_at time
filter[source]stringQueryfalseInclude events of the specified source
filter[start_time]stringQueryfalseInclude events equal to or later than the created_at time
filter[type]stringQueryfalseInclude events of the specified type for the given event source. The filter[source] parameter must be included
page[size]stringQueryfalseInclude the specified number of events
user_idstringPathtrueZendesk user ID

Code Samples

curl
curl "https://{subdomain}.zendesk.com/api/v2/users/{user_id}/events" \  -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/users/120077332/events?filter[end_time]=&filter[source]=&filter[start_time]=&filter[type]=&page[size]="	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/users/120077332/events")		.newBuilder()		.addQueryParameter("filter[end_time]", "")		.addQueryParameter("filter[source]", "")		.addQueryParameter("filter[start_time]", "")		.addQueryParameter("filter[type]", "")		.addQueryParameter("page[size]", "");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://support.zendesk.com/api/v2/users/120077332/events',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },  params: {    'filter[end_time]': '',    'filter[source]': '',    'filter[start_time]': '',    'filter[type]': '',    'page[size]': '',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://support.zendesk.com/api/v2/users/120077332/events?filter[end_time]=&filter[source]=&filter[start_time]=&filter[type]=&page[size]="headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/users/120077332/events")uri.query = URI.encode_www_form("filter[end_time]": "", "filter[source]": "", "filter[start_time]": "", "filter[type]": "", "page[size]": "")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
{  "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[after]=hkjhdjk"    }  ],  "meta": {    "after_cursor": "hkjhdjk",    "has_more": true  }}
400 Bad Request
// Status 400 Bad Request
{  "error": {    "message": "You passed an invalid value for the id attribute. Invalid parameter: id must be an integer from api/v2/users/show",    "title": "Invalid attribute"  }}

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 parameter 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

Parameters

NameTypeInRequiredDescription
filter[end_time]stringQueryfalseInclude events equal to or before the created_at time
filter[source]stringQueryfalseInclude events of the specified source
filter[start_time]stringQueryfalseInclude events equal to or later than the created_at time
filter[type]stringQueryfalseInclude events of the specified type for the given event source. The filter[source] parameter must be included
identifierstringQuerytruePass a profile identifier query to filter for a specific profile in the format source:type:identifier_type:identifier_value. For more information, see Identifier queries
page[size]stringQueryfalseInclude the specified number of events

Code Samples

curl
curl "https://{subdomain}.zendesk.com/api/v2/user_profiles/events?identifier={identifier_query}" \  -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/user_profiles/events?filter[end_time]=&filter[source]=&filter[start_time]=&filter[type]=&identifier=shoppingnow%3Acustomer%3Aemail%3Aexample%40example.com&page[size]="	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/user_profiles/events")		.newBuilder()		.addQueryParameter("filter[end_time]", "")		.addQueryParameter("filter[source]", "")		.addQueryParameter("filter[start_time]", "")		.addQueryParameter("filter[type]", "")		.addQueryParameter("identifier", "shoppingnow:customer:email:[email protected]")		.addQueryParameter("page[size]", "");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://support.zendesk.com/api/v2/user_profiles/events',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },  params: {    'filter[end_time]': '',    'filter[source]': '',    'filter[start_time]': '',    'filter[type]': '',    'identifier': 'shoppingnow%3Acustomer%3Aemail%3Aexample%40example.com',    'page[size]': '',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://support.zendesk.com/api/v2/user_profiles/events?filter[end_time]=&filter[source]=&filter[start_time]=&filter[type]=&identifier=shoppingnow%3Acustomer%3Aemail%3Aexample%40example.com&page[size]="headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/user_profiles/events")uri.query = URI.encode_www_form("filter[end_time]": "", "filter[source]": "", "filter[start_time]": "", "filter[type]": "", "identifier": "shoppingnow:customer:email:[email protected]", "page[size]": "")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
{  "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[after]=hkjhdjk"    }  ],  "meta": {    "after_cursor": "hkjhdjk",    "has_more": true  }}
400 Bad Request
// Status 400 Bad Request
{  "errors": [    {      "code": "StartTimestampNotValid",      "id": "c21d8981-8940-419b-907b-7f7a2ba22cca",      "title": "Start Timestamp not valid"    }  ]}
404 Not Found
// Status 404 Not Found
{  "errors": [    {      "code": "StartTimestampNotValid",      "id": "c21d8981-8940-419b-907b-7f7a2ba22cca",      "title": "Start Timestamp not valid"    }  ]}

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

Parameters

NameTypeInRequiredDescription
filter[end_time]stringQueryfalseInclude events equal to or before the created_at time
filter[source]stringQueryfalseInclude events of the specified source
filter[start_time]stringQueryfalseInclude events equal to or later than the created_at time
filter[type]stringQueryfalseInclude events of the specified type for the given event source. This requires the filter[source] parameter to be included
page[size]stringQueryfalseInclude the specified number of events
profile_idstringPathtrueSunshine profile ID

Code Samples

curl
curl "https://{subdomain}.zendesk.com/api/v2/user_profiles/{profile_id}/events" \  -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/user_profiles//events?filter[end_time]=&filter[source]=&filter[start_time]=&filter[type]=&page[size]="	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/user_profiles//events")		.newBuilder()		.addQueryParameter("filter[end_time]", "")		.addQueryParameter("filter[source]", "")		.addQueryParameter("filter[start_time]", "")		.addQueryParameter("filter[type]", "")		.addQueryParameter("page[size]", "");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://support.zendesk.com/api/v2/user_profiles//events',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },  params: {    'filter[end_time]': '',    'filter[source]': '',    'filter[start_time]': '',    'filter[type]': '',    'page[size]': '',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://support.zendesk.com/api/v2/user_profiles//events?filter[end_time]=&filter[source]=&filter[start_time]=&filter[type]=&page[size]="headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/user_profiles//events")uri.query = URI.encode_www_form("filter[end_time]": "", "filter[source]": "", "filter[start_time]": "", "filter[type]": "", "page[size]": "")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
{  "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[after]=hkjhdjk"    }  ],  "meta": {    "after_cursor": "hkjhdjk",    "has_more": true  }}
400 Bad Request
// Status 400 Bad Request
{  "errors": [    {      "code": "StartTimestampNotValid",      "id": "c21d8981-8940-419b-907b-7f7a2ba22cca",      "title": "Start Timestamp not valid"    }  ]}
404 Not Found
// Status 404 Not Found
{  "errors": [    {      "code": "StartTimestampNotValid",      "id": "c21d8981-8940-419b-907b-7f7a2ba22cca",      "title": "Start Timestamp not valid"    }  ]}

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

Access also depends on agent role permissions set in Support > People > Roles > People.

Parameters

NameTypeInRequiredDescription
user_idstringPathtrueZendesk 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]"      },      {        "type": "external_id",        "value": "0987654321"      }    ],    "name": "Jane Smith",    "source": "shoppingnow",    "type": "customer"  }}

Code Samples

curl
curl "https://{subdomain}.zendesk.com/api/v2/users/{user_id}/events" \  -d {"profile":{"name": "Jane Smith", "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}
Go
import (	"fmt"	"io"	"net/http"	"strings")
func main() {	url := "https://support.zendesk.com/api/v2/users/120077332/events"	method := "POST"	payload := strings.NewReader(`{  "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]"      },      {        "type": "external_id",        "value": "0987654321"      }    ],    "name": "Jane Smith",    "source": "shoppingnow",    "type": "customer"  }}`)	req, err := http.NewRequest(method, url, payload)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/users/120077332/events")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""{  \"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\": \"jane@example.com\"      },      {        \"type\": \"external_id\",        \"value\": \"0987654321\"      }    ],    \"name\": \"Jane Smith\",    \"source\": \"shoppingnow\",    \"type\": \"customer\"  }}""");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("POST", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');var data = JSON.stringify({  "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]"      },      {        "type": "external_id",        "value": "0987654321"      }    ],    "name": "Jane Smith",    "source": "shoppingnow",    "type": "customer"  }});
var config = {  method: 'POST',  url: 'https://support.zendesk.com/api/v2/users/120077332/events',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },  data : data,};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsimport json
url = "https://support.zendesk.com/api/v2/users/120077332/events"
payload = json.loads("""{  "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]"      },      {        "type": "external_id",        "value": "0987654321"      }    ],    "name": "Jane Smith",    "source": "shoppingnow",    "type": "customer"  }}""")headers = {	"Content-Type": "application/json",}
response = requests.request(	"POST",	url,	auth=('<username>', '<password>'),	headers=headers,	json=payload)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/users/120077332/events")request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")request.body = %q({  "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]"      },      {        "type": "external_id",        "value": "0987654321"      }    ],    "name": "Jane Smith",    "source": "shoppingnow",    "type": "customer"  }})request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

202 Accepted
// Status 202 Accepted
{  "profile_id": "01E1DPYAA7HW7645KMJEY9CXRJ"