# Search > Query customers, conversations, messages, companies, notes and custom objects with Kustomer's search API, including filters, operators, dates, custom attributes, sorting, limits and every standard attribute. Source: https://developer.kustomer.com/docs/concepts/search The search API runs the same queries as saved searches in Kustomer. One endpoint covers every object type: you pick what to return with `queryContext`, and filter with `and`, `or` and `not` criteria on any standard or custom attribute. `POST /v1/customers/search` ([reference](https://developer.kustomer.com/api/core-resources/create-customer-search)) ```bash title="cURL" curl -X POST "https://acme.api.kustomerapp.com/v1/customers/search?pageSize=100" \ -H "Authorization: Bearer $KUSTOMER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "queryContext": "conversation", "and": [ { "conversation_status": { "equals": "open" } }, { "conversation_priority": { "gte": 4 } }, { "conversation_created_at": { "gte": "2026-10-01" } } ], "timeZone": "America/New_York" }' ``` Despite the path, the endpoint isn't limited to customers. With `queryContext: "conversation"`, it returns conversations. ## Request body **Search body** Query parameters: `page`, `pageSize` (up to 500), and `idsOnly=true` to return only matching IDs, which is faster for large syncs. ## Criteria Each criterion maps one attribute to one operator and value: ```json { "": { "": } } ``` Attribute names are `_` in snake case, such as `conversation_status` or `customer_created_at`. You can filter on attributes of related objects too: a `customer` search can filter on `conversation_status` to find customers with open conversations. ### Operators Which operators an attribute accepts depends on its operator group, listed in the [standard attributes](#standard-attributes-json-schema) tables. | Operator group | Operators | Example | | -------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------- | | `string` | `equals`, `not_equals`, `contains`, `not_contains`, `is_set`, `not_set` | `{ "customer_name": { "contains": "doe" } }` | | `string_notanalyzed` | `equals`, `not_equals`, `is_set`, `not_set` (exact match) | `{ "customer_externalId": { "equals": "crm-10293" } }` | | `text` | `contains`, `not_contains`, `is_set`, `not_set` | `{ "message_body": { "contains": "refund" } }` | | `list` | `equals`, `not_equals`, `in`, `not_in`, `is_set`, `not_set` | `{ "conversation_status": { "in": ["open", "snoozed"] } }` | | `number` | `equals`, `between`, `gte`, `lte`, `is_set`, `not_set` | `{ "conversation_message_count": { "gte": 5 } }` | | `datetime` | `gt`, `gte`, `lt`, `lte`, `is_set`, `not_set` | `{ "conversation_created_at": { "gte": "2026-10-01" } }` | | `boolean` | `equals`, `is_set`, `not_set` | `{ "kobject_imported": { "equals": true } }` | | `any` | `matches` (free-text match across the object) | `{ "customer_any_text": { "matches": "order 4417" } }` | `in` and `not_in` take arrays. `is_set` and `not_set` ignore their value; send an empty string (company searches need `true`). `contains` is case-insensitive. ### Combining criteria ```json { "queryContext": "customer", "and": [{ "customer_custom_loyaltyTierStr": { "equals": "gold" } }], "or": [ { "conversation_status": { "equals": "open" } }, { "conversation_status": { "equals": "snoozed" } } ], "not": [{ "customer_email": { "contains": "@acme.example" } }] } ``` _An interactive query builder for a conversation search. The reader switches criteria on and off (conversation_status with equals or in, conversation_priority with gte, lte or equals, a conversation_created_at range built from a gte and an lte criterion, and customer_custom_loyaltyTierStr), moves each one between the and, or and not groups, and picks a customer attribute to sort by. The POST /v1/customers/search request body updates live with the changed lines highlighted, while twelve sample conversations show which records match, why each one passes or fails, and the sorted order. It shows that and requires every criterion, or needs at least one, not excludes matches, and sorting always uses customer attributes._ ## Dates Dates can be local (`YYYY-MM-DD`) or UTC timestamps: - A **local date** is interpreted in `timeZone`, or GMT if you omit it. `{"conversation_created_at": {"lte": "2026-10-19"}}` with `"timeZone": "America/New_York"` means "up to the end of 19 October, New York time." - A **UTC timestamp** such as `2026-10-20T16:34:00.000Z` is used exactly, with no time-zone adjustment. ## Custom attributes | Object | Pattern | Example | | ---------------- | ------------------------------------ | ---------------------------------------------------------------- | | Standard objects | `_custom_` | `{ "customer_custom_loyaltyTierStr": { "equals": "gold" } }` | | Custom objects | `kobject_custom__` | `{ "kobject_custom_ecomm-order_totalPriceNum": { "gte": 100 } }` | The attribute's suffix decides its operator group: `Str` behaves like `string`, `Num` like `number`, `At` like `datetime`, `Bool` like `boolean`. ## Sorting Sorting only works on customer attributes, whatever the `queryContext`: ```json { "sort": [{ "customer_updated_at": "asc" }] } ``` Sortable attributes: `customer_name`, `customer_gender`, `customer_created_at`, `customer_updated_at`, `customer_modified_at`, `customer_externalId`, `customer_activity_at`, `customer_last_seen_at`, `customer_signed_up_at`, `customer_lastmessage_preview`, `customer_progressive_status`, `customer_done`, `customer_open`, `customer_snoozed`, `customer_last_message_sent_at`, `customer_last_message_out_sent_at`, `customer_last_message_unresponded_to_sent_at`, `customer_last_message_at`. ## Response ```json title="200 OK" { "meta": { "pageSize": 100, "page": 1, "total": 238, "totalPages": 3 }, "links": { "self": "...", "next": "..." }, "data": [ { "type": "conversation", "id": "58228e05d4e96711004eccb7", "attributes": { "name": "Where is my order?", "status": "open" } } ] } ``` ## Limits - **10,000 results per query.** `pageSize` goes up to 500, and a request where `page × pageSize` is over 10,000 returns `400`. For bigger result sets, window the query by `updated_at` and run one search per window. [Search recipes](https://developer.kustomer.com/docs/guides/search-recipes#export-more-than-the-page-limit) has the code. - **Two years of data.** Search covers records updated in the past two years. For older standard and custom objects, use the archive search endpoint with the same body: `POST /v1/customers/archive/search` ([reference](https://developer.kustomer.com/api/core-resources/create-customer-archive-search)) - **Rate limit.** Machine users (API keys) can make 100 search requests per minute. See [Rate limits](https://developer.kustomer.com/docs/concepts/rate-limits). - **Index delay.** Search is updated asynchronously, so a record you just created can take a moment to appear. To read your own writes, fetch the record by ID or `externalId`. ## Standard attributes JSON schema Every standard attribute you can filter on, grouped by object. The operator group decides which [operators](#operators) apply. The full JSON schema is also in the [search endpoint's reference](https://developer.kustomer.com/api/core-resources/create-customer-search). ### Customer attributes | Attribute | Type | Operator group | Values | | ---------------------------------------------- | --------- | -------------------- | ----------------------------------------------------------------------- | | `customer_any_text` | string | `any` | | | `customer_name` | string | `string` | | | `customer_gender` | string | `list` | `m`, `f` | | `customer_presence` | string | `list` | `online`, `offline`, `idle` | | `customer_email` | string | `string` | | | `customer_shared_email` | string | `string` | | | `customer_phone` | string | `string` | | | `customer_shared_phone` | string | `string` | | | `customer_urls` | string | `string` | | | `customer_address` | string | `string` | | | `customer_locale` | string | `string` | | | `customer_activity_at` | date-time | `datetime` | | | `customer_last_seen_at` | date-time | `datetime` | | | `customer_signed_up_at` | date-time | `datetime` | | | `customer_last_message_sent_at` | date-time | `datetime` | | | `customer_last_message_out_sent_at` | date-time | `datetime` | | | `customer_last_message_unresponded_to_sent_at` | date-time | `datetime` | | | `customer_last_message_at` | date-time | `datetime` | | | `customer_externalId` | string | `string_notanalyzed` | | | `customer_shared_externalId` | string | `string_notanalyzed` | | | `customer_created_at` | date-time | `datetime` | | | `customer_updated_at` | date-time | `datetime` | | | `customer_modified_at` | date-time | `datetime` | | | `customer_created_by` | user | `list` | | | `customer_modified_by` | user | `list` | | | `customer_satisfaction_avg_score` | number | `number` | | | `customer_satisfaction_avg_rating` | number | `number` | | | `customer_conversations_count` | number | `number` | | | `customer_status` | string | `list` | `snoozed`, `open`, `done` | | `customer_progressive_status` | string | `list` | `snoozed`, `open`, `done` | | `customer_active_users` | user | `list` | | | `customer_watchers` | user | `list` | | | `customer_tags` | string | `list` | | | `customer_sentiment` | string | `list` | `happy`, `unhappy`, `indifferent` | | `customer_social_type` | string | `list` | `facebook`, `instagram`, `whatsapp`, `linkedin`, `pinterest`, `twitter` | | `customer_social_userid` | string | `string_notanalyzed` | | | `customer_social_username` | string | `string_notanalyzed` | | | `customer_shared_social_type` | string | `list` | `facebook`, `instagram`, `whatsapp`, `linkedin`, `pinterest`, `twitter` | | `customer_shared_social_userid` | string | `string_notanalyzed` | | | `customer_shared_social_username` | string | `string_notanalyzed` | | | `customer_default_lang` | string | `string_notanalyzed` | | | `customer_imported_at` | date-time | `datetime` | | | `customer_imported` | boolean | `boolean` | | ### Company attributes | Attribute | Type | Operator group | Values | | ---------------------- | --------- | -------------------- | ------ | | `company_any_text` | string | `any` | | | `company_name` | string | `string` | | | `company_tags` | string | `list` | | | `company_default_lang` | string | `string_notanalyzed` | | | `company_imported_at` | date-time | `datetime` | | | `company_imported` | boolean | `boolean` | | ### Message attributes | Attribute | Type | Operator group | Values | | -------------------------- | --------- | -------------------- | --------------------------------------------------------------------------------------------------- | | `message_any_text` | string | `any` | | | `message_body` | string | `text` | | | `message_channel` | string | `list` | `sms`, `chat`, `email`, `facebook`, `voice`, `twitter-dm`, `twitter-tweet`, `instagram`, `whatsapp` | | `message_size` | number | `number` | | | `message_direction` | string | `boolean` | `in`, `out` | | `message_sent_at` | date-time | `datetime` | | | `message_created_at` | date-time | `datetime` | | | `message_updated_at` | date-time | `datetime` | | | `message_created_by` | user | `list` | | | `message_modified_by` | user | `list` | | | `message_sentiment` | string | `list` | `happy`, `unhappy`, `indifferent` | | `message_customer_id` | string | `string_notanalyzed` | | | `message_status` | string | `list` | `sent`, `received`, `error` | | `message_error_at` | date-time | `datetime` | | | `message_error_title` | string | `string` | | | `message_external_id` | string | `string_notanalyzed` | | | `message_direction_type` | string | `list` | `initial-in`, `initial-out`, `response-in`, `response-out`, `followup-in`, `followup-out` | | `message_created_by_teams` | string | `string_notanalyzed` | | | `message_redacted` | string | `boolean` | | | `message_redacted_at` | date-time | `datetime` | | | `message_imported_at` | date-time | `datetime` | | | `message_imported` | boolean | `boolean` | | | `message_recipients` | string | `string` | | | `message_sender` | string | `string` | | | `message_shortcuts` | string | `string_notanalyzed` | | | `message_subject` | string | `text` | | | `message_source` | string | `list` | `bulk` | | `message_attachment_count` | number | `number` | | | `message_auto` | string | `boolean` | | | `message_lang` | string | `string_notanalyzed` | | ### Note attributes | Attribute | Type | Operator group | Values | | ----------------------- | --------- | -------------------- | ------ | | `note_any_text` | string | `any` | | | `note_body` | string | `text` | | | `note_created_at` | date-time | `datetime` | | | `note_modified_at` | date-time | `datetime` | | | `note_updated_at` | date-time | `datetime` | | | `note_created_by` | user | `list` | | | `note_modified_by` | user | `list` | | | `note_deleted` | user | `boolean` | | | `note_user_mentions` | user | `list` | | | `note_team_mentions` | string | `list` | | | `note_attachment_count` | user | `number` | | | `note_external_id` | string | `string_notanalyzed` | | | `note_customer_id` | string | `string_notanalyzed` | | | `note_conversation_id` | string | `string_notanalyzed` | | | `note_lang` | string | `string_notanalyzed` | | | `note_imported_at` | date-time | `datetime` | | | `note_imported` | boolean | `boolean` | | ### Conversation attributes | Attribute | Type | Operator group | Values | | -------------------------------------------------- | --------- | -------------------- | --------------------------------------------------------------------------------------------------------------- | | `conversation_any_text` | string | `any` | | | `conversation_name` | string | `string` | | | `conversation_sentiment` | string | `list` | `happy`, `unhappy`, `indifferent` | | `conversation_status` | string | `list` | `snoozed`, `open`, `done` | | `conversation_sub_status` | string | `string_notanalyzed` | | | `conversation_created_at` | date-time | `datetime` | | | `conversation_updated_at` | date-time | `datetime` | | | `conversation_modified_at` | date-time | `datetime` | | | `conversation_modified_by` | user | `list` | | | `conversation_message_count` | number | `number` | | | `conversation_note_count` | number | `number` | | | `conversation_satisfaction_survey_id` | string | `list` | | | `conversation_satisfaction_sent_by` | user | `list` | | | `conversation_satisfaction_sent_by_teams` | string | `list` | | | `conversation_satisfaction_created_at` | date-time | `datetime` | | | `conversation_satisfaction_score` | number | `number` | | | `conversation_satisfaction_rating` | number | `number` | | | `conversation_satisfaction_status` | string | `list` | `canceled`, `scheduled`, `offered`, `unresponded`, `rated`, `commented` | | `conversation_channels` | string | `list` | `sms`, `chat`, `email`, `facebook`, `voice`, `twitter-dm`, `twitter-tweet`, `instagram`, `whatsapp` | | `conversation_satisfaction` | string | `string` | | | `conversation_priority` | integer | `number` | | | `conversation_tags` | string | `list` | | | `conversation_assigned_users` | user | `list` | | | `conversation_assigned_teams` | string | `list` | | | `conversation_last_message_sent_at` | date-time | `datetime` | | | `conversation_last_message_out_sent_at` | date-time | `datetime` | | | `conversation_last_message_unresponded_to_sent_at` | date-time | `datetime` | | | `conversation_last_message_at` | date-time | `datetime` | | | `conversation_first_response_sent_at` | date-time | `datetime` | | | `conversation_first_response_time` | number | `number` | | | `conversation_first_response_created_by` | user | `list` | | | `conversation_last_response_created_by` | user | `list` | | | `conversation_last_message_direction` | string | `list` | `in`, `out` | | `conversation_direction` | string | `list` | `in`, `out` | | `conversation_outbound_message_count` | number | `number` | | | `conversation_customer_id` | string | `string_notanalyzed` | | | `conversation_campaign_id` | string | `string_notanalyzed` | | | `conversation_first_message_in_sent_at` | date-time | `datetime` | | | `conversation_first_message_in_direction_type` | string | `list` | `initial-in`, `initial-out`, `response-in`, `response-out`, `followup-in`, `followup-out` | | `conversation_first_message_in_channel` | string | `list` | `sms`, `chat`, `email`, `facebook`, `voice`, `twitter-dm`, `twitter-tweet`, `instagram`, `whatsapp` | | `conversation_first_message_out_sent_at` | date-time | `datetime` | | | `conversation_first_message_out_direction_type` | string | `list` | `initial-in`, `initial-out`, `response-in`, `response-out`, `followup-in`, `followup-out` | | `conversation_first_message_out_channel` | string | `list` | `sms`, `chat`, `email`, `facebook`, `voice`, `twitter-dm`, `twitter-tweet`, `instagram`, `whatsapp` | | `conversation_time_created_at` | date-time | `datetime` | | | `conversation_time_conversation_id` | string | `string_notanalyzed` | | | `conversation_time_created_by_teams` | string | `list` | | | `conversation_time_assigned_users` | user | `list` | | | `conversation_time_assigned_teams` | string | `list` | | | `conversation_time_touched` | string | `boolean` | | | `conversation_time_reopened` | string | `boolean` | | | `conversation_time_snoozed` | string | `boolean` | | | `conversation_time_resolved` | string | `boolean` | | | `conversation_time_message_at` | date-time | `datetime` | | | `conversation_time_message_time` | number | `number` | | | `conversation_time_messages_sent` | number | `number` | | | `conversation_time_note_at` | date-time | `datetime` | | | `conversation_time_note_time` | number | `number` | | | `conversation_time_notes_sent` | number | `number` | | | `conversation_time_handle_at` | date-time | `datetime` | | | `conversation_time_handle_time` | number | `number` | | | `conversation_time_channels` | string | `list` | `sms`, `chat`, `email`, `facebook`, `voice`, `twitter-dm`, `twitter-tweet`, `instagram`, `whatsapp` | | `conversation_default_lang` | string | `string_notanalyzed` | | | `conversation_sla_status` | string | `list` | `done`, `pending`, `paused` | | `conversation_sla_version_id` | string | `string_notanalyzed` | | | `conversation_sla_id` | string | `list` | | | `conversation_sla_breached` | boolean | `boolean` | | | `conversation_sla_breach_at` | date-time | `datetime` | | | `conversation_sla_satisfied_at` | date-time | `datetime` | | | `conversation_sla_breach_metric` | string | `list` | `firstResponse`, `nextReply`, `totalCustomerWaitTime`, `longestUnrespondedMessage`, `totalConversationOpenTime` | | `conversation_first_done_created_by` | user | `list` | | | `conversation_last_done_created_at` | date-time | `datetime` | | | `conversation_last_done_created_by` | user | `list` | | | `conversation_last_done_created_by_teams` | string | `list` | | | `conversation_reply_channel` | string | `list` | `sms`, `chat`, `email`, `facebook`, `voice`, `twitter-dm`, `twitter-tweet`, `instagram`, `whatsapp` | | `conversation_queue` | string | `list` | | | `conversation_external_queue` | string | `list` | `amazon-connect` | | `conversation_ended` | boolean | `boolean` | | | `conversation_ended_at` | date-time | `datetime` | | | `conversation_ended_reason` | string | `string` | | | `conversation_imported_at` | date-time | `datetime` | | | `conversation_imported` | boolean | `boolean` | | ### Other attributes | Attribute | Type | Operator group | Values | | ----------------- | ------ | -------------- | ------ | | `any_text` | string | `any` | | | `tracking_events` | string | `number` | | ### Kobject attributes | Attribute | Type | Operator group | Values | | --------------------- | --------- | -------------- | ------ | | `kobject_any_text` | string | `any` | | | `kobject_created_at` | date-time | `datetime` | | | `kobject_updated_at` | date-time | `datetime` | | | `kobject_imported_at` | date-time | `datetime` | | | `kobject_imported` | boolean | `boolean` | |