Function customerSearch

customerSearch<ThrowOnError extends boolean = true>(
    options: Options<CustomerSearchData, ThrowOnError>,
): RequestResult<
    {
        data: {
            attributes: {
                createdAt: string;
                displayName: string;
                lastActivityAt: string;
                name: string;
                rev: number;
                updatedAt: string;
                verified: boolean;
            };
            id: string;
            links: { self: string };
            relationships: {
                org: { data: { id: string; type: string }; links: { self: string } };
            };
            type: string;
        }[];
        links: {
            first: string;
            last: string;
            next: string;
            prev: null
            | string;
            self: string;
        };
        meta: {
            aggregations: { [key: string]: unknown };
            page: number;
            pageSize: number;
            total: number;
            totalPages: number;
        };
    },
    unknown,
    ThrowOnError,
>

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.

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

Type Parameters

ThrowOnError extends boolean = true

Parameters

options: Options<CustomerSearchData, ThrowOnError>

Returns RequestResult<
    {
        data: {
            attributes: {
                createdAt: string;
                displayName: string;
                lastActivityAt: string;
                name: string;
                rev: number;
                updatedAt: string;
                verified: boolean;
            };
            id: string;
            links: { self: string };
            relationships: {
                org: { data: { id: string; type: string }; links: { self: string } };
            };
            type: string;
        }[];
        links: {
            first: string;
            last: string;
            next: string;
            prev: null
            | string;
            self: string;
        };
        meta: {
            aggregations: { [key: string]: unknown };
            page: number;
            pageSize: number;
            total: number;
            totalPages: number;
        };
    },
    unknown,
    ThrowOnError,
>

Function customerSearch

Filter on dates

Example of search criteria with local date

Note

Example of search criteria with UTC date

Filter on standard attributes

Example of search criteria with standard attributes

Filter on custom attributes for standard Objects

Example of search criteria with custom attributes

Filter on custom attributes for custom Objects

Examples

Sort on customer attributes

Example of sort with customer attributes

Note

Standard attributes JSON Schema

Type Parameters

Parameters

Settings

On This Page