Requests

What is a Request?

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.

Example Request

An example 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.

Example

An example 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).

Example

An example 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.

Example 1

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

Example 2

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

Example 3

An example 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.

Example

An example 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.