Search Records API

Audience: Developers, Integration Engineers, Solution Architects

Purpose: Explains how to retrieve Records programmatically using structured query criteria when a single unique identifier is not available.

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 automation 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 Automation, 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 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:

{
  "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 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 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 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 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 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 docs.

post

Search entity records.

Authorizations

apiKey & businessId & userId

X-API-KEYstringRequired

X-BUSINESS-IDstringRequired

X-USER-IDstringRequired

Path parameters

object_identifierstringRequired

Query parameters

group_idstringOptional

Group id to filter records by.

in_group_idsstringOptional

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.

not_in_group_idsstringOptional

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.

orderingstringOptional

Which field to use when ordering the results.

pageintegerOptional

A page number within the paginated result set.

page_sizeintegerOptional

Number of results to return per page.

searchstringOptional

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.

Body

application/json

field_namesstring[] · nullableOptional

List of field names to return. Only one of 'field_names' or 'field_ids' is allowed.

field_idsstring · uuid[] · nullableOptional

List of field ids to return. Only one of 'field_ids' or 'field_names' is allowed.

search_within_field_namesstring[] · nullableOptional

List of field names to search within. Only one of 'search_within_field_names' or 'search_within_field_ids' is allowed.

search_within_field_idsstring · uuid[] · nullableOptional

List of field ids to search within. Only one of 'search_within_field_ids' or 'search_within_field_names' is allowed.

andboolean · nullableOptional

Whether to apply AND or OR logic in filters

Default: true

Responses

200Success

application/json

countintegerRequiredExample: 123

nextstring · uri · nullableOptionalExample: http://api.example.org/accounts/?page=4

previousstring · uri · nullableOptionalExample: http://api.example.org/accounts/?page=2

errorsone ofOptionalExample: ["error message"]

nullOptional

or

string[]Optional

post

/api/records/{object_identifier}/search

HTTPcURLJavaScriptPython

POST /api/records/{object_identifier}/search HTTP/1.1
X-API-KEY: YOUR_API_KEY
X-BUSINESS-ID: YOUR_API_KEY
X-USER-ID: YOUR_API_KEY
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
}

200Success

{
  "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 automation or 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:

Related Topics

• Add Records API

• Manage Records by ID API

• Lookup Record API

• Create or Update Records (Upsert) API