Custom Object Record Events

The Custom Object Record Events API lets you retrieve a log of activities that occurred on a custom object record, such as record creation and field updates.

Each event is associated with the custom object record on which the action was performed. Events include information about the actor who triggered the change. Actors can be human users (admins, agents, or end users) or system actors (object triggers).

Permissions

The user submitting a Custom Object Record Events API request must have permission to view the custom object record referenced in the request. Permission checks are performed against the custom object record's permissions.

Event Retention

Custom object record events are retained for the lifetime of the record. There is no time-based expiration for these events.

Events are automatically deleted in the following scenarios:

• When a custom object record is deleted, all events for that record are deleted.
• When a custom object type is deleted, all records of that type and their events are deleted.

JSON format

Custom Object Record Events are represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
actor	object	false	true	The user or system that triggered the event
created_at	string	false	true	When the event was created (ISO-8601 format)
description	string	false	false	A description of the event
id	string	false	true	Unique identifier for the event
properties	object	false	true	Event properties containing transaction details
received_at	string	false	true	When the event was received (ISO-8601 format)
source	string	false	true	The source of the event (always 'zendesk' for standard events)
type	string	false	true	The event type: record_created or record_updated

An event associated with a custom object record

A custom object record event describes an event for a custom object record.

Name	Type	Read-only	Description
id	string	yes	Unique identifier for the event
type	string	yes	The event type: record_created or record_updated
source	string	yes	The source of the event (always zendesk for standard events)
description	string	yes	A description of the event
actor	object	yes	The user who triggered the event. See actor object
created_at	string	yes	When the event was created (ISO-8601 format)
received_at	string	yes	When the event was received (ISO-8601 format)
properties	object	yes	Event properties containing transaction details. See properties object

Actor object

The actor object identifies who triggered the event.

Name	Type	Description
user_id	integer	The id of the user who triggered the event

Properties object

The properties object contains details about what changed.

Name	Type	Description
transaction_events	array	List of field changes in this transaction. See transaction event object

Transaction event object

Each transaction event represents a single field change.

Name	Type	Description
type	string	The type of change: name_changed, custom_field_changed, or external_id_changed
originated_from	object	The source of the change. See originated from object
key	string	The field key (only for custom_field_changed events)
previous	string	The previous value
current	string	The new value

Originated from object

Indicates how the change was made.

Name	Type	Description
from_ui	object	Present if the change was made via the UI. Contains ip_address
from_trigger	object	Present if the change was made by an object trigger. Contains trigger_id and revision_id
from_api	object	Present if the change was made via API. Contains token_id

Example

{
  "events": [
    {
      "id": "01HR91W56R71K30CHJCSJKGDSJ",
      "type": "record_updated",
      "source": "zendesk",
      "description": "",
      "actor": {
        "user_id": 4398147187967
      },
      "created_at": "2024-03-06T04:55:45.112Z",
      "received_at": "2024-03-06T04:55:45.247971922Z",
      "properties": {
        "transactional_events": [
          {
            "type": "name_changed",
            "originated_from": {
              "from_ui": {
                "ip_address": "157.211.239.177"
              }
            },
            "previous": "My bike",
            "current": "My red bike"
          },
          {
            "type": "custom_field_changed",
            "originated_from": {
              "from_trigger": {
                "trigger_id": "12943479832840",
                "revision_id": "7"
              }
            },
            "key": "color",
            "previous": "blue",
            "current": "red"
          }
        ]
      }
    }
  ],
  "links": [
    {
      "next": ""
    }
  ],
  "meta": {
    "has_more": false
  }
}

List Events for Custom Object Record

• GET /api/v2/custom_objects/{custom_object_key}/records/{custom_object_record_id}/events

Returns events for a custom object record. Events capture changes to record fields.

Allowed For

• Agents with read access to the custom object record

Parameters

Name	Type	In	Required	Description
page[after]	string	Query	false	Cursor for pagination. Use the value from links.next in the response.
page[size]	integer	Query	false	Number of events to return per page
custom_object_key	string	Path	true	The key of the custom object
custom_object_record_id	string	Path	true	The id of the custom object record

Code Samples

curl

curl "https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/{custom_object_record_id}/events" \
  -u {email_address}/token:{api_token}

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://support.zendesk.com/api/v2/custom_objects/car/records/01HSJY76BDNQGG6Y6XVHZA2HP4/events?page[after]=&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 "{email_address}/token:{api_token}"

	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/custom_objects/car/records/01HSJY76BDNQGG6Y6XVHZA2HP4/events")
		.newBuilder()
		.addQueryParameter("page[after]", "")
		.addQueryParameter("page[size]", "");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://support.zendesk.com/api/v2/custom_objects/car/records/01HSJY76BDNQGG6Y6XVHZA2HP4/events',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
  params: {
    'page[after]': '',
    'page[size]': '',
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests
from requests.auth import HTTPBasicAuth

url = "https://support.zendesk.com/api/v2/custom_objects/car/records/01HSJY76BDNQGG6Y6XVHZA2HP4/events?page[after]=&page[size]="
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"GET",
	url,
	auth=auth,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://support.zendesk.com/api/v2/custom_objects/car/records/01HSJY76BDNQGG6Y6XVHZA2HP4/events")
uri.query = URI.encode_www_form("page[after]": "", "page[size]": "")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
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": [
    {
      "actor": {
        "user_id": 4398147187967
      },
      "created_at": "2024-03-06T04:55:45.112Z",
      "description": "",
      "id": "01HR91W56R71K30CHJCSJKGDSJ",
      "properties": {
        "transactional_events": [
          {
            "current": "My red bike",
            "originated_from": {
              "from_ui": {
                "ip_address": "157.211.239.177"
              }
            },
            "previous": "My bike",
            "type": "name_changed"
          },
          {
            "current": "red",
            "key": "color",
            "originated_from": {
              "from_trigger": {
                "revision_id": "7",
                "trigger_id": "12943479832840"
              }
            },
            "previous": "blue",
            "type": "custom_field_changed"
          }
        ]
      },
      "received_at": "2024-03-06T04:55:45.247971922Z",
      "source": "zendesk",
      "type": "record_updated"
    }
  ],
  "links": [
    {
      "next": ""
    }
  ],
  "meta": {
    "has_more": false
  }
}

403 Forbidden

// Status 403 Forbidden

{
  "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"
    }
  ]
}