Search Records API
Overview
The Search Records endpoint allows you to retrieve one or more Records based on structured query criteria rather than a single unique identifier.
This endpoint is designed for flexible, condition-based retrieval scenarios. It enables external systems to filter Records by field values, apply complex query logic, return selected fields, and retrieve collections of Records that match dynamic criteria, without relying on ID- or lookup-based access.
The material on this page builds on information covered in Records Core Concepts and Object Data Model.
Why Use This API
Use the Record Search endpoint when you need to retrieve Records based on conditions rather than a known unique identifier.
Common scenarios include:
Retrieving Records that meet lifecycle or status criteria
Filtering Records by one or more field values
Identifying candidate Records for synchronization with external systems
Building reporting or analytics integrations
Implementing conditional workflows
Pre-validating data before updates or Agentic Workflow triggers
Search is ideal when:
Multiple Records may match the criteria
Filtering must be dynamic or user-defined
Lookup by name or email is not possible
The exact Record ID is unknown
Once specific Records are identified, use ID-based retrieval for deterministic updates, archival, or other Record-level operations.
Search Records API Behavior
Understand how this endpoint behaves:
Accepts structured query criteria referencing valid field API names
Returns a collection of matching Records (zero, one, or many)
Does not guarantee uniqueness and is not a substitute for lookup when a single result is required
Supports selective field returns to control response size
Respects Object-level, Record-level, and field-level permissions
May paginate large result sets
Does not modify Records
Supports multi-layered filtering with grouped conditions and AND/OR logic, enabling precise, structured Record retrieval beyond simple text search.
Advanced Query Filter Capabilities
In addition to basic text search, the Records Search endpoint supports structured, multi-layer filtering that mirrors the filtering logic available in the Kizen UI.
This enables precise dataset selection for Agentic Workflow, Workflow logic, reporting, synchronization, and segmentation use cases.
The request body supports two levels of logical grouping:
Filter logic within a query group
Logical relationships between query groups
Understanding this structure is critical when constructing Agentic Workflow-driven or integration-based searches.
Query Group Structure
The query property is an array of query groups. There may be one or many groups.
Each query group contains:
filters: a list of individual field conditionsand: controls how filters inside that group are evaluatedid: an internal identifier for the group
Example structure:
Layer 1: Filter Logic Within a Query Group
Inside each query group:
and: true→ All filters in that group must match (ALL logic)and: false→ Any filter in that group may match (ANY logic)
This corresponds to the ALL / ANY toggle visible in the UI filter builder. Filters within a group operate only relative to that group.
Layer 2: Logic Between Query Groups
The top-level and property controls how query groups relate to each other:
and: true→ All groups must matchand: false→ Any group may match (functions as OR operator)
Conceptually, evaluation follows this pattern:
(Group 1 Filters) [AND/OR] (Group 2 Filters) [AND/OR] (Group 3 Filters) ...
Each group may contain multiple filters, and there is no inherent two-group limitation.
Filter Definition
Each filter Object includes:
type: category of filter (e.g.,fields,forms,logged_activities,related_object, etc.)subtype: subtype classification (e.g.,non_custom, custom field types)field: field API identifiercondition: comparison operatorvalue: comparison value
Available operators depend on field type (date, text, number, boolean, etc.) and mirror those available in the UI filter builder. Invalid operator–field combinations will result in validation errors.
Cross-Entity Filtering
Filtering is not limited to standard Record fields. Depending on type and subtype, queries may target:
Standard fields
Custom Fields
Forms and submissions
Logged Activities
Scheduled Activities
Related Object
Other supported Record domains
This allows advanced segmentation across multiple Record dimensions within a single query.
Interaction with Text Search
The endpoint supports both:
Full-text search via the
searchparameterStructured filtering via
query
If both are provided, results must satisfy the combined constraints. Structured filtering should be used when deterministic logical control is required.
Search Query Optimization
Because the API supports layered AND/OR logic:
Small changes in
andvalues can significantly alter result sets.Broad OR logic may return large datasets.
Complex or loosely scoped filters may increase response size and processing time.
Best practices:
Scope filters as narrowly as possible.
Limit returned fields using
field_idsorfield_names.Use pagination when expecting large result sets.
Validate filter logic carefully before deploying to production.
Integration Guidance
When building advanced queries:
Construct the filter in the UI.
Inspect the resulting request payload in the browser network tab.
Replicate the
querystructure in your API call (except theview_modelproperty; more on that below).Capture returned Record IDs for deterministic follow-up operations.
For operations requiring guaranteed uniqueness, use ID-based retrieval instead of complex logical filtering.
Omit view_model property
When constructing advanced queries using the UI filter builder and inspecting the network request, you may see a view_model property included in the request body.
The view_model property is used internally by the UI and should not be used for API-based search requests.
When replicating the query structure in your API call:
Copy the
queryarray and logicalandvalues.Omit the
view_modelproperty.Submit only supported API request properties.
Including view_model in an API request will result in missing fields or schema mismatch issues.
Search Records Endpoint
Want to try the API out? Visit our Swagger docs.
Search entity records.
Group id to filter records by.
Comma separated list of group ids. Only records in these groups will be returned. If both 'in_group_ids' and 'not_in_group_ids' are supplied, only 'in_group_ids' will be considered.
Comma separated list of group ids. Only records not in these groups will be returned. If both 'in_group_ids' and 'not_in_group_ids' are supplied, only 'in_group_ids' will be considered.
Which field to use when ordering the results.
A page number within the paginated result set.
Number of results to return per page.
A search term, by default, searches Contact's email, first_name, last_name, home_phone, mobile_phone, business_phone and Record's name. 'search_within_field_names' or 'search_within_field_ids' can be used to specify fields to search within.
List of field names to return. Only one of 'field_names' or 'field_ids' is allowed.
List of field ids to return. Only one of 'field_ids' or 'field_names' is allowed.
List of field names to search within. Only one of 'search_within_field_names' or 'search_within_field_ids' is allowed.
List of field ids to search within. Only one of 'search_within_field_ids' or 'search_within_field_names' is allowed.
Whether to apply AND or OR logic in filters
true123http://api.example.org/accounts/?page=4http://api.example.org/accounts/?page=2["error message"]POST /api/records/{object_identifier}/search HTTP/1.1
X-API-KEY: YOUR_API_KEY
X-BUSINESS-ID: YOUR_BUSINESS_ID
X-USER-ID: YOUR_USER_ID
Content-Type: application/json
Accept: */*
Content-Length: 266
{
"field_names": [
"text"
],
"field_ids": [
"123e4567-e89b-12d3-a456-426614174000"
],
"search_within_field_names": [
"text"
],
"search_within_field_ids": [
"123e4567-e89b-12d3-a456-426614174000"
],
"query": [
{
"filters": [
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"and": true
}
],
"and": true
}{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"object_type": "text",
"fields": {
"id": {
"id": "text",
"field_type": "text",
"display_name": "text",
"value": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
},
"id": "123e4567-e89b-12d3-a456-426614174000",
"client_info": {
"num_addresses_v2": 1,
"display_name": "text",
"email_on_suppression_list": true
},
"access": {
"view": true,
"edit": true,
"remove": true
}
}
],
"errors": [
"error message"
]
}Search Records Schema
What’s Next
After Retrieving Records via Search, you can:
Retrieve specific Records by ID for deterministic updates or archival
Perform bulk operations on identified Record sets
Use returned field data to drive Agentic Workflow logic
Capture Record IDs for synchronization with external systems
For more information on managing and modifying Records, review the following Record API topics below:
Last updated
Was this helpful?