Custom Objects Search

You can use the Search 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:

Name	Type	Read-only	Mandatory	Description
data	array	false	false	Object records that match the query parameters
links	object	false	false	The 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 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.

Name	Type	Required	Description
query	object	yes	The body of the query. See Query
_created_at	object	no	An object specifying a date range within which records must have been created to match. See Date Range Object
_updated_at	object	no	An object specifying a date range within which records must have been updated to match. See Date Range Object
sort_by	string	no	A 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:

Name	Type	Required	Description
<attribute>	object	no	A comparison object specifying an attribute value condition to be met for records to match
_type	object	no	A comparison object specifying an object type condition to be met for records to match
$and	array	no	Array of conjunctive query objects (logical AND)
$or	array	no	Array 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:

Name	Type	Required	Format	Description
start	string	no	yyyy-MM-dd HH:mm:ss.SSS	Inclusive beginning of the date range
end	string	no	yyyy-MM-dd HH:mm:ss.SSS	Exclusive 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:

Name	Type	Required	Description
$contains	array, boolean, integer, number, string	no	Matches records whose corresponding attribute value contains the value provided
$eq	boolean, integer, number, string	no	Matches records whose corresponding attribute value equals the value provided
$neq	boolean, integer, number, string	no	A shortcut for {"$not": {"$eq": <value>}}. Matches records whose corresponding attribute value does not equal the value provided
$not	object	no	A 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==.

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

Name	Type	In	Required	Description
cursor	string	Query	false	Pagination cursor
per_page	string	Query	false	Number 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}:{password}

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"
    }
  ]
}