Custom Data
The Zendesk custom data APIs lets you connect and understand all your customer data wherever it lives. It consists of the Legacy Custom Objects API, Profiles API, and Events API.
Plan availability
The Legacy 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
- What are the custom data APIs?
- Getting started with legacy custom objects
- Getting started with profiles
- Getting started with events
Guides and tutorials
Community
Examples
For information on the curl examples used in the APIs, see Examples.
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 Legacy 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.
Category | Limit |
---|---|
Profiles | 30,000,000 |
Profile sources | 50 |
Profile types | 2500 |
Identifiers per profile | 20 |
Profile source character length | 40 |
Profile type character length | 40 |
Identifier source character length | 60 |
Identifier type character length | 60 |
Events
The following table shows events hard limits. Availability and limits can vary according to Zendesk Suite plan type.
Category | Limit |
---|---|
Event sources | 50 |
Event types | 2500 |
Event source character length | 40 |
Event type character length | 40 |
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 paths accept idempotency keys:
POST /api/v2/user_profiles/events
POST /api/v2/users/{user_id}/events
POST /api/v2/user_profiles/{profile_id}/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 Legacy 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 calledorder=
in the Legacy Custom Objects API - The
per_page
parameter in the Legacy 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 Lite | Sunshine Team | Sunshine Professional | Sunshine Enterprise |
---|---|---|---|
250 requests per minute | 500 requests per minute | 700 requests per minute | 1,000 requests per minute |
Legacy 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 Lite | Sunshine Team | Sunshine Professional | Sunshine Enterprise | |
---|---|---|---|---|
Object types* | 50 | 50 | 50 | 50 |
Object size | 32 KB | 32 KB | 32 KB | 32 KB |
Object records | 100,000 | 250,000 | 1,000,000 | 25,000,000 |
Relationship types* | 50 | 50 | 50 | 50 |
Relationship records | 100,000 | 250,000 | 1,000,000 | 25,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 legacy custom objects storage limits on the Zendesk Suite plans, see Zendesk Suite plan limits.
Legal notices
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.