Events and Profiles API

This API is in early access. Sign up to the User Events API early access program to use it.

The Events and Profiles API consists of events, profiles, and people.

Events let you build a timeline of all your customers' interactions from any source. Events can be any programmatic event, including purchase transactions, website visits, or customer service interactions. Each event is associated with a customer who triggered the event.

Profiles let you create a single view of a customer across applications and systems. A profile can contain the various identities of a user in different applications and systems.

People are the customers who have profiles created with either the Profiles or the Events APIs. The API defines each customer as a person with one or more profiles.

The Events and Profiles API is available on the Enterprise plan for Zendesk Support. If you're interested in becoming a Zendesk developer partner, you can convert a trial account into a sponsored Zendesk Support account. The sponsored account is on the Enterprise plan with up to 5 agents. See Getting a trial or sponsored account for development in the Develop Help Center.

Documentation

This is the reference documentation for the Events and Profiles API.

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

API path

The Events and Profiles API has the following path:

https://{subdomain}.zendesk.com/api/sunshine/

where {subdomain} is the subdomain of your Zendesk Support account.

Authentication

Authentication works as described in the Security and Authentication in the Zendesk v2 API documentation.

Pagination

We use a cursor based pagination. You will receive a pagination token for the next page. You are able to specify things such as ?items to specify the window size.

Content type

The Events and Profiles API is a JSON API.

  • POST requests require a "Content-Type: application/json" header

  • GET requests require a "Accept: application/json" header

Idempotency

The API allows an idempotency key to be specified which will allow retrying of api calls without the risk of creating duplicates. For example, if a call to the POST /api/sunshine/events endpoint is made when a button is pressed, the idempotency key can be used to prevent duplicate events from being created on secondary button clicks.

To specify an idempotency key to be used with a request, provide the header X-Idempotency-Key: <key_value> with your request. The key can be any string with a length less than or equal to 48.

Idempotency keys are accepted for the following api paths:

POST /api/sunshine/track POST /api/sunshine/events POST /api/sunshine/profiles

When a request is received with an idempotency key, the request proceeds as normal if the key has not been seen before. If the key has been used before, the server responds with a 409 status code.

Keys expire after 4 hours, so if a request with a duplicate key is sent after 4 hours from the original request, the request will be allowed to proceed.

Rate limits

The rate limit is not finalized. We're looking at feedback and sample volumes during the EAP to help set the final rate limit.

Legal notices

Your use and access to the API is expressly conditioned on your compliance with the policies, restrictions, and other provisions related to the API set forth in our API Restrictions and Responsibilities, in our Change Policy, and in the other documentation we provide you. You must also comply with the restrictions set forth in the Zendesk Master Subscription Agreement and the Zendesk Privacy Policy, in all uses of the API. If Zendesk believes that you have or attempted to violate any term, condition, or the spirit of these policies or agreements, your right to access and use the API may be temporarily or permanently revoked.

This product includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com