Getting started with events

You can use Events API to track events triggered by a person in different applications or systems. Events can be any programmatic event, including purchase transactions, website visits, or customer service interactions.

Each event is associated with a profile that identifies the person who triggered the event. Each profile is associated with a Zendesk user. As a result, each event is also associated with a Zendesk user.

Event ↔ Profile ↔ Zendesk user

Disclaimer: Zendesk provides this article for instructional purposes only. Zendesk does not support or guarantee the code. Zendesk also can't provide support for third-party technologies such as curl.

Requirements

Get a Zendesk Support account on a Zendesk Suite plan. It is automatically enabled to use the API.

You can sign up for a 14-day trial account. If you're interested in becoming a Zendesk developer partner, you can convert your trial account into a sponsored Zendesk Support account

You'll also need agent or admin permissions in the account to use the API.

User story

You work for a fictional company named Acme. Your team is tasked with building an event service for Acme. You get the following story:

As an Acme success manager, I'd like to see the actions the customer took in the Acme application before I contact the customer.

Acme has a Zendesk account. Instead of provisioning a new database and building something from scratch, you decide to use the Events API included in Zendesk to store and access Acme customer events.

Create an event

You create an event by posting information about the event and the person who triggered it to the following API endpoint:

POST /api/v2/user_profiles/events

The API expects a profile with each event. The profile's role is to associate the person in the Acme system with the user in Zendesk.

Because the events originate in the Acme system, you'll associate each event with an Acme identifier for the customer, such as an email address. If the API finds a user in Zendesk who shares an identifier listed in the profile's identifiers array, it automatically associates the new profile -- and therefore the event -- with that user. If the API can't find a Zendesk user who shares any of the identifiers, it creates an anonymous Zendesk user named "sunshine_user" and associates the profile with the user.

You don't need to directly associate the event with a Zendesk user, though you could with the following request:

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

Try it yourself

To create an event

1. Get the event from your application.

   The Acme application returns the following event data:

   • "event_name": "2fa_enabled"
   • "event_desc": "Customer enabled 2-factor authentication"
   • "passcode_pref": "SMS"

2. Query your user management system to get an identifier for the person who triggered the event.

   The system returns the following identifier for the person:

   • "email": "[email protected]"

3. Insert the event and identifier data in a JSON object that has the following format:

   {
      "profile": {
        "source": "acme",
        "type": "customer",
        "identifiers": [
          {
            "type": "email",
            "value": "[email protected]"
          }
        ]
      },
      "event": {
        "source": "acme",
        "type": "2fa_enabled",
        "description": "Customer enabled 2-factor authentication",
        "properties": {
          "passcode_preference": "SMS"
        }
      }
    }

   See Anatomy of a profile and Anatomy of a event for descriptions of the profile and event objects.

   The API doesn't accept numeric values. All numbers must be strings. Example: "16505556789".

4. Save the JSON object in a file named event.json.

5. In your command-line interface, navigate to the folder containing event.json.

6. Run the following curl command in your command-line interface:

   curl https://{subdomain}.zendesk.com/api/v2/user_profiles/events \
      -d @event.json \
      -H "Content-Type: application/json" \
      -v -u {email_address}:{password} -X POST

   Make sure to replace the placeholder values with your own.

   Windows users: Replace the line-continuation backslashes (\) in this and the other examples with caret (\^) characters.

   Example response

   {"status": "received"}

Get the event

After creating one or more events associated with the customer, you can access the events with the customer's email identifier in the Acme system, which you recorded in their profile. You could also access the events with the customer's Zendesk user id if you know it or with the id of the user's profile.

You decide to get the events with the customer's Acme identifier (since you already know it and you recorded it in a profile) using the following endpoint:

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

You look up a customer's profile with an identifier query. See Using identifier queries with profiles. The customer's identifier in Acme's system recorded in the profile is the email address [email protected]. Therefore, your identifier query should be as follows:

acme:customer:email:[email protected]

Each identifier query must include the following information:

• a profile source ("acme")
• a profile type ("customer")
• an identifier type ("email")
• an identifier value ("[email protected]")

Try it yourself

To get an event

• Run the following curl command in your command-line interface:

  curl "https://{subdomain}.zendesk.com/api/v2/user_profiles/events?identifier=acme:customer:email:[email protected]" \
      -v -u {email_address}:{password}

  Make sure to replace the placeholder values with your own. Also make sure to enclose the URL in quotes.

  Example response

  Status: 200 OK
  
   {
      "events": [
        {
          "id": "5c42123e98326c0001b0b25c",
          "type": "2fa_enabled",
          "source": "acme",
          "description": "Customer enabled 2-factor authentication",
          "created_at": "2020-03-30T04:37:34.851Z",
          "received_at": "2019-03-30T04:37:34.851Z",
          "properties": {
            "passcode_preference": "SMS"
          }
        }
      ],
      "links": [
        {
          "next":""
        }
      ]
    }

Next steps

You tracked an event triggered by a customer in Acme and then used the customer's identifier in Acme to retrieve it.

Keep experimenting with the API. Create different types of events for different users. Build a small application that uses the event data to deliver some value to the customer.

If you're building a Zendesk app, you can get the events associated with a user object such as a ticket requester. See Accessing events in Zendesk apps.

For a developer guide, see the Events API developer guide.

For the reference docs, see Events API.