Search across all customer data using criteria based on standard objects including message, conversation, company as well as your custom kobject data.

Any one of the following roles is required for this endpoint:

|Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.search.read|org.permission.search.create| |org.admin.search.read|org.permission.search.update| ||org.permission.search_global.create| ||org.permission.search_preview.create|

Standard Fields 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",
        "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
}

Filtering on Dates

Dates should be in the format of a local date YYYY-MM-DD or as a UTC date. If a timezone is included in the query, a local date will be adjusted for to account for the included timezone. UTC dates will not be timezone adjusted.
An example of search criteria including a date is:

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

Excluding a timezone is equivalent to using the timezone GMT.
An example of search criteria including a UTC date is:

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

Filtering on Standard Fields

For a list of standard fields available see #definitions/customer-search-fields

Example

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

Custom Fields on Standard Objects

Custom objects can be queried on standard objects as well using the following syntax: <<standard_object_name>>custom<<custom_field_name>>

Example

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

Custom Objects

Custom objects work in a similar fashion to custom fields.

kobject_custom_<<klass_name>>_<<custom_field_name>>

Examples

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

Sorting

Its possible to sort 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

Examples

{"sort": [{"customer_updated_at": "asc"}]}
{"sort": [{"customer_gender": "asc"}, {"customer_created_at": "asc"}]}

Note

It is not possible to sort on other standard object attributes.

Pagination

As there is a hard limit on the page number of 100, you may sometimes want to page through more records. Perhaps you want to get an initial snapshot of data and then subsequently keep them up to date. One option to solve the pagination limitation is to write a query with criteria based on the updated_at field of the object. You can then use that information in subsequent API calls based on the last updated_at of the response.