post https://api.kustomerapp.com/v1/customers/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.
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 |
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
GMTtimezone 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 attibutes on 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",
"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
}