Result and Field Filtering

When retrieving a list of objects via a GET request, you can use result filtering and field filtering to customize the JSON response returned.

Result Filtering

The filter parameter can be added to the query URL to restrict or customize the results of a JSON response by specific parameters (for example, name, capabilities, state, country_code, etc.).

As a general rule, with some exceptions, you can filter results by any top-level field returned in the response. In some cases, nested subfields can also be used for filtering. To reference a nested field, use dot notation to separate the parent field and the subfield, for example:

trunks.allow_transfer eq false
properties.login eq "username"

Filter Syntax

The basic structure of a filter expression is:

filter=object_attribute filter_operator value

Filter values may be enclosed in single or double quotes. Quoting is optional for single-word values such as USA, but required when the value consists of more than one word contains spaces. For example:

name eq "filter value name"

Combining Filters

You can combine multiple filter conditions using the logical operator and. When filters are combined, all conditions must be satisfied for a record to be included in the response.

The general syntax for combining filters is:

filter=condition1 and condition2 [and conditionN]

Each condition must follow the standard filter syntax:

object_attribute filter_operator value

Only the and logical operator is supported for combining filter conditions. Other logical operators such as or, not, or grouped expressions using parentheses are not supported.

Examples

Filter records by state and phone number pattern: filter=state eq "NY" and phonenumber like "%555%"

Filter records by status and numeric value: filter=status eq "active" and maximum_ttl gt 40000

Filter records using both top-level and nested fields: filter=properties.login eq "username" and type eq "conference"

info

When sending a cURL request, inside your filter string, be sure to use URL-encoding for special characters:

space → %20 or +
double quotes → %22
percentage sign → %25
colon → %3A

For example, the filter country_code eq "USA" and phonenumber like "%555%" must be encoded as:

country_code%20eq%20%22USA%22%20and%20phonenumber%20like%20%22%25555%25%22

or:

country_code+eq+%22USA%22+and+phonenumber+like+%22%25555%25%22.

cURL will accept both variants.

Example Request

This GET request returns Endpoint objects that match the filter criteria. In this case, the results are limited to endpoints of type conference.

curl -X GET \
'https://api.carrierx.com/core/v2/endpoints?filter=type+eq+conference' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The response includes all of the endpoints that fit the filter criteria.

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "addresses": [],
            "attributes": {},
            "capacity": 0,
            "endpoint_sid": "613325f8-bbb8-4599-b477-1b4fef3d017c",
            "name": "my_example_conference",
            "partner_sid": "6nelo9p3-3eef-4f75-8f48-fb98e99908be",
            "properties": {
                "account_sid": "bdrU77AFb-Y1sDwqqxkeb.M3LP7hSKYg",
                "api_url": "https://api.carrierx.com/conference/<%= config[:ConferenceVersion] %>",
                "container_sid": "null",
                "login": "username",
                "password": "password"
            },
            "transformations": [],
            "type": "conference",
            "voip_token": null
        }
    ],
    "limit": 1000,
    "offset": 0,
    "pagination": {},
    "total": 1
}

Result Filtering Quick Reference

Operator	Definition	Example
bit	Bit mask: this operator is used with the `capabilities` and `active_capabilities` fields only. It may have the following core values: 1 = SMS IN (1 represents 1 in a bit mask), 2 = SMS OUT (2 represents 10 in a bit mask), 4 = VOICE (4 represents 100 in a bit mask), 8 = MMS IN (8 represents 1000 in a bit mask), 16 = MMS OUT (16 represents 10000 in a bit mask). You can use this operator to look for all the DIDs that have a particular capability alongside with other possible capabilities those DIDs may have. For example `capabilities bit 4` returns all the available DIDs with the following capabilities: 4(100) and up, whatever other capabilities it may have (if any), e.g. 4+1=5(101), 4+2=6(110), 4+1+2=7(111), 4+8=12(1100), 4+1+8=13(1101), etc.	`capabilities bit 3` The search will return results for DIDs with both SMS and VOICE capabilities = 1+2+4=7. `capabilities bit 7` The search will return results for DIDs with both SMS and VOICE capabilities = 1+2+4=7.
eq	Equal to: this search looks for the exact value entered.	`name eq "my_mediator"` The search results will include the records that have the exact `my_mediator` value for the `name` field.
ge	Greater than or equal to: this search returns records where the value is greater than or equal to the field listed.	`wait_origination_did_ttl ge 70000` The search results will include the records that have the `wait_origination_did_ttl` field value greater than or equal to `70000`.
gt	Greater than: this search returns records where the value is exceeded for the field listed.	`maximum_ttl gt 40000` The search results will include the records that have the `maximum_ttl` field value greater than `40000`.
ilike	This search returns records containing the value indicated in the string passed. This form of search is case insensitive and supports the `%` wildcard character.	`name ilike "AccOUnt%"` The search results will include the records that have the `name` field value starting with `Account`.
in	In: this search returns records where the current value of the specified field must be in the specified list.	`status in ("active", "suspended")` The search results will include the records that have the `status` field value equal to either `active` or `suspended`.
le	Less than or equal to: this search returns records where the value is less than or equal to the field listed.	`wait_origination_did_ttl le 90000` The search results will include the records that have the `wait_origination_did_ttl` field value less than or equal to `90000`.
like	The same functionality as `ilike` but case sensitive. Supports the `%` wildcard character.	`name like "Account%"` The search results will include the records that have the `name` field value starting with `Account`.
lt	Less than: this search returns records where the value is less than the field listed.	`maximum_ttl lt 10000` The search results will include the records that have the `maximum_ttl` field value less than `10000`.
ne	Not equal to: this search returns records that do not include the current values for the specified field.	`name ne "my_mediator"` The search results will include the records that do not have the `my_mediator` value for the `name` field.
notin	Not in: this search returns records where the current value of the specified field must not be in the specified list.	`status notin ("active", "suspended")` The search results will include the records that do not have a `status` field value of `active`.

Wildcard Matching

When using the like and ilike filter operators, the % character can be used as a wildcard meaning that any number of characters can exist in place of %. A wildcard represents zero or more characters and allows pattern-based matching.

The wildcard can appear at the beginning, end, or middle of the filter value.

Examples

Match values that start with a string: name like "Account%"

Match values that end with a string: name like "%Service"

Match values that contain a string (case-insensitive): name ilike "%test%"

note

The % wildcard is supported only with the like and ilike operators.

Field Filtering

There are two parameters associated with field filtering: include_fields, and exclude_fields. By default, the fields included in JSON responses are specific to the request made. These returned fields are explained in the Object section for that object.

Refer to the specific object to determine which fields can be included and excluded from the JSON responses.

include_fields and exclude_fields accept comma-separated strings as values.

Example

In the following, we request Endpoint objects without the properties field.

curl -X GET \
'https://api.carrierx.com/core/v2/endpoints?exclude_fields=properties' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The following response excludes the properties field from returned Endpoint objects.

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "addresses": [],
            "attributes": {},
            "capacity": 0,
            "endpoint_sid": "613325f8-bbb8-4599-b477-1b4fef3d017c",
            "name": "my_example_conference",
            "out_sip_password": null,
            "out_sip_username": null,
            "partner_sid": "6nelo9p3-3eef-4f75-8f48-fb98e99908be",
            "transformations": [],
            "type": "conference",
            "voip_token": null
        }
    ],
    "limit": 1000,
    "offset": 0,
    "pagination": {},
    "total": 1
}

Field Filtering Quick Reference

Parameter	Data Type	Description
exclude_fields	string	The comma-separated list of fields to be excluded from the response. The fields depend on the object. See the Object section for that object to see which fields return.
include_fields	string	The comma-separated list of fields to be included in the response. The fields depend on the object. See the Object section for that object to see which fields return.

Result Filtering​

Filter Syntax​

Combining Filters​

Examples​

Example Request​

Result Filtering Quick Reference​

Wildcard Matching​

Examples​

Field Filtering​

Example​

Field Filtering Quick Reference​

Result Filtering

Filter Syntax

Combining Filters

Examples

Example Request

Result Filtering Quick Reference

Wildcard Matching

Examples

Field Filtering

Example

Field Filtering Quick Reference