Advanced search
Advanced search is active when the advanced_search parameter is set to 1:
/api/v2/calls.json?advanced_search=1
To support comparison operators like "ends with" or "is not empty", each filter is passed as a URI parameter in the format:
PARAM_NAME__OPERATOR=VALUE
Where:
PARAM_NAMEis the name of the attribute, likephone_numberoruser_name. See Search parameters.OPERATORis a comparison operator, likeincludesorlower_than. The operators depend on the type of the parameter. See Comparison operators.VALUEis the value to compare with. A value is always required, even for operators likeis_empty. In that case, pass1or any other value; it is ignored.
Two underscore characters (__) separate the attribute name from the operator.
Example:
/api/v2/calls.json?advanced_search=1&phone_number__includes=1234&user_name__equal_to=J%20Smith
This is equivalent to:
("phone_number" INCLUDES "1234") AND ("user_name" EQUAL_TO "J Smith")
A space character is encoded as %20 in the URI.
When paging through advanced search results, follow next_url from the response. It carries a
continuation_token parameter that identifies the position of the next page; do not build the
URL of the next page yourself.
An invalid filter (unknown parameter, unknown operator, value in a wrong format, or an invalid
UUID) is answered with 400 Bad Request and the error InvalidParameter.
Search parameters
The parameters available to a role are the ones shown in the Advanced Search tab of the web
portal for that role. The complete list follows. Custom field parameters embed the ID of the field
in the parameter name: custom_field__<UUID> for the value, and custom_field_label__<UUID> for
the threshold label of a number field. The type of a custom field parameter depends on the type of
the field.
Call
| Parameter | Type | Description |
|---|---|---|
| acd_id | text_choice | Call - ACD ID |
| acd_name | text_choice | Call - ACD Name |
| acd_number | text_choice | Call - ACD Number |
| agent_id | string | Call - Agent ID |
| agent_name | string | Call - Agent Name |
| broadworks_group_id | string | Call - Broadworks Group ID |
| broadworks_sp_id | string | Call - Broadworks SP ID |
| broadworks_user_id | string | Call - Broadworks User ID |
| call_id | uuid | Call - ID |
| call_state | choice | Call - State |
| call_summary | string_query | Call - Summary |
| call_topic_id | choice | Call - Topic |
| category_id | choice | Call - Tag |
| cisco_phone_ip | string | Call - Cisco Phone IP Address |
| cisco_refci | string | Call - Cisco xRefCi |
| client_id | choice | Call - Client |
| confidential | bool | Call - Confidential Flag |
| date | date | Call - Date |
| datetime | datetime | Call - Date/Time |
| direction | choice | Call - Direction |
| disconnect_cause | choice | Call - Disconnect Cause |
| disconnect_date | date | Call - Disconnect Date |
| disconnect_datetime | datetime | Call - Disconnect Date/Time |
| do_not_delete | bool | Call - Do-Not-Delete Flag |
| duration | duration | Call - Duration |
| encrypt_fingerprint | string | Call - Encryption Fingerprint |
| evaluation_report_is_passed | bool | Call - Evaluation Report - Pass Status |
| evaluation_report_score | number | Call - Evaluation Report - Score |
| evaluation_report_status | choice | Call - Evaluation Report - Status |
| evaluation_reports_count | number | Call - Evaluation Reports Count |
| file_path | string | Call - File Path |
| highlighted_redaction_rule_id | choice | Call - Highlighted Redaction By Rule |
| interaction_call_idx | number | Call - Interaction Segment Number |
| interaction_id | uuid | Call - Interaction ID |
| interaction_total_calls | number | Call - Interaction Total Segments |
| is_highlighted_redaction | bool | Call - Highlighted Redaction |
| is_redacted | bool | Call - Redacted |
| keyword_id | choice | Call - Keyword |
| metaswitch_extension | string | Call - Metaswitch User Extension |
| metaswitch_group | string | Call - Metaswitch Group Name |
| metaswitch_system | string | Call - Metaswitch System Name |
| metaswitch_user | string | Call - Metaswitch User Name |
| notes | string | Call - Notes |
| notes_count | number | Call - Notes Count (Incl. Replies) |
| notes_count_excluding_replies | number | Call - Notes Count (Excl. Replies) |
| notes_count_replies | number | Call - Notes Count (Replies Only) |
| orig_calling_number | string | Call - Orig. Calling Number |
| orig_dialed_number | string | Call - Dialed Digits |
| pbx_call_id | string | Call - PBX Call ID |
| pbx_tracking_id | string | Call - PBX Tracking ID |
| phone_id | string | Call - Phone ID |
| phone_id_from | string | Call - Caller Phone ID |
| phone_id_to | string | Call - Called Phone ID |
| phone_ip_address | string | Call - IP Address |
| phone_ip_address_from | string | Call - Caller IP Address |
| phone_ip_address_to | string | Call - Called IP Address |
| phone_name | string | Call - Phone Name |
| phone_name_from | string | Call - Caller Phone Name |
| phone_name_to | string | Call - Called Phone Name |
| phone_number | string | Call - Phone Number |
| phone_number_from | string | Call - Caller Phone Number |
| phone_number_to | string | Call - Called Phone Number |
| protocol_call_direction | choice | Call - PBX Call Direction |
| record_state | choice | Call - Recording State |
| redaction_rule_id | choice | Call - Redacted By Rule |
| redirected_from_id | string | Call - Redirected From Phone ID |
| redirected_from_name | string | Call - Redirected From Phone Name |
| redirected_from_number | string | Call - Redirected From Phone Number |
| redirected_to_id | string | Call - Redirected To Phone ID |
| redirected_to_name | string | Call - Redirected To Phone Name |
| redirected_to_number | string | Call - Redirected To Phone Number |
| rtp_codec_name | string | Call - RTP Stream - Codec Name |
| rtp_codec_type | number | Call - RTP Stream - Codec Type |
| screen_recordings_count | number | Call - Screen Recordings Count |
| sentiment_agent_label | choice | Call - Sentiment Agent Label |
| sentiment_agent_score | number | Call - Sentiment Agent Score |
| sentiment_customer_label | choice | Call - Sentiment Customer Label |
| sentiment_customer_score | number | Call - Sentiment Customer Score |
| sentiment_details | string_query | Call - Sentiment Details |
| sentiment_label | choice | Call - Sentiment Label |
| sentiment_score | number | Call - Sentiment Score |
| shared_by_user | choice | Call - Shared By (User) |
| shared_with_user | choice | Call - Shared With (User) |
| topic_match | multi_param_number | Call - Topic Match |
| total_files_size | number | Call - File Size |
| transcript | string_query | Call - Transcript |
| transcript_status | choice | Call - Transcript - Status |
| transcript_words_count | number | Call - Transcript - Total Words |
| voip_protocol | choice | Call - Voip Protocol |
custom_field__<UUID> |
string | Call - Custom Field (text type) |
custom_field__<UUID> |
number | Call - Custom Field (number type) |
custom_field__<UUID> |
text_choice | Call - Custom Field (option type) |
custom_field__<UUID> |
date | Call - Custom Field (date type) |
custom_field_label__<UUID> |
choice | Call - Custom Field Label (number type with thresholds) |
Call note
| Parameter | Type | Description |
|---|---|---|
| note | string | Call Note - Note |
| note_created_at | datetime | Call Note - Created At |
| note_is_pinned | bool | Call Note - Pinned |
| note_is_resolved | bool | Call Note - Resolved |
| note_pos_begin | duration | Call Note - Audio Position Begin |
| note_pos_end | duration | Call Note - Audio Position End |
| note_user | choice | Call Note - Created By |
| note_user_id | uuid | Call Note - Created By User ID |
Evaluation report
| Parameter | Type | Description |
|---|---|---|
| evaluation_report_additional_feedback | string | Evaluation Report - Feedback - Additional |
| evaluation_report_agent_user_id | choice | Evaluation Report - Agent |
| evaluation_report_created_date | date | Evaluation Report - Date Created |
| evaluation_report_created_datetime | date | Evaluation Report - Date/Time Created |
| evaluation_report_description | string | Evaluation Report - Description |
| evaluation_report_evaluator_user_id | choice | Evaluation Report - Evaluator |
| evaluation_report_feedback | string | Evaluation Report - Feedback (Combined) |
| evaluation_report_form | choice | Evaluation Report - Form |
| evaluation_report_form_id | uuid | Evaluation Report - Form ID |
| evaluation_report_group_id | choice | Evaluation Report - Group |
| evaluation_report_id | uuid | Evaluation Report - ID |
| evaluation_report_improvement_feedback | string | Evaluation Report - Feedback - Improvement Areas |
| evaluation_report_is_passed | bool | Evaluation Report - Pass Status |
| evaluation_report_modified_date | date | Evaluation Report - Date Modified |
| evaluation_report_modified_datetime | date | Evaluation Report - Date/Time Modified |
| evaluation_report_name | string | Evaluation Report - Name |
| evaluation_report_score | number | Evaluation Report - Score |
| evaluation_report_status | choice | Evaluation Report - Status |
| evaluation_report_strengths_feedback | string | Evaluation Report - Feedback - Strengths |
| evaluation_report_type | choice | Evaluation Report - Type |
Group
| Parameter | Type | Description |
|---|---|---|
| group | choice | Group |
| group_id | uuid | Group - ID |
| group_manager_count | number | Group - Manager Count |
| group_manager_id | choice | Group - Managers |
| group_member_count | number | Group - Member Count |
| group_member_id | choice | Group - Members |
| group_name | string | Group - Name |
| group_timezone | choice | Group - Timezone |
Role
| Parameter | Type | Description |
|---|---|---|
| role | choice | Role |
| role_access_level | choice | Role - Access Scope |
| role_id | uuid | Role - ID |
| role_name | string | Role - Name |
Tenant
| Parameter | Type | Description |
|---|---|---|
| tenant | choice | Tenant |
| tenant_associate_calls | choice | Tenant - Associate Calls with Tenant |
| tenant_associate_calls_condition | string | Tenant - Associate Calls with Tenant - Condition |
| tenant_audio_format | choice | Tenant - Audio Recording - Audio Format |
| tenant_auto_provision | bool | Tenant - User Auto Provisioning |
| tenant_auto_provision_authenticate_type | choice | Tenant - User Auto Provisioning - Authentication Type |
| tenant_auto_provision_can_login | bool | Tenant - User Auto Provisioning - Web portal access |
| tenant_auto_provision_extension_to_login_match_pattern | string | Tenant - User Auto Provisioning - Extension-to-login Translation Pattern |
| tenant_auto_provision_extension_to_login_translation_rule | string | Tenant - User Auto Provisioning - Extension-to-login Translation Rule |
| tenant_auto_provision_group_id | choice | Tenant - User Auto Provisioning - Group |
| tenant_auto_provision_licenses | choice | Tenant - User Auto Provisioning - Licenses |
| tenant_auto_provision_record | choice | Tenant - User Auto Provisioning - Recording Settings |
| tenant_auto_provision_role_id | choice | Tenant - User Auto Provisioning - Role |
| tenant_broadworks_group_id | string | Tenant - Associate Calls with Tenant - Broadworks Group ID |
| tenant_broadworks_sp_id | string | Tenant - Associate Calls with Tenant - Broadworks SP ID |
| tenant_cisco_partition | string | Tenant - Associate Calls with Tenant - Cisco Partition |
| tenant_domain | string | Tenant - Domain |
| tenant_extension_type | choice | Tenant - Extension type |
| tenant_extensions_unique_systemwide | bool | Tenant - Extension uniqueness is system-wide |
| tenant_file_format | choice | Tenant - Audio Recording - File Format |
| tenant_id | uuid | Tenant - ID |
| tenant_language | choice | Tenant - Language |
| tenant_licenses_evaluation_seat | number | Tenant - License - Agent Evaluation |
| tenant_licenses_monitoring_seat | number | Tenant - License - Live Monitoring |
| tenant_licenses_recording_seat | number | Tenant - License - Call Recording |
| tenant_licenses_screen_recording_seats | number | Tenant - License - Screen Recording |
| tenant_licenses_speech_analytics | number | Tenant - License - Speech Analytics |
| tenant_lookback_ondemand_recording | choice | Tenant - LookBack On-Demand Recording |
| tenant_metaswitch_group | string | Tenant - Associate Calls with Tenant - MetaSwitch Group Name |
| tenant_metaswitch_system | string | Tenant - Associate Calls with Tenant - MetaSwitch System Name |
| tenant_name | string | Tenant - Name |
| tenant_pause_recording_timeout | number | Tenant - Pause Recording Timeout |
| tenant_record_unknown_users | choice | Tenant - Record Unknown Users |
| tenant_screen_rec_enable | bool | Tenant - Screen Recording |
| tenant_sip_uri_host | string | Tenant - Associate Calls with Tenant - SIP URI Host |
| tenant_storage_limit_audio_days | number | Tenant - Storage Limits - Audio Recordings - Days |
| tenant_storage_limit_audio_minutes | number | Tenant - Storage Limits - Audio Recordings - Minutes |
| tenant_storage_limit_audio_size | float | Tenant - Storage Limits - Audio Recordings - File Size |
| tenant_storage_limit_screen_days | number | Tenant - Storage Limits - Screen Recording - Days |
| tenant_storage_limit_screen_minutes | number | Tenant - Storage Limits - Screen Recording - Minutes |
| tenant_storage_limit_screen_size | float | Tenant - Storage Limits - Screen Recording - File Size |
| tenant_storage_limits_enable | bool | Tenant - Storage Limits |
| tenant_timezone | choice | Tenant - Timezone |
| tenant_total_groups | number | Tenant - Total Groups |
| tenant_total_roles | number | Tenant - Total Roles |
| tenant_total_users | number | Tenant - Total Users |
| tenant_use_agc | choice | Tenant - Audio Recording - AGC Filter |
| tenant_use_plc | choice | Tenant - Audio Recording - PLC Filter |
User
| Parameter | Type | Description |
|---|---|---|
| user | choice | User |
| user_authenticate_type | choice | User - Authentication Type |
| user_basic_speech_analytics | bool | User - Basic Speech Analytics |
| user_can_login | bool | User - Web Portal Access |
| user_confidential | bool | User - Confidential Flag |
| user_created_time | datetime | User - Create Date/Time |
| user_email | string | User - Email |
| user_extension | string | User - Extension |
| user_group_count | number | User - Group Membership Count |
| user_has_calls_for_period | date | User - Has calls for period |
| user_id | uuid | User - ID |
| user_is_active | bool | User - Active Status |
| user_last_login_time | datetime | User - Last Login Date/Time |
| user_license | choice | User - License |
| user_login | string | User - Login |
| user_managed_group_count | number | User - Managed Group Count |
| user_managed_group_id | choice | User - Managed Group |
| user_must_change_password | bool | User - Must Change Password |
| user_name | string | User - Name |
| user_no_calls_for_period | date | User - No calls for period |
| user_record | choice | User - Recording Setting |
| user_record_announcement | choice | User - Recording Announcement |
| user_record_direction | choice | User - Recording Direction |
| user_require_2fa | bool | User - Require 2FA |
| user_screen_recording_login | string | User - Screen Recording Username |
| user_timezone | choice | User - Timezone |
| user_valid_till_time | datetime | User - Valid Till Date/Time |
Comparison operators
string
equal_to- the value matches the text exactlynot_equal_to- the value does not match the textstarts_with- the value starts with the textends_with- the value ends with the textincludes- the value includes the textis_empty- the value is an empty string or not setnot_empty- the value is not an empty stringpattern- the value matches a simple pattern (similar to SQLLIKE), where_matches exactly one character and%matches zero or more charactersregex- the value matches a regular expression
string_query
query- the value matches a full-text search queryis_empty- the value is an empty string or not setnot_empty- the value is not an empty string
uuid
is- the ID equals the valueis_not- the ID does not equal the valueis_empty- the ID is not setnot_empty- the ID is set
The value must be a valid UUID, otherwise the request fails with 400 Bad Request.
number and float
equal_to,not_equal_togreater_than,greater_than_or_equal_tolower_than,lower_than_or_equal_tobetween,not_between- two numbers separated by-, for example10 - 20is_set- the value is available (notNULL)not_set- the value is not available (NULL)
multi_param_number
Same operators as number. The value additionally carries the ID of the secondary parameter,
separated from the number by two underscores. For example, to find calls where the topic
7f34c1ef-742e-4a88-b772-5e4e6a925ebe matched more than twice:
/api/v2/calls.json?advanced_search=1&topic_match__greater_than=7f34c1ef-742e-4a88-b772-5e4e6a925ebe__2
date
equal_to,not_equal_tobefore,after,on_or_before,on_or_afterbetween,not_between- two dates separated by-older_than_days,newer_than_days- an integer number of dayswithin_day_range,within_week_range,within_month_range,within_quarter_range,within_year_range- a range of relative periods. For example,-30 - 0withwithin_day_rangemeans the last 30 days, and-1 - 0withwithin_month_rangemeans the last monthis_set,not_set
Format of a date: YYYY/MM/DD, or YYYY/MM/DD - YYYY/MM/DD for a range (the spaces around the separator are optional).
datetime
equal_to,not_equal_tobefore,after,on_or_before,on_or_afterbetween,not_between- two values separated by/older_than_minutes,newer_than_minutes- an integer number of minuteswithin_minute_range,within_hour_range- a range of relative periods. For example,-10 - 0withwithin_minute_rangemeans the last 10 minutesis_set,not_set
Format of a date and time: ISO 8601, for example 2024-04-30T06:00:00.000Z, or 2024-04-30T06:00:00.000Z/2024-04-30T06:30:00.000Z for a range.
time
equal_to,not_equal_tobefore,after,at_or_before,at_or_afterbetween,not_between- two values separated by-is_set,not_set
Format of a time: HH:MM:SS, or HH:MM:SS - HH:MM:SS for a range.
duration
equal_to,not_equal_togreater_than,greater_than_or_equal_tolower_than,lower_than_or_equal_tobetween,not_between- two values separated by-
Format of a duration: SS (seconds), MM:SS, or HH:MM:SS. For a range, two values
separated by -, for example 1:00 - 5:00.
choice
is- the value equals the optionis_not- the value does not equal the optionone_of- the value is one of the optionsnot_one_of- the value is none of the optionsis_set,not_set
The value is the identifier of the option: the ID of a user, group, tag, or client; the numeric
code of a call state, recording state, or VoIP protocol; or a keyword for parameters such as
direction (inbound, outbound, internal, inbound_excl_internal, outbound_excl_internal,
unknown). The error message of a rejected value lists the accepted options. Pass several options
to one_of and not_one_of as a comma-separated list, for example direction__one_of=inbound,outbound.
text_choice
Combines the operators of choice and string. Used for ACD attributes and option-type custom fields, where the stored value is free text but a list of known options is also offered.
is,is_not,one_of,not_one_ofequal_to,not_equal_to,starts_with,ends_with,includes,pattern,regexis_empty,not_empty,is_set,not_set
bool
is_true- the value is trueis_false- the value is false or not setis_set,not_set
Renamed types
The types set, string_set, and multi_param_set were renamed choice, text_choice, and
multi_param_choice. The operators older_than and newer_than of the date and datetime
types are now before and after. The old names are still accepted.