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:

create	The attribute can be set when the user creates the object using the POST method.
update	The attribute can be modified when the user updates the object using either PATCH or PUT methods.
read only	The attribute is set by the system and the user can neither set nor modify it.
required	The path/query argument is required in the request.
deprecated	The API method is deprecated.
beta	The 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:

• a Conference v2 Endpoint
• a FlexML Endpoint
• a Mediator Endpoint

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