The Zendesk Sunshine platform lets you connect and understand all your customer data wherever it lives. The Sunshine platform currently consists of the following APIs:
The Events and Profiles API (which also includes the People API) is in early access. The API can be enabled by an admin in your account. In Admin Center, go to Sunshine > Settings (https://your_subdomain.zendesk.com/admin/sunshine/settings), select the Events and Profiles API, and click Save.
The Sunshine API is available on the Sunshine Enterprise and Sunshine Select plans.
The Sunshine Select plan is included with the Support Elite plan. Support Enterprise and Suite Enterprise customers can upgrade to the Sunshine Select plan.
Sunshine Select provides increased data storage. See Storage limits.
This is the API reference documentation for Sunshine.
In addition to this API reference, the following resources are available in the Develop Help Center:
For common questions, see the Sunshine questions in the developer FAQ
For tutorials, articles, and other information, see Using the Sunshine APIs
To ask questions, provide answers, and join discussions, see the developer community
The API path for Sunshine is /api/sunshine/. Example:
The endpoint paths were updated in March 2019 to use new /api/sunshine/ paths. The previous endpoint paths will redirect to the new paths until further notice. For a mapping of the old and new endpoint paths, see Custom Objects API path renaming.
Authentication works as described in the Security and Authentication in the Zendesk v2 API documentation.
Custom Objects API
Pagination works as described in Pagination in the Zendesk v2 API documentation, except for the following differences:
sort_orderparameter is called
order=in the Custom Objects API
per_pageparameter 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.
Events and Profiles APIs
The Events and Profiles 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.
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"
The API uses the following standard response codes.
- "200 - Ok"
- "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)
- "204 - No Content"
- "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.
The Events and Profiles APIs, which are in early access, let 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/sunshine/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 and Profiles API paths accept idempotency keys:
The Custom Objects API doesn't support idempotency keys.
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 rate limits outlined in this section apply to custom objects. The limits for events and profiles, which are in early access, have not been determined yet.
The rate limit for custom objects is 1,000 requests per minute. This includes requests made from the Zendesk Apps framework.
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. The response has a "Retry-After" header that tells you for how many seconds to wait before retrying.
Events (early access)
The rate limit is not finalized. We're looking at feedback and sample volumes during the early access program to help set the final rate limit.
Profiles (early access)
The rate limit is not finalized.
The maximum number of records you can store depends on your Sunshine plan:
|Sunshine Enterprise||Sunshine Select|
See Plan availability.
The storage limits for the Events and Profiles APIs, which are in early access, are not finalized.
This product includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com.