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.

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

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:

{ "<attribute>": { "<operator>": <value> } }

Attribute names are <object>_<attribute> 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 tables.

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

{
  "queryContext": "customer",
  "and": [{ "customer_custom_loyaltyTierStr": { "equals": "gold" } }],
  "or": [
    { "conversation_status": { "equals": "open" } },
    { "conversation_status": { "equals": "snoozed" } }
  ],
  "not": [{ "customer_email": { "contains": "@acme.example" } }]
}

+{
+  "queryContext": "conversation",
+  "and": [
+    { "conversation_status": { "equals": "open" } },
+    { "conversation_priority": { "gte": 4 } },
+    { "conversation_created_at": { "gte": "2026-10-01" } }
+  ],
+  "timeZone": "America/New_York"
+}

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

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:

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

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

• Rate limit. Machine users (API keys) can make 100 search requests per minute. See 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 apply. The full JSON schema is also in the search endpoint's reference.

Customer attributes

Company attributes

Message attributes

Note attributes

Conversation attributes

Other attributes

Kobject attributes