> For the complete documentation index, see [llms.txt](https://developer.kizen.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.kizen.com/docs/concepts/objects/records/records-apis/search-records-api.md).
# Search Records API
{% hint style="success" %}
**Audience:** Developers, Integration Engineers, Solution Architects
**Purpose:** Explains how to retrieve space.vars.entities programmatically using structured query criteria when a single unique identifier is not available.
{% endhint %}
## Overview
The **Search Records** endpoint allows you to retrieve one or more space.vars.entities 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 space.vars.entities by field values, apply complex query logic, return selected fields, and retrieve collections of space.vars.entities 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](/docs/concepts/objects/records/records-core-concepts.md) and [Object Data Model](/docs/concepts/objects/object-data-model.md).
### Why Use This API
Use the Record Search endpoint when you need to retrieve space.vars.entities based on conditions rather than a known unique identifier.
Common scenarios include:
* Retrieving space.vars.entities that meet lifecycle or status criteria
* Filtering space.vars.entities by one or more field values
* Identifying candidate space.vars.entities for synchronization with external systems
* Building reporting or analytics integrations
* Implementing conditional workflows
* Pre-validating data before updates or space.vars.automation triggers
Search is ideal when:
* Multiple space.vars.entities may match the criteria
* Filtering must be dynamic or user-defined
* Lookup by name or email is not possible
* The exact space.vars.entity ID is unknown
Once specific space.vars.entities are identified, use ID-based retrieval for deterministic updates, archival, or other space.vars.entity-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 space.vars.entities (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 space.vars.object-level, space.vars.entity-level, and field-level permissions
* May paginate large result sets
* Does not modify space.vars.entities
* Supports multi-layered filtering with grouped conditions and AND/OR logic, enabling precise, structured space.vars.entity retrieval beyond simple text search.
### Advanced Query Filter Capabilities
In addition to basic text search, the space.vars.entities Search endpoint supports structured, multi-layer filtering that mirrors the filtering logic available in the space.vars.Kizen\_company\_name UI.
This enables precise dataset selection for space.vars.automation, space.vars.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 space.vars.automation-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 conditions
* `and` : controls how filters inside that group are evaluated
* `id` : an internal identifier for the group
Example structure:
```json
{
"and": false,
"query": [
{
"id": "query-0",
"and": false,
"filters": [
{
"type": "fields",
"subtype": "non_custom",
"field": "birthday",
"condition": "=",
"value": "2026-03-18"
}
]
}
]
}
```
#### 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 match
* `and: 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 space.vars.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 identifier
* `condition` : comparison operator
* `value` : 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 space.vars.entity fields. Depending on `type` and `subtype`, queries may target:
* Standard fields
* space.vars.fields
* Forms and submissions
* Logged space.vars.activities
* Scheduled space.vars.activities
* Related space.vars.object
* Other supported space.vars.entity domains
This allows advanced segmentation across multiple space.vars.entity dimensions within a single query.
#### Interaction with Text Search
The endpoint supports both:
* Full-text search via the `search` parameter
* Structured 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 `and` values 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_ids` or `field_names`.
* Use pagination when expecting large result sets.
* Validate filter logic carefully before deploying to production.
#### Integration Guidance
When building advanced queries:
1. Construct the filter in the UI.
2. Inspect the resulting request payload in the browser network tab.
3. Replicate the `query` structure in your API call (except the `view_model` property; more on that below).
4. Capture returned space.vars.entity 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 `query` array and logical `and` values.
* Omit the `view_model` property.
* 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](https://app.go.kizen.com/api/docs/public/swagger#/records/records_search_create) docs.
## POST /api/records/{object\_identifier}/search
> Search entity records.
```json
{"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"security":[{"businessId":[],"userId":[],"apiKey":[]}],"components":{"securitySchemes":{"businessId":{"type":"apiKey","in":"header","name":"X-BUSINESS-ID"}},"schemas":{"EntityRecordSearchPayloadRequest":{"type":"object","properties":{"field_names":{"type":"array","items":{"type":"string","minLength":1},"nullable":true,"description":"List of field names to return. Only one of 'field_names' or 'field_ids' is allowed."},"field_ids":{"type":"array","items":{"type":"string","format":"uuid"},"nullable":true,"description":"List of field ids to return. Only one of 'field_ids' or 'field_names' is allowed."},"search_within_field_names":{"type":"array","items":{"type":"string","minLength":1},"nullable":true,"description":"List of field names to search within. Only one of 'search_within_field_names' or 'search_within_field_ids' is allowed."},"search_within_field_ids":{"type":"array","items":{"type":"string","format":"uuid"},"nullable":true,"description":"List of field ids to search within. Only one of 'search_within_field_ids' or 'search_within_field_names' is allowed."},"query":{"type":"array","items":{"$ref":"#/components/schemas/FilterQueryRequest"}},"and":{"type":"boolean","nullable":true,"default":true,"description":"Whether to apply AND or OR logic in filters"}}},"FilterQueryRequest":{"type":"object","properties":{"filters":{"type":"array","items":{"type":"object","additionalProperties":{}},"description":"List of filters to apply."},"and":{"type":"boolean","nullable":true,"default":true,"description":"Whether to apply AND or OR logic in filters"}}},"PaginatedEntityRecordListList":{"type":"object","required":["count","results"],"properties":{"count":{"type":"integer"},"next":{"type":"string","nullable":true,"format":"uri"},"previous":{"type":"string","nullable":true,"format":"uri"},"results":{"type":"array","items":{"$ref":"#/components/schemas/EntityRecordList"}},"errors":{"oneOf":[{"type":"null"},{"type":"array","items":{"type":"string"}}]}}},"EntityRecordList":{"type":"object","properties":{"object_type":{"type":"string"},"fields":{"$ref":"#/components/schemas/Fields"},"id":{"type":"string","format":"uuid"},"client_info":{"$ref":"#/components/schemas/ClientInfo"},"access":{"$ref":"#/components/schemas/AccessSerpy"}},"required":["access","client_info","fields","id","object_type"]},"Fields":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/SerializedFieldValueDict"}},"required":["id"]},"SerializedFieldValueDict":{"type":"object","properties":{"id":{"type":"string"},"field_type":{"type":"string"},"display_name":{"type":"string"},"value":{"type":"object","additionalProperties":{}}},"required":["display_name","field_type","id","value"]},"ClientInfo":{"type":"object","properties":{"num_addresses_v2":{"type":"integer"},"display_name":{"type":"string"},"email_on_suppression_list":{"type":"boolean"}},"required":["display_name","email_on_suppression_list","num_addresses_v2"]},"AccessSerpy":{"type":"object","properties":{"view":{"type":"boolean"},"edit":{"type":"boolean"},"remove":{"type":"boolean"}},"required":["edit","remove","view"]}}},"paths":{"/api/records/{object_identifier}/search":{"post":{"operationId":"records_search_create","description":"Search entity records.","parameters":[{"in":"query","name":"group_id","schema":{"type":"string"},"description":"Group id to filter records by."},{"in":"query","name":"in_group_ids","schema":{"type":"string"},"description":"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."},{"in":"query","name":"not_in_group_ids","schema":{"type":"string"},"description":"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."},{"in":"path","name":"object_identifier","schema":{"type":"string"},"required":true},{"in":"query","name":"ordering","schema":{"type":"string"},"description":"Which field to use when ordering the results."},{"in":"query","name":"page","schema":{"type":"integer"},"description":"A page number within the paginated result set."},{"in":"query","name":"page_size","schema":{"type":"integer"},"description":"Number of results to return per page."},{"in":"query","name":"search","schema":{"type":"string"},"description":"\n 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.\n "}],"tags":["records"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityRecordSearchPayloadRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedEntityRecordListList"}}},"description":""}}}}}}
```
***
## Search Records Schema
## The EntityRecordSearchPayloadRequest object
```json
{"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"components":{"schemas":{"EntityRecordSearchPayloadRequest":{"type":"object","properties":{"field_names":{"type":"array","items":{"type":"string","minLength":1},"nullable":true,"description":"List of field names to return. Only one of 'field_names' or 'field_ids' is allowed."},"field_ids":{"type":"array","items":{"type":"string","format":"uuid"},"nullable":true,"description":"List of field ids to return. Only one of 'field_ids' or 'field_names' is allowed."},"search_within_field_names":{"type":"array","items":{"type":"string","minLength":1},"nullable":true,"description":"List of field names to search within. Only one of 'search_within_field_names' or 'search_within_field_ids' is allowed."},"search_within_field_ids":{"type":"array","items":{"type":"string","format":"uuid"},"nullable":true,"description":"List of field ids to search within. Only one of 'search_within_field_ids' or 'search_within_field_names' is allowed."},"query":{"type":"array","items":{"$ref":"#/components/schemas/FilterQueryRequest"}},"and":{"type":"boolean","nullable":true,"default":true,"description":"Whether to apply AND or OR logic in filters"}}},"FilterQueryRequest":{"type":"object","properties":{"filters":{"type":"array","items":{"type":"object","additionalProperties":{}},"description":"List of filters to apply."},"and":{"type":"boolean","nullable":true,"default":true,"description":"Whether to apply AND or OR logic in filters"}}}}}}
```
## The PaginatedEntityRecordListList object
```json
{"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"components":{"schemas":{"PaginatedEntityRecordListList":{"type":"object","required":["count","results"],"properties":{"count":{"type":"integer"},"next":{"type":"string","nullable":true,"format":"uri"},"previous":{"type":"string","nullable":true,"format":"uri"},"results":{"type":"array","items":{"$ref":"#/components/schemas/EntityRecordList"}},"errors":{"oneOf":[{"type":"null"},{"type":"array","items":{"type":"string"}}]}}},"EntityRecordList":{"type":"object","properties":{"object_type":{"type":"string"},"fields":{"$ref":"#/components/schemas/Fields"},"id":{"type":"string","format":"uuid"},"client_info":{"$ref":"#/components/schemas/ClientInfo"},"access":{"$ref":"#/components/schemas/AccessSerpy"}},"required":["access","client_info","fields","id","object_type"]},"Fields":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/SerializedFieldValueDict"}},"required":["id"]},"SerializedFieldValueDict":{"type":"object","properties":{"id":{"type":"string"},"field_type":{"type":"string"},"display_name":{"type":"string"},"value":{"type":"object","additionalProperties":{}}},"required":["display_name","field_type","id","value"]},"ClientInfo":{"type":"object","properties":{"num_addresses_v2":{"type":"integer"},"display_name":{"type":"string"},"email_on_suppression_list":{"type":"boolean"}},"required":["display_name","email_on_suppression_list","num_addresses_v2"]},"AccessSerpy":{"type":"object","properties":{"view":{"type":"boolean"},"edit":{"type":"boolean"},"remove":{"type":"boolean"}},"required":["edit","remove","view"]}}}}
```
## The EntityRecordList object
```json
{"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"components":{"schemas":{"EntityRecordList":{"type":"object","properties":{"object_type":{"type":"string"},"fields":{"$ref":"#/components/schemas/Fields"},"id":{"type":"string","format":"uuid"},"client_info":{"$ref":"#/components/schemas/ClientInfo"},"access":{"$ref":"#/components/schemas/AccessSerpy"}},"required":["access","client_info","fields","id","object_type"]},"Fields":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/SerializedFieldValueDict"}},"required":["id"]},"SerializedFieldValueDict":{"type":"object","properties":{"id":{"type":"string"},"field_type":{"type":"string"},"display_name":{"type":"string"},"value":{"type":"object","additionalProperties":{}}},"required":["display_name","field_type","id","value"]},"ClientInfo":{"type":"object","properties":{"num_addresses_v2":{"type":"integer"},"display_name":{"type":"string"},"email_on_suppression_list":{"type":"boolean"}},"required":["display_name","email_on_suppression_list","num_addresses_v2"]},"AccessSerpy":{"type":"object","properties":{"view":{"type":"boolean"},"edit":{"type":"boolean"},"remove":{"type":"boolean"}},"required":["edit","remove","view"]}}}}
```
***
## What’s Next
After Retrieving space.vars.entities via Search, you can:
* Retrieve specific space.vars.entities by ID for deterministic updates or archival
* Perform bulk operations on identified space.vars.entity sets
* Use returned field data to drive space.vars.automation logic
* Capture space.vars.entity IDs for synchronization with external systems
For more information on managing and modifying space.vars.entities, review the following space.vars.entity API topics below:
Related Topics
* [Add Records API](/docs/concepts/objects/records/records-apis.md)
* [Manage Records by ID API](/docs/concepts/objects/records/records-apis/manage-records-by-id-api.md)
* [Lookup Record API](/docs/concepts/objects/records/records-apis/lookup-record-api.md)
* [Create or Update Records (Upsert) API](/docs/concepts/objects/records/records-apis/create-or-update-records-upsert-api.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://developer.kizen.com/docs/concepts/objects/records/records-apis/search-records-api.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.