Skip to main content

Using the REST API

This section describes how to obtain credentials to use the API, what types of requests the system recognizes, and the format of the responses. It also holds reference information about pagination, filtering, and callbacks.

Main Conventions​

The following conventions are used in the sections, which contain the tables with objects attributes, their types, and descriptions:

createThe attribute can be set when the user creates the object using the POST method.
updateThe attribute can be modified when the user updates the object using either PATCH or PUT methods.
read onlyThe attribute is set by the system and the user can neither set nor modify it.
requiredThe path/query argument is required in the request.
deprecatedThe API method is deprecated.
betaThe attribute is part of the feature that is still in development and is not recommended to use in production.

Authentication​

All CarrierX API requests require authentication. The first step to using CarrierX API is obtaining a CarrierX account and gaining credentials. To do so, please submit a request through our Contact Us page.

Currently, CarrierX API requests use two types of authentication:

  • Bearer token, used by the requests to the Core API.
  • Basic HTTP authentication with login and password, used by the requests to the endpoint APIs (Conference, FlexML, and Mediator).
warning

Your API credentials carry various privileges for CarrierX access. Be sure to keep them secure and do not share them in publicly accessible areas such as source code management systems, client-side code, etc.

With the credentials you receive from CarrierX team, you can gain access to the Portal, where you will be able to create a security token. The security token allows you to work with the Core API and retrieve the endpoint login credentials for Conference, FlexML, and Mediator.

tip

Follow the steps of our Create a Security Token quick start guide to create a token.

While the system allows request authentications for any users registered with CarrierX, the specific requests are limited by the scopes associated with the OAuth token that you use for the requests. This means that you might be eligible to make requests to CarrierX API, but not authorized to make a specific request, e.g., you can only view objects but not allowed to create, modify, or delete them.

You can create OAuth tokens with restricted access permissions (scopes) if you need that for a specific application. Refer to the Generate OAuth Bearer Token section for more details on this.

Prior to making requests to a Conference, FlexML, or Mediator endpoint, you need to create an application endpoint. Refer to the Configure an Application Endpoint quick start guide for step-by-step instructions on creating an endpoint. Dedicated quick start guides are also available to configure:

note

Note that at this time, you can only use tokens for the Core API. Each of the application endpoints has different login and password values. Entering the Core API token credentials instead of the endpoint-specific credentials when working with the Conference, FlexML, or Mediator APIs will return the unauthorized error.

Examples​

The following curl command will return a list of all of the endpoints of the CarrierX account associated with the login credentials. Use your Core API token in the query below. The endpoint login and password values are listed in the returned JSON object.

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

The credentials of a specific endpoint are found in the properties attribute of the nested object. Locate the login and password values.

{
  "count": 1,
  "has_more": false,
  "items": [
      {
          "addresses": [],
          "attributes": {},
          "capacity": 0,
          "endpoint_sid": "844346ef-93e9-4fa8-a4ab-e3015af94573",
          "name": "flexml",
          "out_sip_password": null,
          "out_sip_username": null,
          "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
          "properties": {
              "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
              "api_url": "https://api.carrierx.com/flexml/v1",
              "container_sid": "null",
              "login": "sample_login",
              "password": "sample_password"
          },
          "transformations": [],
          "type": "flexml",
          "voip_token": null
      }
  ],
  "limit": 1000,
  "offset": 0,
  "pagination": {},
  "total": 1
}

The following curl command will return data for your current account in FlexML API. Use your login and password to get this information.

curl -X GET \
'https://api.carrierx.com/flexml/v1/accounts/whoami' \
-H 'Content-Type: application/json' \
-u '<your_user_name>:<your_password>'

The response will be as follows:

{
    "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
    "login": "sample_login",
    "name": "User Name",
    "date_created": "2024-06-23T10:25:36.000Z",
    "url": null,
    "method": "POST",
    "error_handler": "basic",
    "status_callback_url": null,
    "status_callback_method": "POST"
}

Requests​

The requests in CarrierX API are made using the standard REST notation, typical for web services.

A simplest request will have the following structure:

  • The request URL to which the request will be sent. The URL will be different for the Core API methods and for the main endpoint-related requests (conference, FlexML, mediator).

  • The request method or the verb used for the REST over HTTP request.

  • One or several headers or user/password authentication.

    • At least one header----H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'---is required to access the Core API.
    • For the requests to the conference, FlexML, or mediator endpoints, CarrierX uses the basic HTTP authentication with login and password (cURL -u option).

    Refer to the Authentication section for more details on this.

All the above elements are required for all CarrierX API requests.

Other request may have additional structure elements which include:

  • Path arguments are required with some methods to access specific objects (GET the object by secure ID, PATCH/PUT, and DELETE objects).

  • Body payload is required with POST and PATCH/PUT. Even if the object method does not require any body arguments (e.g., POST for some objects), the payload must still include an empty object (--data-binary '{}').

    note

    If the request includes body payload, you must use the Content-Type: application/json header with it. Otherwise it will return the 415 Unsupported media type error status code.

  • Query arguments may be either optional or required for some requests. Refer to the objects sections below to see which object methods require the presence of the query arguments. The optional query arguments available with some GET requests include pagination, result filtering, and field filtering.

  • Form data is required with some POST methods, e.g., uploading a file to the container using multipart/form-data content type.

Sample Request​

A sample request to create a Conference endpoint:

curl -X POST \
'https://api.carrierx.com/core/v2/endpoints' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"my_conf", "type":"conference"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Request URL​

The usual path to the API objects includes the base URL to the API used with the object (Core API base URL for the objects used throughout the CarrierX products, or specific API base URLs used for FlexML, Mediator, or Conference), and the path to the object collections and the object items.

If the action targets the specific object, the path to it will include the object secure ID (SID), which allows to distinguish the targeted object from the other ones in the same collection.

tip
  • The Core API has the following base URL: https://api.carrierx.com/core/v2
  • The Conference API has the following base URL: https://api.carrierx.com/conference/v2
  • The FlexML API has the following base URL: https://api.carrierx.com/flexml/v1
  • The Mediator API has the following base URL: https://api.carrierx.com/mediator/v1

The system only accepts HTTPS requests, and not HTTP requests.

Request Methods​

CarrierX API uses five main verbs (methods) of REST over HTTP for the requests: POST, GET, PUT, PATCH, and DELETE. These methods are used to create the objects, get the information about the objects, modify the objects, and delete them.

note

Not all the objects can be created. Some of them are created automatically by the system. You can only view them, and cannot add, modify, or delete.

CarrierX partners need to have special permissions (or scopes) to use API methods on various objects. Refer to the available_scopes table for the complete list of the scopes that define the partner's permissions on objects and collections.

info

Please contact technical support at support@carrierx.com in the case you need some additional scopes enabled for your account.

POST​

The POST method is used to create new objects. When you create a new object, you usually need to specify at least some of the attributes for the object to be created in the request payload.

The successful POST request will return a 200 response with the serialized JSON copy of the created object.

Sample​

A sample POST request that creates a trunk

curl -X POST \
'https://api.carrierx.com/core/v2/trunk_groups/138ed522-6633-405b-b58d-55eb0d262e32/trunks' \
-H 'Content-Type: application/json' \
--data-binary '{}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

GET​

The GET method is used to view the information about the existing objects and their collections.

Generic GET requests return the list of all the objects (or collections) available for the request sent. Most of such GET requests can be used together with Pagination, Result Filtering, and Field Filtering.

GET requests aimed at a specific object require to use the object secure ID to be included as a part of the request path, and return the information about the specified object only. Most of such GET requests can be used together with Field Filtering.

The successful GET request will return a 200 response with the serialized JSON copy of the requested objects (or specific object).

Sample​

A sample GET request that returns the currently logged-in partner

curl -X GET \
'https://api.carrierx.com/core/v2/oauth/whoami' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

PATCH/PUT​

The PATCH/PUT methods are both used to modify the existing objects and their attributes. The difference between them is explained below.

PATCH is used to modify only some of the object attributes and does not require to send the entire object in the request payload. Only the attributes and their values that need to be modified can be sent in the request body.

Objects can have a complex structure and can contain other objects as part of them, i.e., nested inside them. When you use PATCH and want to modify the nested objects, PATCH follows the below rules to define what must be updated and how:

  1. If the existing nested object contains the same record (by key), the existing record will be replaced with the new value, provided in the PATCH request. The other nested object records will remain unmodified.

  2. If the existing nested object does not contain the same record, a new record will be added to the object. The other nested object records will remain unmodified.

  3. If the existing nested object contains the same record and the value of the incoming record is null, then the existing record will be removed. The other nested object records will remain unmodified.

  4. If the PATCH request contains nested_objects=replace as a query attribute, the whole nested object will be replaced with a new one (i.e., all the old records and their values will be removed and only the new ones will be added).

PUT is used to modify the complete object and require to send the entire object (together with the nested objects, if there are any) in the request payload.

Both PATCH and PUT requests are aimed at a specific object and require the object secure ID as a part of the request path.

The successful PATCH/PUT request will return a 200 response with the serialized JSON copy of the modified object.

Sample 1​

A sample PATCH request that modifies or adds a new name record of the nested attributes object:

curl -X PATCH \
'https://api.carrierx.com/core/v2/partners/aeda835c-6627-4f4c-ac73-9edcae95640b' \
-H 'Content-Type: application/json' \
--data-binary '{"attributes":{"name":"New Partner Name"}}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response 1​

The serialized JSON copy of the created object together with the nested object:

{
    "attributes": {
        "name": "New Partner Name"
    },
    ...,
    "partner_sid": "ed437757-001d-4ecc-aa5a-efdf5e50dba0"
}
Sample 2​

A sample PATCH request that adds a new name2 record of the nested attributes object of the same Partner object:

curl -X PATCH \
'https://api.carrierx.com/core/v2/partners/aeda835c-6627-4f4c-ac73-9edcae95640b' \
-H 'Content-Type: application/json' \
--data-binary '{"attributes":{"name2":"New Partner Name 2"}}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response 2​

The serialized JSON copy of the created object together with the modified nested object:

{
    "attributes": {
        "name": "New Partner Name"
        "name2": "New Partner Name 2"
    },
    ...,
    "partner_sid": "ed437757-001d-4ecc-aa5a-efdf5e50dba0"
}
Sample 3​

A sample PATCH request that modifies the entire nested attributes object of the same Partner object:

curl -X PATCH \
'https://api.carrierx.com/core/v2/partners/aeda835c-6627-4f4c-ac73-9edcae95640b?nested_objects=replace' \
-H 'Content-Type: application/json' \
--data-binary '{"attributes":{"name3":"New Partner Name 3"}}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response 3​

The serialized JSON copy of the created object together with the nested object:

{
    "attributes": {
        "name3": "New Partner Name 3"
    },
    ...,
    "partner_sid": "ed437757-001d-4ecc-aa5a-efdf5e50dba0"
}

DELETE​

The DELETE method is used to delete the object targeted by its secure ID.

The successful DELETE request will return a 204 response code with an empty body.

Sample​

A sample DELETE request that deletes an endpoint:

curl -X DELETE \
'https://api.carrierx.com/core/v2/endpoints/1a34c5e9-3a09-4de5-b553-5f6a9ef202ac' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Rate Limiting​

Currently, CarrierX applies no rate limiting to the partners requests to CarrierX API.

Responses​

All responses return conventional HTTP status codes. Most of the responses (GET, POST, PATCH/PUT) also return objects in the JSON format.

CarrierX API allows cross-origin (CORS) requests and data transfers.

HTTP Status Codes​

Error CodeMessageDescription
2xxSuccess
200OKThe request has succeeded. The result will be a returned JSON object or a link to download a file.
201CreatedThe request has succeeded and led to the creation of a resource. This response is normally returned to the requests that upload files.
204No ContentThe server has successfully fulfilled the request. There is no additional content to send in the response payload body. This response code is normally returned to the DELETE requests.
4xxClient Errors
400Bad RequestThe request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.
400No JSON object could be decodedGenerally an indicator that there is a syntax error.
401Bad credentialsThe request requires correct user authentication.
401UnauthorizedThe request requires user authentication.
403ForbiddenThe server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.
404Cannot find item by SIDThe SID number does not exist. Verify that the SID has been entered correctly. Note that calls can expire.
404Not FoundThe requested resource was not found on the server.
409Depends on the conflict sourceThis status code (aka Conflict) means that your request could not be processed because of some conflict that has occurred during such a request. For specific details see the error section of the API method that you are calling. As a rule, you can try to resolve the conflict by resubmitting your request later.
415Unsupported media typeEnsure that the header includes support for the JSON content type.
422Object validation errorThe server cannot process a request to the API because the request contains semantic errors or does not meet certain conditions.
5xxServer Errors
500Internal server errorThe server encountered an unexpected condition which prevented it from fulfilling the request.

Examples​

A typical 200 status code in the response

HTTP/2 200
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Access-Control-Allow-Origin,Access-Control-Allow-Methods,Access-Control-Allow-Credentials,Content-Disposition,Access-Control-Allow-Headers
Content-Length: 1333
Content-Type: application/json
Date: Wed, 22 Sep 2021 08:23:06 GMT
Server: nginx
Strict-Transport-Security: max-age=31536000; includeSubDomains
Vary: accept-encoding

CarrierX API uses the following HTTP status codes:

A sample 400 status code when the JSON sent in the request body has errors in its syntax:

{
    "body": {
        "message": "cannot parse json. Check json for validity",
        "errors": null
    },
    "status": 400
}

A sample 401 status code when trying to send a request without authentication:

{
  "message": "authentication required",
  "errors": [
    {
      "field": "cause",
      "message": "authentication required",
      "reference_sid": null
    }
  ]
}

A sample 403 status code when trying to access resources you do not have enough permission for:

{
    "message": "permission denied",
    "errors": [
        {
            "field": "cause",
            "message": "permission denied",
            "reference_sid": null
        }
    ]
}

A sample 404 status code when trying to access a non-existent object (e.g., a token with an incorrect SID):

{
    "message": "no item error",
    "errors": [
        {
            "field": null,
            "message": "cannot find token",
            "reference_sid": null
        }
    ]
}

Response Objects​

A typical formatted JSON object in the response

{
    "callback_url": null,
    "did_group_sid": "41e21049-e5eb-433c-a93d-d57417b1863c",
    "name": "N/A",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f"
}

Successful requests return objects in the JSON format with application/json set as Content-Type. The object keys and values depend on the request and the object returned, and are described in the corresponding object sections.

Normally, the system returns the object fields unordered and unformatted. To view the object fields ordered alphabetically and "pretty-formatted" in the response to the command-line requests (e.g., cURL), use the jq command-line JSON processor or similar tools.

With jq, the request will look like this:

curl -X GET 'https://api.carrierx.com/core/v2/oauth/whoami' -H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda' | jq -S

Pagination​

You can use the pagination to limit the number of the objects returned in the response and sort them by the object attributes.

The pagination is available for the GET requests which return the lists of the objects without targeting them by secure IDs.

info

All the pagination parameters and their values are added to the URL as query parameters.

The pagination parameters include:

limit​

An integer parameter that determines how many items are returned in the response. The entered value cannot exceed 1000.

The default value is 10, meaning that a maximum of ten items will be returned.

Example

limit=100: returns 100 items if their total number is more or equal to 100, or all the existing items if their quantity is less than 100.

order​

A string parameter that allows to sort the returned objects. Three values are accepted for this parameter:

  • attribute name + asc to sort the items in the response in the ascending or alphabetical order (default order).
  • attribute name + desc to sort the items in the response in the descending or reverse-alphabetical order.
  • shuffle to randomize the order of the items in the response.
Example
  • order=name+desc: returns objects sorted by name in reverse-alphabetical order.
  • order=name (shorthand for order=name+asc): returns objects sorted by name in alphabetical order.
  • order=shuffle: returns objects in randomized order.

offset​

An integer parameter that determines the amount of items that are skipped in the response.

The default value is 0, meaning that the first existing item will appear first.

Example

offset=2: if there are five records, the response will not include the first two records; instead, it will return records for items three through five.

note

The offset parameter is not used together with the after/ before arguments.

Sample Request​

This request returns Country objects sorting them descending by the common_name attritute, starting with the second record available, and returns a maximum of two records.

curl -X GET \
'https://api.carrierx.com/core/v2/countries?offset=2&limit=2&order=common_name+desc' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

To view records not included in the response, make a request to the URL value of the previous or the next key.

{
  "count": 2,
  "has_more": true,
  "items": [
    {
      "capital": "Sana'a",
      "common_name": "Yemen",
      "dialing_prefix": "967",
      "domain": "ye",
      "iso_3166_alpha_2": "YE",
      "iso_3166_alpha_3": "YEM",
      "iso_3166_numeric": 887,
      "mcc": "421",
      "official_name": "Republic of Yemen",
      "region": "Asia",
      "subregion": "Western Asia"
    },
    {
      "capital": "El Aaiún",
      "common_name": "Western Sahara",
      "dialing_prefix": null,
      "domain": "eh",
      "iso_3166_alpha_2": "EH",
      "iso_3166_alpha_3": "ESH",
      "iso_3166_numeric": 732,
      "mcc": null,
      "official_name": "Sahrawi Arab Democratic Republic",
      "region": "Africa",
      "subregion": "Northern Africa"
    }
  ],
  "limit": 2,
  "offset": 2,
  "pagination": {
    "next": "https://api.carrierx.com/core/v2/countries?limit=2&order=common_name+desc&offset=4",
    "previous": "https://api.carrierx.com/core/v2/countries?limit=2&order=common_name+desc&offset=0"
  },
  "total": 251
}

after/ before​

For some objects (e.g., Call Detail Record or SMS Detail Record objects), the system will not return their total number. This can happen as the number dynamically changes in large quantities and can become not relevant by the time of the next request.

In this case, instead of using the standard pagination offset (which is rather difficult to calculate as the system does not return the total number of objects), you can use the after or before query arguments. With these arguments, the system will return the objects which precede or follow the entered object secure ID. This might be useful if you want to receive an exact range of the objects and know the secure IDs of the records which start and end this range.

ParameterData TypeDescription
afterstringThe secure ID of the object. The response will include only the results which follow the specified secure ID in the list of the object secure IDs.
beforestringThe secure ID of the object. The response will include only the results which precede the specified secure ID in the list of object secure IDs.
note

If you use the after or before query arguments:

  • the response pagination attribute will also include the secure IDs of the previous or next objects instead of the offset value;
  • you cannot set the offset to any value except 0 (normally, you should omit the offset query attribute from such requests);
  • you can only apply the sorting by the limited number of the object attributes (e.g., date_stop for Call Detail Record objects or date_insert for SMS Detail Record objects).

Currently, CarrierX supports the pagination that uses the after and before arguments for the following objects and methods:

ObjectMethodSorting ('order') Values
Call Detail RecordGet Call Detail Records methoddate_stop
SMS Detail RecordGet Message Detail Records methoddate_insert
tip

Refer to our Call Detail Record Application Quick Start to learn more about how you can use the after and before pagination query arguments.

Sample Request​

This request returns a maximum of one record of SMS Detail Record objects following the object with the b6d574ea-b11f-41fd-a25f-602e7b28807f secure ID.

curl -X GET \
'https://api.carrierx.com/core/v2/sms/message_drs?after=b6d574ea-b11f-41fd-a25f-602e7b28807f&limit=1' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

To view records not included in the response, make a request to the URL value of the previous key.

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "date_insert": "2020-07-24T10:25:11.000Z",
            "date_sent": "2020-07-24T10:25:11.014Z",
            "date_start": "2020-07-24T10:25:11.014Z",
            "date_stop": "2020-07-24T10:25:12.014Z",
            "delay_sent": 0,
            "direction": "outbound",
            "dr_sid": "92cd9154-2f53-4e62-8b4e-8ff6e4849d16",
            "mcc": 310,
            "media_urls": [],
            "message": "This is a test message.",
            "message_segments": 1,
            "mnc": 999,
            "number_billing": "15162065870",
            "number_dst": "12078152557",
            "number_external": "12078152557",
            "number_src": "15162065870",
            "partner_sid": "8d180104-0b34-4e55-907f-4a72409484c9",
            "price": "0.005",
            "provider": "tsg",
            "rate": "0.005",
            "status": "sent",
            "type": "sms",
            "user_data": "test_message",
            "version": null
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "previous": "https://api.carrierx.com/core/v2/sms/message_drs?before=92cd9154-2f53-4e62-8b4e-8ff6e4849d16&limit=1&offset=0"
    },
    "total": null
}

Request Parameters Combinations​

You can use the following combinations of the pagination parameters:

  • limit, offset, order: https://api.carrierx.com/core/v2/countries?limit=2&offset=2&order=common_name+desc

  • after, limit, order: https://api.carrierx.com/core/v2/calls/call_drs?after=bb2aacd2-23d3-418e-9ec0-2fc45c5f9d76&limit=1&order=date_stop+asc

  • before, limit, order: https://api.carrierx.com/core/v2/calls/call_drs?before=56fb6b94-811e-4952-b242-4e06f4e95b7e&limit=1&order=date_stop+desc

  • after, before, limit, order: https://api.carrierx.com/core/v2/sms/message_drs?after=012e1d6a-75ac-43ec-bacc-68f1ef1c60a3&before=b6d574ea-b11f-41fd-a25f-602e7b28807f&limit=100&order=date_insert+desc

If you omit any of the parameters from the response, their default values will be used (if there are any).

Pagination Response​

The JSON response for a successful query using the pagination parameters will include the following attributes:

AttributeData TypeDescription
countintegerThe number of items present in the response.
has_morebooleanWhether or not there are more records existing outside of the queried parameters (e.g., if the number of items that exist exceeds the limit value, the has_more value in the response will be set to true).
itemsarray of objectsThe list of the objects which match the request with the pagination query parameters applied.
limitintegerThe limit value applied to the request.
offsetintegerThe offset value applied to the request.
paginationobjectThe links that allow getting the objects which precede or follow the objects in the response due to the offset or after/ before arguments used in the request. This attribute will be an empty object if there are no more records existing outside of the queried parameters. If there are existing records outside of the query, the pagination value will include the next or previous URLs, or both of them.
totalintegerThe total number of the queried objects that match the search criteria. This value will be set to null with the uncountable objects (call detail records, messages, etc.)
tip

You can use the URLs present in the response pagination attribute to obtain the remainder of the records available without modifying the original query. Simply construct another GET request with the URL(s) provided in this field.

note

You can additionally restrict the results returned in the response using Result Filtering and/or Field Filtering.

Result Filtering​

The filter parameter is added to the query URL to restrict or customize the results of a JSON response by certain parameters (e.g., name, capabilities, state, country_code, etc.). The common rule is that, with some exceptions, you can filter those results by any top-level field(s) that are returned in the response. Moreover, in some cases you can use the nested subfields for result filtering. In this case you need to use a dot in the filter name to separate the parent field and the nested subfield, e.g. trunks.allow_transfer eq false or properties.login eq username.

The structure of result filtering is as follows: filter=object_attribute filter_operator value. You can also use the and operator to combine several filters for more specific searches. For example, for a DID object we could apply the following filter: filter=state eq "NY" and phonenumber like "%555%".

Filter values can also be put inside single or double quotes. This is not necessary when the filter value is just a single word like USA. However, if your filter value consists of more than one word, the quotes are required. For example, name eq "filter value name".

info

When sending a cURL request, inside your filter string, do not forget to use the so-called URL-encoding instead of the following characters:

  • space: use %20 or + instead
  • double quotes: use %22 instead
  • percentage sign: use %25 instead
  • colon: use %3A instead

For example, a string like country_code eq "USA" and phonenumber like "%555%" must be converted to country_code%20eq%20%22USA%22%20and%20phonenumber%20like%20%22%25555%25%22 or to country_code+eq+%22USA%22+and+phonenumber+like+%22%25555%25%22. cURL will accept both variants.

Example​

This GET request returns Endpoint objects that meet the filter criteria. In this case, we are narrowing the results to the conference endpoint type.

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

The following 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​

OperatorDefinitionExample
bitBit 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.
eqEqual 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.
geGreater 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.
gtGreater 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.
ilikeThis search returns records containing the value indicated in the string passed. This form of search is case insensitive.name ilike "AccOUnt%"
The search results will include the records that have the name field value starting with Account.
inIn: 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.
leLess 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.
likeThe same functionality as ilike but case sensitive.name like "Account%"
The search results will include the records that have the name field value starting with Account.
ltLess 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.
neNot 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.
notinNot 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.
note

For the ilike and like filters, % can be added anywhere as part of the string to indicate that any number of characters can exist in place of %. So, this method of search will also work: name like "A%t". This search will yield records with name values beginning with A and ending in t.

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​

ParameterData TypeDescription
exclude_fieldsstringThe 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_fieldsstringThe 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.