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.

Search Object Records by Attribute Value

POST /api/sunshine/objects/query

Returns object records that match the query parameters.

Allowed For

  • Agents

URI Parameters

Name Type Required Description
cursor string no Pagination cursor
per_page integer no The requested number of records to return per page. Defaults to 10; maximum value is 1000

Request Body Parameters

Name Type Required Description
query QueryNode yes The body of the query
_created_at DateRange no An object specifying a date range within which records must have been created to match
_updated_at DateRange no An object specifying a date range within which records must have been updated to match
sort_by string no A string specifying the order to sort returned records. See Sort By Parameter for more information. Defaults to "_created_at desc".
DateRange Objects

DateRanges are JSON objects that indicate at least one of a start and end date. Requests containing these objects will be 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, the returned records will be only those which satisfy both date ranges.

DateRange Parameters
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 DateRange can contain both, either, or neither of the start and end parameters. Note that a DateRange containing no parameters will not affect what records are returned by the request.

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

QueryNodes are JSON objects that make up the core of the request. They indicate what records to retrieve based on their types, attributes, and values.

QueryNode Parameters
Name Type Required Description
_type QueryComparator one of {_type, $and, $or, <attribute>} Comparator against Object Type
<attribute> QueryComparator one of {_type, $and, $or, <attribute>} Comparator against object record attribute values
$and Array[QueryNode] one of {_type, $and, $or, <attribute>} Array of conjunctive QueryNodes (logically AND'ed together)
$or Array[QueryNode] one of {_type, $and, $or, <attribute>} Array of disjunctive QueryNodes (logically OR'ed together)
QueryComparator Objects

QueryComparators are JSON objects which indicate what records should be matched based on attribute values (or in the case of _type, the records' Object Type).

QueryComparator Parameters
Name Type Required Description
$contains array, boolean, integer, number, string one of {$contains, $eq, $neq, $not} Matches records whose corresponding attribute value contains the value provided
$eq boolean, integer, number, string one of {$contains, $eq, $neq, $not} Matches records whose corresponding attribute value equals the value provided
$neq boolean, integer, number, string one of {$contains, $eq, $neq, $not} A shortcut for {"$not": {"$eq": <value>}}; matches records whose corresponding attribute value does not equal the value provided
$not QueryComparator one of {$contains, $eq, $neq, $not} Matches records whose corresponding attribute value does not satisfy the contained QueryComparator
Wildcard Queries Over All Attributes

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

A QueryComparator can also apply the comparison against all attributes with the "*" wildcard. 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, there is a possibility of receiving some unexpected results.

Example Request

{
  "query": {
    "$and": [
      {"author": {"$eq": "Sidney Sheldon"}},
      {"publisher": {"$contains": "Bloomsbury"}}
    ]
  }
}
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": [
    {
      "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": {
        "book_price": 542,
        "book_available": true,
        "author": "Sidney Sheldon",
        "name": "The Doomsday Conspiracy",
        "publisher": "Bloomsbury publications"
      }
    },
    {
      "type": "book",
      "id": "70588682-ca8d-11e9-893a-63225c9f1206",
      "external_id": null,
      "created_at": "2019-08-29T18:47:23.556Z",
      "updated_at": "2019-08-29T18:47:23.556Z",
      "attributes": {
        "book_price": 542,
        "book_available": true,
        "author": "Sidney Sheldon",
        "name": "If Tomorrow Comes",
        "publisher": "Bloomsbury publications"
      }
    }
  ]
}
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 adjustment to one of the records from the previous example:

{
  "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: json { "query": { "$and": [ {"author.first": {"$eq": "Sidney"}}, {"author.last": {"$eq": "Sheldon"}}, {"inventory.book_available": {"$eq": true}}, {"inventory.stores_available": {"$contains": "872648"}} ] } }

Sort By Parameter

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