Introduction

The Zendesk custom data APIs lets you connect and understand all your customer data wherever it lives. It consists of the Custom Objects API, Profiles API, and Events API.

Plan availability

The Custom Objects API, Profiles API, and Events API are available on the Zendesk Suite Team plan and above.

Documentation

This is the API reference documentation for custom data. It covers the following APIs:

In addition to the API docs, the following resources are available in the Develop Help Center.

Getting started

Guides and tutorials

Community

Examples

For information on the curl examples used in the APIs, see Examples.

Events API

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.

Security and authentication

The Profiles and Events APIs support standard OAuth scopes. Profile and event resources are part of the user resource. For example, the users:read scope grants read access to all profile and event resources. For more information, see Using OAuth authentication with your application and Security and authentication.

Rate limits

The API enforces rate limiting on standard create endpoints. For information about limits on the Zendesk Suite plans, see Zendesk Suite plan limits. Rate limits include requests made from the Zendesk Apps framework.

To list the limits for your account, see Custom Objects Limits.

For general information on the number of requests allowed per minute, see Rate limits.

Profiles

The following table shows profiles hard limits. Availability and limits can vary according to the Zendesk Suite plan type.

CategoryLimit
Profiles30,000,000
Profile sources50
Profile types2500
Identifiers per profile20
Profile source character length40
Profile type character length40
Identifier source character length60
Identifier type character length60

Events

The following table shows events hard limits. Availability and limits can vary according to Zendesk Suite plan type.

CategoryLimit
Event sources50
Event types2500
Event source character length40
Event type character length40

Request format

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

  • All PATCH requests require a "Content-Type: application/merge-patch+json" header

  • All GET requests should return "Content-Type: application/json"

For information on the JSON request format, see Request format.

Response format

The API uses the standard response codes described in Response format.

In addition, a "404 - Not Found" can be returned from any endpoint that takes a URL parameter that does not exist, or any incorrect URL. A "500 - Internal Server Error" can be returned at any time from any endpoint in case of failures in the service. Any endpoint can also return "429 - Too Many Requests" as documented in Rate limits.

Idempotency

The Events API lets you specify an idempotency key that allows the user to retry an API request without the risk of creating duplicate records. For example, if a button click in your app triggers a request to the POST /api/v2/user_profiles/events endpoint, you can use the idempotency key to prevent subsequent clicks from creating duplicate event records.

To specify an idempotency key 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.

The following Events API path accepts idempotency keys:

  • POST /api/v2/user_profiles/events

When a request is received with an idempotency key, the request proceeds normally 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.

The Custom Objects API and the Profiles API don't support idempotency keys.

Pagination

Pagination works as described in Pagination, except for the following differences:

  • The sort_order parameter is called order= in the Custom Objects API
  • The per_page parameter in the Custom Objects API can take up to 1,000 records rather than 100 records per page on most endpoints in the Zendesk v2 API

The response body is also different. The response object doesn't contain the next\_page or previous\_page properties. Instead, it has a link property at the top level with next and previous child properties.

Profiles and Events APIs

The Profiles and Events APIs use cursor-based pagination. You receive a pagination token for the next page. You can specify things such as ?items to specify the window size.

Data types

For information on data types returned by the APIs, see Data types.

Legacy plan limits

The rate limits by legacy Sunshine plan type are shown in the following table.

Sunshine LiteSunshine TeamSunshine ProfessionalSunshine Enterprise
250 requests per minute500 requests per minute700 requests per minute1,000 requests per minute

Custom objects storage limits

The following table shows storage limits by legacy Sunshine plan type. For more information, see About the Zendesk Sunshine plan types.

Sunshine LiteSunshine TeamSunshine ProfessionalSunshine Enterprise
Object types*50505050
Object size32 KB32 KB32 KB32 KB
Object records100,000250,0001,000,00025,000,000
Relationship types*50505050
Relationship records100,000250,0001,000,00025,000,000

*Type limits are a soft limit. To find out more about increasing this limit, reach out to your sales rep. For information about custom objects storage limits on the Zendesk Suite plans, see Zendesk Suite plan limits.

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

For information on legal compliance using the APIs, see Legal notice.