Custom Objects API

You can use the Custom Objects API to create, read, update, and delete objects that you define yourself. You can also use it to define and manage relationships with other objects, including native Zendesk objects like tickets and users.

The Custom Objects API is available on the Enterprise plan of Zendesk Support.

Run in Postman

If you use Postman, you can import the Custom Objects 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.

Documentation

This is the reference documentation for the Custom Objects API.

In addition to this API reference, the following resources are available in the Develop Help Center:

Enabling custom objects

Custom objects are available on the Enterprise plan. If you're interested in becoming a Zendesk developer partner, you can convert a trial account into a sponsored Zendesk Support account. The sponsored account is on the Enterprise plan with up to 5 agents. See Getting a trial or sponsored account for development in the Develop Help Center.

Custom objects must be enabled by an administrator in Zendesk Support. If you're not a Support admin, ask one to enable them for you.

To enable custom objects in your account

  1. In Zendesk Support, click the Admin icon () in the sidebar, then select Manage > Custom Objects.

    The Custom Objects page opens in Admin Center.

  2. Click the Activate Custom Objects button.

API path

The Custom Objects API introduces a more modern API design. Unlike Zendesk v2 APIs, the path doesn't have a version number and the resource doesn't have a .json extension. Example:

https://{subdomain}.zendesk.com/api/custom_resources/resources

The path will be updated in the future to reflect the recent API name change. Zendesk will ensure the old path redirects to the new one.

Zendesk v2 APIs are unaffected by the redesign.

Authentication

Authentication works as described in the Security and Authentication in the Zendesk v2 API documentation.

Pagination

Pagination works as described in Pagination in the Zendesk v2 API documentation, 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 have "next_page" and "previous_page" properties. Instead, it has a "link" property at the top level with "next" and "previous" child properties.

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)
  • "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 next section.

Rate limits

The rate limit 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.

Storage limits:

Records
Object types 50
Object records 1,000,000
Relationship types 50
Relationship records 1,000,000

You can create up to 10,000 object records and 10,000 relationship records per 24 hours:

POST requests per 24 hrs
Object records 10,000
Relationship records 10,000

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.