Create customer archive search

post/v1/customers/archive/search
Requires any one of these rolesAbout roles
org.permission.search.createorg.permission.search.updateorg.permission.search_global.createorg.permission.search_preview.create
Legacyorg.user.search.readorg.admin.search.read

The API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.

Searches across all customer data with criteria based on a limited number of attributes on standard objects, including Message, Conversation, and Company objects, and on custom objects. Returns standard objects and custom objects older than 2 years ago that are unavailable in standard searches.

Filter on dates

You can filter by dates in either a local date YYYY-MM-DD format or a UTC date format. If you include a timezone in the query, a local date will be adjusted to account for the included timezone. UTC dates will not be timezone adjusted.

Example of search criteria with local date

{
    "and": [
        {
            "conversation_created_at": {
                "lte": "2020-11-19"
            }
        }
    ],
    "queryContext": "conversation",
    "timeZone": "America/New_York"
}

Note

The default GMT timezone is applied when you exclude a timezone.

Example of search criteria with UTC date

{
    "and": [
        {
            "conversation_created_at": {
                "lte": "2020-11-20T16:34:00.000Z"
            }
        }
    ],
    "queryContext": "conversation"
}

Filtering

For a list of available standard attributes, see Standard attributes JSON schema.

Example of search criteria with standard attributes

[
  {"conversation_updated_at": {"gte": "2016-06-24" }},
  {"conversation_customer_id": {"equals": "65f49506237963001f01a391" }}
]

Sort on attributes

You can sort based on the following attributes:

conversation_created_at
conversation_updated_at
conversation_customer_id
conversation_deleted
customer_companyId
customer_created_at
customer_updated_at
customer_deleted
message_id
message_created_at
message_updated_at
kobject_created_at
kobject_updated_at
^kobject.*_created_at$
^kobject.*_updated_at$
company_created_at
company_updated_at

Example of sort with attributes

{"sort": [{"conversation_created_at": "asc"}]}
{"sort": [{"message_id": "asc"}, {"message_created_at": "asc"}]}

Note

Sorting based on other standard Object attributes is unavailable.

Pagination

There is a hard limit of 100 for the maximum number of pages.

There may be cases where you want to page through more records. For example, let's say you'd like to get an initial snapshot of data and then update the data.

To work around the pagination limit, you can write a query based on the updated_at attribute for a standard Object. You can then use the returned information in following API requests based on the last updated_at value from the response.

Filterable attributes JSON Schema

{
  "type": "object",
  "properties": {
    "customer_any_text_new": {
      "type": "string",
      "operator": "any"
    },
    "customer_id": {
      "type": "string",
      "operator": "string_notanalyzed"
    },
    "customer_created_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "customer_updated_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "customer_companyId": {
      "type": "string",
      "operator": "string_notanalyzed"
    },
    "company_created_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "company_updated_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "message_any_text": {
      "type": "string",
      "operator": "any"
    },
    "message_created_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "message_updated_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "message_conversation_id": {
      "type": "string",
      "operator": "string_notanalyzed"
    },
    "conversation_any_text": {
      "type": "string",
      "operator": "any"
    },
    "conversation_created_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "conversation_updated_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "conversation_customer_id": {
      "type": "string",
      "operator": "string_notanalyzed"
    },
    "kobject_any_text": {
      "type": "string",
      "operator": "any"
    },
    "kobject_created_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "kobject_updated_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
  },
  "additionalProperties": false
}
About this resource

Search

Search finds customers, conversations, messages, companies, notes, custom objects and other records that match a set of criteria, the same way saved searches do in the agent desktop.

Search is how you query Kustomer by content rather than by ID: "open conversations with priority 4 or higher", "customers whose loyalty tier is gold", "orders over $100". It runs the same engine as the saved searches agents use in the agent desktop. You send criteria and get back one page of matching records.

Despite its path, POST /v1/customers/search isn't limited to customers. queryContext picks what to return: customer, conversation, message, company, note, kobject, kobject_<klassName>, conversation_time, work_session or work_item.

Criteria

The body combines criteria in and (every one must match), or (at least one must match) and not (exclude matches). Each criterion maps one attribute to one operator and value, such as { "conversation_status": { "equals": "open" } }. Attribute names are <object>_<attribute> in snake case, and you can filter on related objects, for example a customer search on conversation_status. Custom attributes use <object>_custom_<name>, or kobject_custom_<klassName>_<name> for custom objects, and their suffix decides which operators apply. Which operators an attribute accepts (equals, contains, in, gte, is_set and so on) depends on its type; see search concepts for the full list of attributes and operators.

Dates can be local (2026-10-01), interpreted in timeZone (GMT if omitted), or exact UTC timestamps. fields limits the attributes returned (up to 20), and includeDeleted includes deleted records.

Live and archived data

Endpoint Covers
Standard search Records updated in the past two years, with every standard and custom attribute.
Archive search Records older than that, filterable on a small set of attributes such as IDs, created_at, updated_at and any-text matches. Supports customer, conversation, message, company and KObject contexts.

Conversation time data older than two years isn't searchable at all.

Which endpoint to use

To Call
Find records that match criteria POST /v1/customers/search
Find records older than two years POST /v1/customers/archive/search

Results page with page and pageSize (up to 500), and only the first 10,000 matches can be read: a request where page × pageSize is over 10,000 fails with 400. To export more, split the query into windows on an updated_at attribute and run one search per window (search recipes shows how). idsOnly=true returns just the matching IDs, which is faster for large syncs. Pass a saved search's ID as id to run its stored query. Search is indexed asynchronously, so a record you just wrote may take a moment to appear; read it by ID when you need your own writes. API keys can make 100 search requests per minute; see rate limits.

RelatedSearch conceptsSearch recipesSaved searches

Query parameters

pageinteger

Page number of results to return.

Example 1
pageSizeinteger

Number of results to return per page.

Example 100
idsOnlyboolean

Set to true to return only matching IDs from search results.

Example false
idstring

Saved search ID used to execute a stored query before searching.

Example "60254e3ec413ae00571e3c96"

Request body

application/jsonrequired

## Example request

Creates a query to retrieve the last updatedAt attribute to use in a subsequent request.

json { "and": [ { "customer_updated_at": { "gte": "2016-01-01" } } ], "sort" : [{"customer_updated_at": "asc"}], "queryContext": "customer", "or":[] }

## Example of next request

Uses the returned updatedAt value from the previous request to page through all customer data and keep data up to date.

json { "and": [ { "customer_updated_at": { "gte": "2016-07-27T22:30:48.939Z" } } ], "sort" : [{"customer_updated_at": "asc"}], "queryContext": "customer", "or":[] }

queryContextstring
pattern ^(message|conversation|customer|kobject|kobject_.*|company)$
includeDeletedboolean
timeZonestring
anyOf
anyOf
anyOf
anyOf

Responses

Success

objectrequired
array<object>required
objectrequired