Sunshine
The Zendesk Sunshine platform lets you connect and understand all your customer data wherever it lives. The Sunshine platform consists of the Custom Objects API, Profiles API, and Events APIs.
Plan availability
The Custom Objects API, Profiles API, and Events API are available on the Support Enterprise and Support Suite Enterprise plans with a Sunshine plan.
For information about data storage on Sunshine plans, see Storage limits.
Documentation
This is the API reference documentation for Sunshine. It covers the following APIs:
In addition to the API docs, the following resources are available in the Develop Help Center.
Getting started
- What is the Sunshine API?
- Getting started with Sunshine custom objects
- Getting started with Sunshine profiles
- Getting started with Sunshine user events
Guides and tutorials
Community
Authentication
Authentication works as described in the Security and Authentication in the Zendesk v2 API documentation.
The Sunshine Profiles and Events APIs support standard OAuth scopes. You should treat profile and event resources as part of the user resource. That is, users:read
and users:write
scopes will apply. For more information, see Using OAuth authentication with your application.
Pagination
Custom Objects API
Pagination works as described in Pagination in the Zendesk v2 API documentation, except for the following differences:
- the
sort_order
parameter is calledorder=
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 have "next_page" and "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.
Content type
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"
Response codes
The API uses the following standard response codes.
GET requests
- "200 - Ok"
POST requests
- "201 - Created"
- "400 - Bad Request" (the request could not be understood)
- "413 - Request Entity Too Large" (for jobs endpoints, the JSON array of data to process had too many elements)
- "422 - Unprocessable Entity" (the request could be understood, but was invalid for some reason)
DELETE requests
- "204 - No Content"
PATCH requests
- "200 - Ok"
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 the Rate Limits section.
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.
Rate limits
The API enforces rate limiting on standard create endpoints. The rate limits for each plan type are shown in the following table. Limits include requests made from the Zendesk Apps framework.
Sunshine Lite | Sunshine Professional | Sunshine Enterprise | |
---|---|---|---|
Custom objects | 500 requests per minute | 700 requests per minute | 1,000 requests per minute |
Profiles | Not included | 250 requests per minute | 500 requests per minute |
Events | Not included | 250 requests per minute | 500 requests per minute |
If you exceed the rate limit, the API responds with a HTTP 429 Too Many Requests response code and a body that details the reason for the rate limiter kicking in. To avoid hitting the rate limit, each standard response includes headers that indicate the number of requests remaining before rate limiting. X-Rate-Limit
indicates the limit value being enforced for the account. X-Rate-Limit-Remaining
indicates the number of requests remaining in the rate limiting interval.
When an application exceeds the rate limit, the API returns a HTTP 429 "Too Many Requests" response code. Additionally, an X-Retry-After
header is included in the response to indicate the earliest time that requests will be allowed again.
To list the limits for your account, see Custom Objects Limits.
Storage limits
Custom objects
The following table shows storage limits by Sunshine plan type.
Sunshine Lite | Sunshine Professional | Sunshine Enterprise | |
---|---|---|---|
Object types* | 50 | 50 | 50 |
Object size | 32 KB | 32 KB | 32 KB |
Object records | 100,000 | 1,000,000 | 25,000,000 |
Relationship types* | 50 | 50 | 50 |
Relationship records | 100,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 more information about Sunshine plans, see Plan availability.
Profiles
The following table shows profiles hard limits. Availability and limits can vary according to Sunshine 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 Sunshine plan type.
Category | Limit |
---|---|
Event sources | 50 |
Event types | 2500 |
Event source character length | 40 |
Event type character length | 40 |
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.