Record Search
Audience: Admins, Developers, Solution Architects
Purpose: Explains how to search for records in Kizen using the API, including text-based search, criteria-based filtering, and recommended best practices.
Overview
When the ID of an entity is known, the get API endpoints can be used to fetch the entity. In situations where a search for records is necessary, Kizen provides an API endpoint to search entities based on a number of criteria.
Using the endpoint /records/{object_identifier}/search, a list of matching entities can be fetched:
curl -X POST "https://app.go.kizen.com/api/records/object_identifier/search" \
-H 'accept: application/json'\
-H 'content-type: application/json' When no parameters are included, the search endpoint will return all records.
Search Criteria
The search criteria are passed as query string parameters or in the body of the POST:
group_id
String
Filter group ID. Used to filter records returned.
in_group_ids
String
Comma-separated list of filter group IDs. Only returns records in at least one of these groups. If both in_group_ids and not_in_group_ids are supplied, only in_group_ids will be considered.
not_in_group_ids
String
Comma-separated list of filter group IDs. Only returns records that are not in any of these groups. If both in_group_ids and not_in_group_ids are supplied, only in_group_ids will be considered.
ordering
String
The field to use to order the results.
page
Integer
Which page to return in the result set.
page_size
Integer
The number of results per page.
search
String
The search term to filter by. By default, this text search will be applied to the name field for entities, and for contacts, will be applied to the email, first_name, last_name, home_phone, mobile_phone, and business_phone.
When performing a text search, by default the text search will be applied to the name field for entities, and for contacts, will be applied to the email, first_name, last_name, home_phone, mobile_phone, and business_phone fields.
To adjust this behavior, there are three additional parameters that can be used in the body of the POST:
search_within_field_names
An array of field API names to apply the search text to
search_within_field_ids
An array of field IDs names to apply the search text to
query*
An object representing a specific filter to apply as part of the search.
* Query payloads are not considered to be version-safe at this time. Future updates to the Kizen platform may break existing hard-coded filter configurations. For this reason, we strongly recommend creating a filter group first in Kizen, and using the group ID in the API call, not the filter payload itself.
What's Next
In the next section, Record Permissions, you’ll learn how user permissions determine record visibility and how access levels impact API responses when listing or searching records.
Last updated
Was this helpful?