Legacy Custom Objects Search

You can use the Search Legacy Object Records endpoint to filter custom object records by attribute, object type, time created at, and time updated at.

For a quick start guide, see Searching Sunshine object records.

JSON format

Search are represented as JSON objects with the following properties:

NameTypeRead-onlyMandatoryDescription
dataarrayfalsefalseLegacy object records that match the query parameters
linksobjectfalsefalseThe url of the next and previous page of results. See Pagination

Example

{  "data": [    {      "attributes": {        "author": "Sidney Sheldon",        "book_available": true,        "book_price": 542,        "name": "The Doomsday Conspiracy",        "publisher": "Bloomsbury publications"      },      "created_at": "2019-09-04T22:00:10.191Z",      "external_id": null,      "id": "5d13764c-cf5f-11e9-aa86-2f9bb45ad15c",      "type": "book",      "updated_at": "2019-09-04T22:00:10.191Z"    }  ],  "links": {    "next": "/api/sunshine/objects/query?per_page=10&cursor=MjAyMC0wNi0wOVQyMjowMjoyNC45MjFa",    "previous": null  }}

Search Legacy Object Records

  • POST /api/sunshine/objects/query

Returns object records that match the query parameters.

A search is represented by a JSON object with the following properties.

NameTypeRequiredDescription
queryobjectyesThe body of the query. See Query
_created_atobjectnoAn object specifying a date range within which records must have been created to match. See Date Range Object
_updated_atobjectnoAn object specifying a date range within which records must have been updated to match. See Date Range Object
sort_bystringnoA string specifying the order to sort returned records. See Sorting results. Defaults to "_created_at desc"

Query

A query is a JSON object that has the following properties:

NameTypeRequiredDescription
<attribute>objectnoA comparison object specifying an attribute value condition to be met for records to match
_typeobjectnoA comparison object specifying an object type condition to be met for records to match
$andarraynoArray of conjunctive query objects (logical AND)
$orarraynoArray of disjunctive query objects (logical OR)

Example:

{  "query": {    "$and": [      {"author": {"$eq": "Sidney Sheldon"}},      {"publisher": {"$contains": "Bloomsbury"}}    ]  }}

Date range object

Date range objects are JSON objects that indicate at least one of a start and end date. Requests containing these objects are filtered to include only records that have been created or updated in that range, depending on which request parameter is used. If both created and updated are specified in the request, only records that satisfy both date ranges are returned.

A date range object has the following properties:

NameTypeRequiredFormatDescription
startstringnoyyyy-MM-dd HH:mm:ss.SSSInclusive beginning of the date range
endstringnoyyyy-MM-dd HH:mm:ss.SSSExclusive end of the date range

A date range can contain both, either, or neither of the start and end parameters. Note that a date range containing no parameters will not affect what records are returned by the request.

Example:

{  "query": {    "color": {"$eq": "magenta"}  },  "_created_at": {    "start": "2020-01-01 14:54:17.019",    "end": "2020-03-05 09:23:08.063"  }}

Comparison object

A comparison object defines a condition to be met for the record to match. The condition is based on an attribute value or object type.

A comparison object is a JSON object that has the following properties:

NameTypeRequiredDescription
$containsarray, boolean, integer, number, stringnoMatches records whose corresponding attribute value contains the value provided
$eqboolean, integer, number, stringnoMatches records whose corresponding attribute value equals the value provided
$neqboolean, integer, number, stringnoA shortcut for {"$not": {"$eq": <value>}}. Matches records whose corresponding attribute value does not equal the value provided
$notobjectnoA comparison object. Matches records whose corresponding attribute value does not satisfy the comparison object

Query all attributes

A comparison object can apply to a specific attribute. For example, {"color": {"$eq": "red"}} will match records that have the color attribute with a value equal to "red".

By using the "*" wildcard, a comparison object can also apply to all attributes. For example, {"*": {"$eq": "red"}} will match records that have attributes with a value equal to "red" no matter the name of the attribute. This can make query expressions significantly more economical. As with any wildcard expression, receiving some unexpected results is possible.

Querying nested attributes

When a record has one or more nested attributes, you can use dot notation to specify their fully qualified names in your queries. Consider this record:

{  "type": "book",  "id": "5d13764c-cf5f-11e9-aa86-2f9bb45ad15c",  "external_id": null,  "created_at": "2019-09-04T22:00:10.191Z",  "updated_at": "2019-09-04T22:00:10.191Z",  "attributes": {    "author": {      "first": "Sidney",      "last": "Sheldon"    },    "inventory": {      "book_price": 542,      "book_available": true,      "stores_available": ["938475", "872648", "234324"]    },    "name": "The Doomsday Conspiracy",    "publisher": "Bloomsbury publications"  }}

The record above would be matched by the following query:

{  "query": {    "$and": [      {"author.first": {"$eq": "Sidney"}},      {"author.last": {"$eq": "Sheldon"}},      {"inventory.book_available": {"$eq": true}},      {"inventory.stores_available": {"$contains": "872648"}}    ]  }}

Sorting results

The sort_by parameter must be a string of the format <_created_at|_updated_at> <asc|desc>. Currently only the _created_at and _updated_at metadata fields can be used in this manner.

Pagination

By default, the search endpoint returns ten records per page. You can change the number of records on a per-request basis by passing a per_page parameter in the request's URL parameters. Example: per_page=50. However, you can't exceed 1000 records per page for the Search endpoint. When the response exceeds the per-page maximum, you can paginate through the records by using the cursor parameter as given in the response.

Example: cursor=MjAyMC0wNi0wNVQwMToxNTo1MC42NjZafDIwMjAtMDYtMDVUMDE6MTU6MzUuMjE4Wg==.

Note: This endpoint supports a maximum of 80 pages. If you exceed this this, the cursor length will surpass the maximum URI length of 4096 characters that our HTTP server and gateways can handle.

The list results include next and previous URLs in the response body for easier navigation:

{  "data": [ ... ],  "links": {    "previous": "/api/sunshine/objects/query?per_page=10",    "next": "/api/sunshine/objects/query?per_page=10&cursor=MjAyMC0wNi0wOVQyMjowMjoyNC45MjFafDIwMjAtMDYtMDlUMjI6MDE6NTAuNTExWg=="  }}

The link to the previous page is set to null when you're on the first page of the search. Likewise, the link to the next page is set to null when you're on the last page.

Example of a first page of results:

{  "data": [ ... ],  "links": {    "previous": null,    "next": "/api/sunshine/objects/query?per_page=10&cursor=MjAyMC0wNi0wOVQyMjowMjoyNC45MjFa"  }}

Example of the last page of results:

{  "data": [ ... ],  "links": {    "previous": "/api/sunshine/objects/query?per_page=10&cursor=MjAyMC0wNi0wOVQyMjowMjoyNC45MjFa",    "next": null  }}

Allowed for

  • Agents

Parameters

NameTypeInRequiredDescription
cursorstringQueryfalsePagination cursor
per_pagestringQueryfalseNumber of items returned per page from 1 to 1000

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/sunshine/objects/query \   -d '{"query": {"$and": [{"author": {"$eq": "Sidney Sheldon"}}, {"publisher": {"$contains": "Bloomsbury"}}]}}' \   -H "Content-Type: application/json" -X POST \   -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/sunshine/objects/query?cursor=MjAyMC0wNi0wOVQyMjowMjoyNC45MjFafDIwMjAtMDYtMDlUMjI6MDE6NTAuNTExWg%3D%3D&per_page=1"	method := "POST"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/sunshine/objects/query")		.newBuilder()		.addQueryParameter("cursor", "MjAyMC0wNi0wOVQyMjowMjoyNC45MjFafDIwMjAtMDYtMDlUMjI6MDE6NTAuNTExWg==")		.addQueryParameter("per_page", "1");RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""""");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("POST", body)		.addHeader("Content-Type", "application/json")		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'POST',  url: 'https://support.zendesk.com/api/sunshine/objects/query',  headers: {	'Content-Type': 'application/json',  },  params: {    'cursor': 'MjAyMC0wNi0wOVQyMjowMjoyNC45MjFafDIwMjAtMDYtMDlUMjI6MDE6NTAuNTExWg%3D%3D',    'per_page': '1',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://support.zendesk.com/api/sunshine/objects/query?cursor=MjAyMC0wNi0wOVQyMjowMjoyNC45MjFafDIwMjAtMDYtMDlUMjI6MDE6NTAuNTExWg%3D%3D&per_page=1"headers = {	"Content-Type": "application/json",}
response = requests.request(	"POST",	url,	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/sunshine/objects/query")uri.query = URI.encode_www_form("cursor": "MjAyMC0wNi0wOVQyMjowMjoyNC45MjFafDIwMjAtMDYtMDlUMjI6MDE6NTAuNTExWg==", "per_page": "1")request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
{  "data": [    {      "attributes": {        "author": "Sidney Sheldon",        "book_available": true,        "book_price": 542,        "name": "The Doomsday Conspiracy",        "publisher": "Bloomsbury publications"      },      "created_at": "2019-09-04T22:00:10.191Z",      "external_id": null,      "id": "5d13764c-cf5f-11e9-aa86-2f9bb45ad15c",      "type": "book",      "updated_at": "2019-09-04T22:00:10.191Z"    },    {      "attributes": {        "author": "Sidney Sheldon",        "book_available": true,        "book_price": 542,        "name": "If Tomorrow Comes",        "publisher": "Bloomsbury publications"      },      "created_at": "2019-08-29T18:47:23.556Z",      "external_id": null,      "id": "70588682-ca8d-11e9-893a-63225c9f1206",      "type": "book",      "updated_at": "2019-08-29T18:47:23.556Z"    }  ]}