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\u0026cursor=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 Sort By Parameter. 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

Using 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}

Example Response

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