Create customer search

Searches across customer data with criteria based on standard Object data and any custom attribute data for standard Objects, including Message, Conversation, and Company objects. Standard object data, custom object data, and conversation time data is limited to objects that have an updatedAt more recent than in the past 2 years. To query for older, archived data for standard and custom objects, see the Archive Search API. Older conversation time data is not available via search.

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

Filter on standard attributes

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

Example of search criteria with standard attributes

[
  {"customer_updated_at": {"gte": "2016-06-24" }},
  {"conversation_status": {"equals": "done" }}
]

Filter on custom attributes for standard Objects

You can query custom attributes on standard Objects with the following syntax: <<standard_object_name>>_custom_<<custom_field_name>>.

Example of search criteria with custom attributes

{ "customer_custom_myCustomStr": { "equals": "some value" }}
{ "message_custom_myCustomNum": { "gte": 5 }}

Filter on custom attributes for custom Objects

You can query custom attributes for custom Object with the following syntax: kobject_custom_<<klass_name>>_<<custom_field_name>>.

Examples

{ "kobject_custom_myKlass_myCustomNum": { "gte": 5 }}

Sort on customer attributes

You can sort based on the following customer 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

Example of sort with customer attributes

{"sort": [{"customer_updated_at": "asc"}]}
{"sort": [{"customer_gender": "asc"}, {"customer_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.

Standard attributes JSON Schema

{
  "type": "object",
  "properties": {
    "customer_any_text": {
      "type": "string",
      "operator": "any"
    },
    "customer_name": {
      "type": "string",
      "operator": "string"
    },
    "customer_gender": {
      "type": "string",
      "enum": ["m", "f"],
      "operator": "list"
    },
    "customer_presence": {
      "type": "string",
      "enum": ["online", "offline", "idle"],
      "operator": "list"
    },
    "customer_email": {
      "type": "string",
      "format": "email",
      "operator": "string"
    },
    "customer_shared_email": {
      "type": "string",
      "format": "email",
      "operator": "string"
    },
    "customer_phone": {
      "type": "string",
      "pattern": "^\\+?[1-9]\\d{1,14}$",
      "operator": "string"
    },
    "customer_shared_phone": {
      "type": "string",
      "pattern": "^\\+?[1-9]\\d{1,14}$",
      "operator": "string"
    },
    "customer_urls": {
      "type": "string",
      "operator": "string"
    },
    "customer_address": {
      "type": "string",
      "operator": "string"
    },
    "customer_locale": {
      "type": "string",
      "operator": "string"
    },
    "customer_activity_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "customer_last_seen_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "customer_signed_up_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "customer_last_message_sent_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "customer_last_message_out_sent_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "customer_last_message_unresponded_to_sent_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "customer_last_message_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "customer_externalId": {
      "type": "string",
      "operator": "string_notanalyzed"
    },
    "customer_shared_externalId": {
      "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_modified_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "customer_created_by": {
      "$ref": "#/definitions/user",
      "operator": "list"
    },
    "customer_modified_by": {
      "$ref": "#/definitions/user",
      "operator": "list"
    },
    "customer_satisfaction_avg_score": {
      "type": "number",
      "operator": "number"
    },
    "customer_satisfaction_avg_rating": {
      "type": "number",
      "operator": "number"
    },
    "customer_conversations_count": {
      "type": "number",
      "operator": "number"
    },
    "customer_status": {
      "type": "string",
      "enum": ["snoozed", "open", "done"],
      "operator": "list"
    },
    "customer_progressive_status": {
      "type": "string",
      "enum": ["snoozed", "open", "done"],
      "operator": "list"
    },
    "customer_active_users": {
      "$ref": "#/definitions/user",
      "operator": "list"
    },
    "customer_watchers": {
      "$ref": "#/definitions/user",
      "operator": "list"
    },
    "customer_tags": {
      "type": "string",
      "operator": "list"
    },
    "customer_sentiment": {
      "type": "string",
      "enum": ["happy", "unhappy", "indifferent"],
      "operator": "list"
    },
    "customer_social_type": {
      "type": "string",
      "enum": ["facebook", "instagram", "whatsapp", "linkedin", "pinterest", "twitter"],
      "operator": "list"
    },
    "customer_social_userid": {
      "type": "string",
      "operator": "string_notanalyzed"
    },
    "customer_social_username": {
      "type": "string",
      "operator": "string_notanalyzed"
    },
    "customer_shared_social_type": {
      "type": "string",
      "enum": ["facebook", "instagram", "whatsapp", "linkedin", "pinterest", "twitter"],
      "operator": "list"
    },
    "customer_shared_social_userid": {
      "type": "string",
      "operator": "string_notanalyzed"
    },
    "customer_shared_social_username": {
      "type": "string",
      "operator": "string_notanalyzed"
    },
    "customer_default_lang": {
      "type": "string",
      "operator": "string_notanalyzed"
    },
    "customer_imported_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "customer_imported": {
      "type": "boolean",
      "operator": "boolean"
    },
    "company_any_text": {
      "type": "string",
      "operator": "any"
    },
    "company_name": {
      "type": "string",
      "operator": "string"
    },
    "company_tags": {
      "type": "string",
      "operator": "list"
    },
    "company_default_lang": {
      "type": "string",
      "operator": "string_notanalyzed"
    },
    "company_imported_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "company_imported": {
      "type": "boolean",
      "operator": "boolean"
    },
    "message_any_text": {
      "type": "string",
      "operator": "any"
    },
    "message_body": {
      "type": "string",
      "operator": "text"
    },
    "message_channel": {
      "type": "string",
      "enum": ["sms", "chat", "email", "facebook", "voice", "twitter-dm", "twitter-tweet", "instagram", "whatsapp"],
      "operator": "list"
    },
    "message_size": {
      "type": "number",
      "operator": "number"
    },
    "message_direction": {
      "type": "string",
      "enum": ["in", "out"],
      "operator": "boolean"
    },
    "message_sent_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "message_created_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "message_updated_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "message_created_by": {
      "$ref": "#/definitions/user",
      "operator": "list"
    },
    "message_modified_by": {
      "$ref": "#/definitions/user",
      "operator": "list"
    },
    "message_sentiment": {
      "type": "string",
      "enum": ["happy", "unhappy", "indifferent"],
      "operator": "list"
    },
    "message_customer_id": {
      "type": "string",
      "operator": "string_notanalyzed"
    },
    "message_status": {
      "type": "string",
      "enum": ["sent", "received", "error"],
      "operator": "list"
    },
    "message_error_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "message_error_title": {
      "type": "string",
      "operator": "string"
    },
    "message_external_id": {
      "type": "string",
      "operator": "string_notanalyzed"
    },
    "message_direction_type": {
      "type": "string",
      "enum": ["initial-in", "initial-out", "response-in", "response-out", "followup-in", "followup-out"],
      "operator": "list"
    },
    "message_created_by_teams": {
      "type": "string",
      "operator": "string_notanalyzed"
    },
    "message_redacted": {
      "type": "string",
      "operator": "boolean"
    },
    "message_redacted_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "message_imported_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "message_imported": {
      "type": "boolean",
      "operator": "boolean"
    },
    "message_recipients": {
      "type": "string",
      "operator": "string"
    },
    "message_sender": {
      "type": "string",
      "operator": "string"
    },
    "message_shortcuts": {
      "type": "string",
      "operator": "string_notanalyzed"
    },
    "message_subject": {
      "type": "string",
      "operator": "text"
    },
    "message_source": {
      "type": "string",
      "enum": ["bulk"],
      "operator": "list"
    },
    "message_attachment_count": {
      "type": "number",
      "operator": "number"
    },
    "message_auto": {
      "type": "string",
      "operator": "boolean"
    },
    "message_lang": {
      "type": "string",
      "operator": "string_notanalyzed"
    },
    "note_any_text": {
      "type": "string",
      "operator": "any"
    },
    "note_body": {
      "type": "string",
      "operator": "text"
    },
    "note_created_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "note_modified_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "note_updated_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "note_created_by": {
      "$ref": "#/definitions/user",
      "operator": "list"
    },
    "note_modified_by": {
      "$ref": "#/definitions/user",
      "operator": "list"
    },
    "note_deleted": {
      "$ref": "#/definitions/user",
      "operator": "boolean"
    },
    "note_user_mentions": {
      "$ref": "#/definitions/user",
      "operator": "list"
    },
    "note_team_mentions": {
      "type": "string",
      "pattern": "^(?=[A-Fa-f\\d]{24}$)(\\d+[A-Fa-f]|[A-Fa-f]+\\d)",
      "collection": "teams",
      "operator": "list"
    },
    "note_attachment_count": {
      "$ref": "#/definitions/user",
      "operator": "number"
    },
    "note_external_id": {
      "type": "string",
      "operator": "string_notanalyzed"
    },
    "note_customer_id": {
      "type": "string",
      "operator": "string_notanalyzed"
    },
    "note_conversation_id": {
      "type": "string",
      "operator": "string_notanalyzed"
    },
    "note_lang": {
      "type": "string",
      "operator": "string_notanalyzed"
    },
    "note_imported_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "note_imported": {
      "type": "boolean",
      "operator": "boolean"
    },
    "conversation_any_text": {
      "type": "string",
      "operator": "any"
    },
    "conversation_name": {
      "type": "string",
      "operator": "string"
    },
    "conversation_sentiment": {
      "type": "string",
      "enum": ["happy", "unhappy", "indifferent"],
      "operator": "list"
    },
    "conversation_status": {
      "type": "string",
      "enum": ["snoozed", "open", "done"],
      "operator": "list"
    },
    "conversation_sub_status": {
      "type": "string",
      "operator": "string_notanalyzed"
    },
    "conversation_created_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "conversation_updated_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "conversation_modified_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "conversation_modified_by": {
      "$ref": "#/definitions/user",
      "operator": "list"
    },
    "conversation_message_count": {
      "type": "number",
      "operator": "number"
    },
    "conversation_note_count": {
      "type": "number",
      "operator": "number"
    },
    "conversation_satisfaction_survey_id": {
      "type": "string",
      "operator": "list"
    },
    "conversation_satisfaction_sent_by": {
      "$ref": "#/definitions/user",
      "operator": "list"
    },
    "conversation_satisfaction_sent_by_teams": {
      "type": "string",
      "pattern": "^(?=[A-Fa-f\\d]{24}$)(\\d+[A-Fa-f]|[A-Fa-f]+\\d)",
      "collection": "teams",
      "operator": "list"
    },
    "conversation_satisfaction_created_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "conversation_satisfaction_score": {
      "type": "number",
      "operator": "number"
    },
    "conversation_satisfaction_rating": {
      "type": "number",
      "operator": "number"
    },
    "conversation_satisfaction_status": {
      "type": "string",
      "enum": [
        "canceled",
        "scheduled",
        "offered",
        "unresponded",
        "rated",
        "commented"
      ],
      "operator": "list"
    },
    "conversation_channels": {
      "type": "string",
      "enum": ["sms", "chat", "email", "facebook", "voice", "twitter-dm", "twitter-tweet", "instagram", "whatsapp"],
      "operator": "list"
    },
    "conversation_satisfaction": {
      "type": "string",
      "operator": "string"
    },
    "conversation_priority": {
      "type": "integer",
      "operator": "number",
      "minimum": 1,
      "maximum": 5
    },
    "conversation_tags": {
      "type": "string",
      "operator": "list"
    },
    "conversation_assigned_users": {
      "$ref": "#/definitions/user",
      "operator": "list"
    },
    "conversation_assigned_teams": {
      "type": "string",
      "pattern": "^(?=[A-Fa-f\\d]{24}$)(\\d+[A-Fa-f]|[A-Fa-f]+\\d)",
      "collection": "teams",
      "operator": "list"
    },
    "conversation_last_message_sent_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "conversation_last_message_out_sent_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "conversation_last_message_unresponded_to_sent_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "conversation_last_message_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "conversation_first_response_sent_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "conversation_first_response_time": {
      "type": "number",
      "operator": "number"
    },
    "conversation_first_response_created_by": {
      "$ref": "#/definitions/user",
      "operator": "list"
    },
    "conversation_last_response_created_by": {
      "$ref": "#/definitions/user",
      "operator": "list"
    },
    "conversation_last_message_direction": {
      "type": "string",
      "enum": ["in", "out"],
      "operator": "list"
    },
    "conversation_direction": {
      "type": "string",
      "enum": ["in", "out"],
      "operator": "list"
    },
    "conversation_outbound_message_count": {
      "type": "number",
      "operator": "number"
    },
    "conversation_customer_id": {
      "type": "string",
      "operator": "string_notanalyzed"
    },
    "conversation_campaign_id": {
      "type": "string",
      "operator": "string_notanalyzed"
    },
    "conversation_first_message_in_sent_at": {
      "format": "date-time",
      "operator": "datetime"
    },
    "conversation_first_message_in_direction_type": {
      "type": "string",
      "enum": ["initial-in", "initial-out", "response-in", "response-out", "followup-in", "followup-out"],
      "operator": "list"
    },
    "conversation_first_message_in_channel": {
      "type": "string",
      "enum": ["sms", "chat", "email", "facebook", "voice", "twitter-dm", "twitter-tweet", "instagram", "whatsapp"],
      "operator": "list"
    },
    "conversation_first_message_out_sent_at": {
      "format": "date-time",
      "operator": "datetime"
    },
    "conversation_first_message_out_direction_type": {
      "type": "string",
      "enum": ["initial-in", "initial-out", "response-in", "response-out", "followup-in", "followup-out"],
      "operator": "list"
    },
    "conversation_first_message_out_channel": {
      "type": "string",
      "enum": ["sms", "chat", "email", "facebook", "voice", "twitter-dm", "twitter-tweet", "instagram", "whatsapp"],
      "operator": "list"
    },
    "conversation_time_created_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "conversation_time_conversation_id": {
      "type": "string",
      "operator": "string_notanalyzed"
    },
    "conversation_time_created_by_teams": {
      "type": "string",
      "pattern": "^(?=[A-Fa-f\\d]{24}$)(\\d+[A-Fa-f]|[A-Fa-f]+\\d)",
      "collection": "teams",
      "operator": "list"
    },
    "conversation_time_assigned_users": {
      "$ref": "#/definitions/user",
      "operator": "list"
    },
    "conversation_time_assigned_teams": {
      "type": "string",
      "pattern": "^(?=[A-Fa-f\\d]{24}$)(\\d+[A-Fa-f]|[A-Fa-f]+\\d)",
      "collection": "teams",
      "operator": "list"
    },
    "conversation_time_touched": {
      "type": "string",
      "operator": "boolean"
    },
    "conversation_time_reopened": {
      "type": "string",
      "operator": "boolean"
    },
    "conversation_time_snoozed": {
      "type": "string",
      "operator": "boolean"
    },
    "conversation_time_resolved": {
      "type": "string",
      "operator": "boolean"
    },
    "conversation_time_message_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "conversation_time_message_time": {
      "type": "number",
      "operator": "number"
    },
    "conversation_time_messages_sent": {
      "type": "number",
      "operator": "number"
    },
    "conversation_time_note_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "conversation_time_note_time": {
      "type": "number",
      "operator": "number"
    },
    "conversation_time_notes_sent": {
      "type": "number",
      "operator": "number"
    },
    "conversation_time_handle_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "conversation_time_handle_time": {
      "type": "number",
      "operator": "number"
    },
    "conversation_time_channels": {
      "type": "string",
      "enum": ["sms", "chat", "email", "facebook", "voice", "twitter-dm", "twitter-tweet", "instagram", "whatsapp"],
      "operator": "list"
    },
    "conversation_default_lang": {
      "type": "string",
      "operator": "string_notanalyzed"
    },
    "any_text": {
      "type": "string",
      "operator": "any"
    },
    "tracking_events": {
      "type": "string",
      "operator": "number"
    },
    "conversation_sla_status": {
      "type": "string",
      "enum": ["done", "pending", "paused"],
      "operator": "list"
    },
    "conversation_sla_version_id": {
      "type": "string",
      "operator": "string_notanalyzed"
    },
    "conversation_sla_id": {
      "type": "string",
      "operator": "list"
    },
    "conversation_sla_breached": {
      "type": "boolean",
      "operator": "boolean"
    },
    "conversation_sla_breach_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "conversation_sla_satisfied_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
     "conversation_sla_breach_metric": {
      "type": "string",
      "enum": [
        "firstResponse",
        "nextReply",
        "totalCustomerWaitTime",
        "longestUnrespondedMessage",
        "totalConversationOpenTime"
      ],
      "operator": "list"
    },
    "conversation_first_done_created_by": {
      "$ref": "#/definitions/user",
      "operator": "list"
    },
    "conversation_last_done_created_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "conversation_last_done_created_by": {
      "$ref": "#/definitions/user",
      "operator": "list"
    },
    "conversation_last_done_created_by_teams": {
      "type": "string",
      "pattern": "^(?=[A-Fa-f\\d]{24}$)(\\d+[A-Fa-f]|[A-Fa-f]+\\d)",
      "collection": "teams",
      "operator": "list"
    },
    "conversation_reply_channel": {
      "type": "string",
      "enum": ["sms", "chat", "email", "facebook", "voice", "twitter-dm", "twitter-tweet", "instagram", "whatsapp"],
      "operator": "list"
    },
    "conversation_queue": {
      "type": "string",
      "pattern": "^(?=[A-Fa-f\\d]{24}$)(\\d+[A-Fa-f]|[A-Fa-f]+\\d)",
      "collection": "queues",
      "operator": "list"
    },
    "conversation_external_queue": {
      "type": "string",
      "enum": ["amazon-connect"],
      "operator": "list"
    },
    "conversation_ended": {
      "type": "boolean",
      "operator": "boolean"
    },
    "conversation_ended_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "conversation_ended_reason": {
      "type": "string",
      "operator": "string"
    },
    "conversation_imported_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "conversation_imported": {
      "type": "boolean",
      "operator": "boolean"
    },
    "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"
    },
    "kobject_imported_at": {
      "type": "string",
      "format": "date-time",
      "operator": "datetime"
    },
    "kobject_imported": {
      "type": "boolean",
      "operator": "boolean"
    }
  },
  "definitions": {
    "user": {
      "type": "string",
      "pattern": "^(?=[A-Fa-f\\d]{24}$)(\\d+[A-Fa-f]|[A-Fa-f]+\\d)",
      "collection": "users"
    }
  },
  "additionalProperties": false
}