Core API Reference
The CarrierX service offers a RESTful API that can be used to rent phone numbers, enable SMS for applications, support SIP trunking, and provision full-featured application endpoints.
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.
Using Postman
This documentation contains cURL commands that you will run in your terminal. Rather than use these commands, you can explore the API using Postman, a stand-alone client with a user-friendly interface. Postman is widely used for API development and allows you to test requests.
You will need to download the Postman client to your computer. To do so, visit the Postman website and click Download. Click Run in Postman to import this collection to the Postman app.
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. |
Authentication
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
andpassword
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
andpassword
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
}
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).
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.
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.
Requests
Sample request to create 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'
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.
- At least one header—
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
, andDELETE
objects). - Body payload is required with
POST
andPATCH
/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 '{}'
).
- 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 usingmultipart/form-data
content type.
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.
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.
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.
POST
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'
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.
GET
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'
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).
PATCH/PUT
Sample
PATCH
request that modifies or adds a newname
record of the nestedattributes
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 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
PATCH
request that adds a newname2
record of the nestedattributes
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 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
PATCH
request that modifies the entire nestedattributes
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 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"
}
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:
-
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. -
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.
-
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. -
If the
PATCH
request containsnested_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.
DELETE
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'
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.
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
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
The Core API uses the following HTTP status codes:
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
}
Sample
401
status code when trying to send a request without authentication:
{
"message": "authentication required",
"errors": [
{
"field": "cause",
"message": "authentication required",
"reference_sid": null
}
]
}
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
}
]
}
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
}
]
}
Error Code | Message | Description |
---|---|---|
2xx | Success | |
200 | OK | The request has succeeded. The result will be a returned JSON object or a link to download a file. |
201 | Created | The request has succeeded and led to the creation of a resource. This response is normally returned to the requests that upload files. |
204 | No Content | The 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. |
4xx | Client Errors | |
400 | Bad Request | The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications. |
400 | No JSON object could be decoded | Generally an indicator that there is a syntax error. |
401 | Bad credentials | The request requires correct user authentication. |
401 | Unauthorized | The request requires user authentication. |
403 | Forbidden | The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated. |
404 | Cannot find item by SID | The SID number does not exist. Verify that the SID has been entered correctly. Note that calls can expire. |
404 | Not Found | The requested resource was not found on the server. |
409 | Depends on the conflict source | This 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. |
415 | Unsupported media type | Ensure that the header includes support for the JSON content type. |
422 | Object validation error | The server cannot process a request to the API because the request contains semantic errors or does not meet certain conditions. |
5xx | Server Errors | |
500 | Internal server error | The server encountered an unexpected condition which prevented it from fulfilling the request. |
Response Objects
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
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 thenext
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
}
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.
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.
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.
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.
after/ before
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
}
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.
Parameter | Data Type | Description |
---|---|---|
after | string | The 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. |
before | string | The 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. |
Currently, CarrierX supports the pagination that uses the after
and before
arguments for the following objects and methods:
Object | Method | Sorting (‘order’) Values |
---|---|---|
Call Detail Record | Get Call Detail Records method | date_stop |
SMS Detail Record | Get Message Detail Records method | date_insert |
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:
Attribute | Data Type | Description |
---|---|---|
count | integer | The number of items present in the response. |
has_more | boolean | Whether 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 ). |
items | array of objects | The list of the objects which match the request with the pagination query parameters applied. |
limit | integer | The limit value applied to the request. |
offset | integer | The offset value applied to the request. |
pagination | object | The 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. |
total | integer | The 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.) |
Result Filtering
This
GET
request returns Endpoint objects that meet the filter criteria. In this case, we are narrowing the results to theconference
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/v1",
"container_sid": "null",
"login": "username",
"password": "password"
},
"transformations": [],
"type": "conference",
"voip_token": null
}
],
"limit": 1000,
"offset": 0,
"pagination": {},
"total": 1
}
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"
.
Result Filtering Quick Reference
Operator | Definition | Example | Description |
---|---|---|---|
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 capabilities bit 7 |
The search will return results for DIDs with SMS capabilities = 1+2=3. 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. | 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. |
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 . |
Field Filtering
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
}
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.
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. |
Core Concepts
This section outlines core concepts having to do with the Core API.
Batch Operations
The Batch API allows you to create, update, and delete tasks. Tasks are bulk operations that modify one or more phonenumber
, prefix
or file
. When you create a batch task, you will have the option to review the items if you set the review
field to boolean true
value. In this case, your returned JSON status
will be pending_review
.
If the changes look correct, you can make a PATCH
or PUT
request to change the status
from pending_review
to approved
. If the items look incorrect, the batch request can be prevented from proceeding by changing the status
to cancelled
.
Callbacks
The CarrierX API enables callbacks to be sent to a URL. The callbacks are triggered when a specific action occurs, such as when either sending or receiving an SMS, calling into a conference, etc. The callback data will be the object that was affected. For example, if an SMS was sent to or from a phone number associated with a callback URL, the callback will be the SMS object.
Callbacks are assigned on either the DID object or the Partner object. If a callback URL is assigned on both the DID object level and the Partner object level, the DID object callback URL will override the Partner object callback URL.
On the Partner object, you can set the following callbacks
- for SMS activity use the
sms
field in thecallbacks
object; - for the mediator endpoints activity use the
app_mediator
field; - for the conference endpoints activity use the
app_conference_call
andapp_conference_meeting
fields. - to get a callback confirming that a DID from an external provider has been rented successfully, use the
phonenumber_order
field.
On the DID object, set the value of the callback_url
field for the callbacks related to SMS activity.
sms and callback_url Callback
The callback response. Refer to the SMS object for more information about each attribute and value.
{
"date_changed":"2023-09-04T17:37:38.852Z",
"date_created":"2023-09-04T17:37:36.123Z",
"date_status_changed":"2023-09-04T17:37:00.000Z",
"direction":"outbound",
"from": "15162065319",
"group_recipients":[],
"mcc":250,
"media_urls":[],
"message": "This is a test inbound message delivered by CarrierX",
"message_segments": 1,
"message_sid": "e405fa47-48f5-4dc5-bbba-77231587188e",
"mnc": null,
"partner_sid": "QLJ79xlC2vP-UEx3hS0R4rldas8.G1UB",
"price": "1",
"status": "received",
"to": "15162065318",
"type":"sms",
"user_data":null}
}
The system sends sms
and callback_url
callbacks when an action related to an SMS event occurs.
Attribute | Data Type | Description |
---|---|---|
date_changed | string | The date and time when the message was last changed. |
date_created | string | The date and time when the system created the message object. |
date_status_changed | string | The date and time when the system changed the message status. |
direction | string | The message direction. |
from | string | The phone number which was used to send the message. Note, that legacy users may still see the old naming instead (from_did ). |
group_recipients | array | The list of phone numbers that an inbound or outbound mms group message is delivered to, in E.164 format |
mcc | integer | The mobile country code that was used by the operator when sending the message. |
media_urls | array | The list of URLs for media resources, if type of message is mms . |
message | string | The message text. It can be empty when sending multimedia messages (MMS) or contain some text which was sent to the receiving party. |
message_segments | integer | The number of segments which the message contains. |
message_sid | string | The secure ID of the message which the system uses to identify the message among other messages. |
mnc | integer | The mobile network code that was used by the operator when sending the message. |
partner_sid | string | The secure ID of the partner associated with the message. |
price | number | The message price. It is calculated as (the rate for the message) × (the number of the message segments). |
status | string | The status of the message at the moment when the system sent the callback. |
to | string | The phone number which was used to receive the message. Note, that legacy users may still see the old naming instead (to_did ). |
type | string | The type of message. Values returned in this field are mms and sms . |
user_data | string | Some additional user-defined data added to the message. |
app_mediator Callback
The
app_mediator
callback response
{
"attributes":{},
"date_insert":"2019-01-25T18:12:10.770Z",
"date_start":"2019-01-25T18:08:23.000Z",
"date_stop":"2019-01-25T18:09:08.000Z",
"date_talk":"2019-01-25T18:08:44.000Z",
"direction":"inbound",
"dr_sid":"2a217f8d-df41-4e3d-bece-c72eaa2a8e2a",
"dtmf":null,
"duration":45,
"endpoint_sid":"632ec9ba-5bef-4ed3-a36d-56feec8ffd41",
"endpoint_type":"mediator",
"event_type":"binding",
"number_dst":"15162065344",
"number_redirect":"15162065346",
"number_src":"15162065345",
"partner_sid":"ed437757-002d-4ecc-aa5a-efdf5e50dba0",
"reference_sid":"05561bef-ce48-4823-a847-bf10f7837a42",
"type":"mediator",
"version":2
}
The app_mediator
callback is triggered when a call is made to a Mediator binding or from a Mediator dialout.
Attribute | Data Type | Description |
---|---|---|
attributes | object | The mediator attributes. |
date_insert | string | The date and time when the Call Detail Record was processed and added to the database. |
date_start | string | The date and time when the call started. |
date_stop | string | The date and time when the call stopped. |
date_talk | string | The date and time when the call is answered. |
direction | string | The direction of the call, either inbound or outbound . |
dr_sid | string | The secure ID of the record. |
dtmf | string | The DTMF sequence of the binding. |
duration | integer | The duration of the call. |
endpoint_sid | string | The endpoint secure ID. |
endpoint_type | string | The type of endpoint that triggered the callback. |
event_type | string | The event type. |
number_dst | string | The destination phone number. |
number_redirect | string | The redirect phone number. |
number_src | string | The source phone number. |
partner_sid | string | The partner secure ID. |
reference_sid | string | The binding_sid or the dialout_sid that was matched for the call. |
type | string | The endpoint type. |
version | integer | The API version. |
app_conference_call Callback
The
app_conference_call
callback response
{
"address_dst": "\\"15162065515\\" \\u003csip:15162065515@11.22.33.44\\u003e",
"address_src": "\\"1234\\" \\u003csip:+17605692222@12.34.56.78",
"bridge": "conference-bridge",
"call_sid": "69057c3e-bb90-4ed3-9c53-000000001090",
"custom_call_type": "foreign",
"custom_name": "\\u00271234\\u0027",
"date_disconnected": "2021-12-14T07:08:01.000Z",
"date_insert": "2021-12-14T07:40:27.706Z",
"date_join": "2021-12-14T07:07:31.000Z",
"date_start": "2021-12-14T07:07:09.000Z",
"date_stop": "2021-12-14T07:08:01.000Z",
"direction": "inbound",
"disconnect_cause": 16,
"disconnect_originator": "src",
"disconnect_reason": "Normal",
"duration": 50,
"duration_meeting": 30,
"endpoint_sid": "e3ddc435-7b07-4f3a-98d5-4fe9be107652",
"meeting_room_sid": "f752b4a5-b821-4322-a26f-db5cfbf014ab",
"meeting_sid": "69057c3e-bb90-4ed3-9c53-000000000373",
"node": "11.22.33.44",
"number_dst": "15162065515",
"number_src": "+17605692222",
"partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
"role": "participant",
"user_agent": "CX-IVS-SBC"
}
The app_conference_call
callback is triggered when the calling party calls a phone number associated with the Conference endpoint.
Attribute | Data Type | Description |
---|---|---|
address_dst | string | The fully qualified address of the called party which includes the SIP information with special characters formatted. |
address_src | string | The fully qualified address of the calling party which includes the SIP information with special characters formatted. |
bridge | string | The name of the bridge which handled the call. |
call_sid | string | The secure ID of the call which the system uses to identify it among other calls. |
custom_call_type | string | The special field used to identify the origin of the call. |
custom_name | string | The custom name for the calling party set by the software used, web, or IVR with special characters formatted. |
date_disconnected | string | The date and time when the call was disconnected from the meeting. |
date_insert | string | The date and time when the detail record about the call was inserted into the database. |
date_join | string | The date and time when the calling party joined the meeting. |
date_start | string | The date and time when the call started. |
date_stop | string | The date and time when the call ended. |
direction | string | The call direction, either inbound or outbound . |
disconnect_cause | integer | The numeric SIP code used to describe the reason to drop the call. |
disconnect_originator | string | The initiator of the disconnection. |
disconnect_reason | string | The detailed descriptive information about the reason to drop the call. |
duration | number | The total call duration, specified in seconds. |
duration_meeting | number | The duration of the caller’s participation in the meeting, specified in seconds. |
endpoint_sid | string | The secure ID of the Conference endpoint associated with the call. |
meeting_room_sid | string | The secure ID of the meeting room with which the meeting is associated. |
meeting_sid | string | The secure ID of the meeting in which the calling party participated. |
node | string | The IP address of the bridge node. |
number_dst | string | The called party phone number. |
number_src | string | The calling party phone number. |
partner_sid | string | The secure ID of the partner with which the Conference endpoint is associated. |
role | string | The role of the calling party in the meeting. |
user_agent | string | The details about the user agent used by the calling party, if available. |
app_conference_meeting Callback
The
app_conference_meeting
callback response
{
"attendee_count": 2,
"audio_attendee_count": 2,
"control_attendee_count": 0,
"data_attendee_count": 0,
"date_insert": "2021-12-14T07:40:33.843Z",
"date_start": "2021-12-14T07:04:41.000Z",
"date_stop": "2021-12-14T07:08:06.000Z",
"duration": 205,
"duration_audio": 205,
"duration_control": 0,
"duration_data": 0,
"duration_meeting": 205,
"duration_recording": 0,
"duration_video": 0,
"endpoint_sid": "e3ddc435-7b07-4f3a-98d5-4fe9be107652",
"has_recording": false,
"meeting_room_sid": "f752b4a5-b821-4322-a26f-db5cfbf014ab",
"meeting_sid": "69057c3e-bb90-4ed3-9c53-000000000373",
"partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
"unique_attendee_count": 2,
"video_attendee_count": 0
}
The app_conference_meeting
callback is triggered when the calling party joins a Conference meeting.
Attribute | Data Type | Description |
---|---|---|
attendee_count | integer | The total number of the meeting attendees. |
audio_attendee_count | integer | The number of the attendees which used audio conferencing during the meeting. |
control_attendee_count | integer | The number of the attendees which used conference controls during the meeting. |
data_attendee_count | integer | The number of the attendees which sent some data during the meeting. |
date_insert | string | The date and time when the detail record about the meeting was inserted into the database. |
date_start | string | The date and time when the meeting started. |
date_stop | string | The date and time when the meeting ended. |
duration | number | The total conference duration, measured in seconds. |
duration_audio | number | The duration of the meeting audio conferencing, measured in seconds. |
duration_control | number | The duration of the conference control usage during the meeting, measured in seconds. |
duration_data | number | The duration of the meeting during which some data was sent or received (e.g., the participants used the screensharing feature), measured in seconds. |
duration_meeting | number | The duration of the meeting, measured in seconds. |
duration_recording | number | The duration of the meeting during which the recording was made, measured in seconds. |
duration_video | number | The duration of the meeting during which the video conferencing was used, measured in seconds. |
endpoint_sid | string | The secure ID of the Conference endpoint associated with the meeting. |
has_recording | boolean | Whether or not the meeting was recorded. |
meeting_room_sid | string | The secure ID of the meeting room associated with the meeting. |
meeting_sid | string | The secure ID of the meeting which the system uses to identify it among other meetings. |
partner_sid | string | The secure ID of the partner with which the Conference endpoint is associated. |
unique_attendee_count | integer | The number of the unique attendees which took part in the meeting. |
video_attendee_count | integer | The number of the attendees which used video conferencing during the meeting. |
phonenumber_messaging_update Callback
The
phonenumber_messaging_update
callback response
{
"did_sid":"d17a5391-1831-4d6b-adf0-5ba9a47ea6ad",
"phonenumber":"13075220123",
"messaging":{"enabled":true,"status":"enabled"}
}
The phonenumber_messaging_update
callback is triggered when SMS/MMS messaging is enabled or disabled for a DID.
Attribute | Data Type | Description |
---|---|---|
did_sid | string | The secure ID of the rented DID. |
phonenumber | string | The phone number for the rented DID in the E.164 format. |
messaging | string | SMS/MMS messaging status for the rented DID. Consists of two parts:
|
phonenumber_order Callback
The ` phonenumber_order` callback response
{
"active_capabilities":4,
"callback_url":"https://example.com/sms-callback-url",
"campaign_sid": null,
"capabilities":7,
"classification_sid":"d1a732b9-8530-499c-926a-e85282fc7387",
"country_code":"CAN",
"did_group_sid":null,
"did_sid":"d713ea8a-c2ab-492f-85ac-83279ce4543e",
"in_country_format":"(236) 804-0634",
"international_format":"+1 236-804-0634",
"locality":null,
"lrn_sid":null,
"name":"N/A",
"partner_sid":"0a2015db-04dc-6fd1-8bd8-ebc2a815b58b",
"phonenumber":"12368040634",
"price":null,
"state":null,
"status":"assigned"
"string_key_1":null,
"string_key_2":null,
"trunk_group_sid":null
}
The phonenumber_order
callback is triggered when a DID from an external provider has been rented successfully.
Attribute | Data Type | Description |
---|---|---|
active_capabilities | integer | The rented DID active capabilities. |
callback_url | string | The URL that receives callback messages in JSON format with data about a rented DID from an external provider. |
capabilities | integer | The rented DID supported capabilities. |
classification_sid | string | The rented DID classification secure ID. |
country_code | string | The ISO 3166-1 alpha-3 code of the rented DID country. |
did_group_sid | string | The secure ID of the rented DID group. |
did_sid | string | The secure ID of the rented DID. |
in_country_format | string | The rented DID in a national format. |
international_format | string | The rented DID in an international format. |
locality | string | The locality or city of the rented DID. |
lrn_sid | string | The secure ID of the Location Routing Number assigned to this rented DID. |
name | string | The DID name. |
partner_sid | string | The secure ID of the partner associated with the rented DID. |
phonenumber | string | The phone number for the rented DID in the E.164 format. |
price | number | The price of the rented DID. |
state | string | The state or province of the rented DID. |
status | string | The current DID status. If the DID has been rented successfully, the status returned in this field should always be assigned . Otherwise, no callback will be sent. |
string_key_1 | string | A user-defined string key. |
string_key_2 | string | A user-defined string key. |
trunk_group_sid | string | The secure ID of the trunk group associated with the rented DID. |
Call Routing
CarrierX call routing connects IP communications infrastructure with the PSTN. Call routing works slightly differently depending on the direction of the communication, either inbound
or outbound
.
Hosted Endpoints: Conference, FlexML, and Mediator
Inbound communications come in from the PSTN and hit the CarrierX switches, which have configured trunks. Trunks are organized and managed in trunk groups. These entities hold settings that determine how the communication is processed. Outbound communications start from an IP-based application and move through a configurable SIP trunk, and are sent to the PSTN.
Third-Party Endpoints
Similar to hosted endpoints, inbound communications from the PSTN reach the CarrierX switches. The communications go through a configured trunk and then your external application. Outbound communications still come from your rented DIDs, but they go through your third-party configured endpoint, which integrates with an external IP. This communication still moves to the trunk and out to the PSTN.
The main difference is that the hosted endpoints (Conference, FlexML, and Mediator) are hosted by CarrierX. The third-party endpoint is hosted externally, not by CarrierX.
Transformations
Transformations look like the following
{
"action":"set_header_parameter",
"direction":"any",
"operands":["P-Charging-Vector","orig-ioi","privateSIP"]
}
Note that you can use regular expressions in transformations. For example, the following will check if the phone number has a 1 prefix and add one if not.
{
"transformations": [
{
"action": "rewrite_to",
"direction": "any",
"operands": ["^([2-9]\\d{9})$", "1\\1"]
},
{
"action": "rewrite_from",
"direction": "any",
"operands": ["^([2-9]\\d{9})$", "1\\1"]
}
]
}
Transformations are applied to endpoints, partners, DIDs, prefixes, trunk groups, and trunks. They modify values when an object is updated. Transformations have three parts: action
, direction
, and operands
.
-
action
is what type of modification will be made. For example,rewrite_to
rewrites the destination phone number. -
direction
determines to which direction of traffic the transformation will apply. For example, if we setdirection
tooutbound
, the specific transformation will apply to sending voice calls only. -
operands
are the items that are being acted upon. For example,rewrite_to
accepts two operands: the value to replace and the value that it is going to be replaced with.
Attribute | Data Type | Description |
---|---|---|
action | string | The action to be executed for the transformation. Refer to the sections below for a list of all actions. |
direction | string | The direction of communication that the transformation applies to. Values accepted in this field are:
|
operands | array | The values to be transformed. Operands can include set values or regular expressions. |
if_match
Sample if_match transformation
{
"action": "if_match",
"direction": "inbound",
"operands": [
"{{stir_verstat}}",
"TN-Validation-Failed",
"reject",
"forbidden"
]
}
The if_match
action is used to add conditions based on which other transformations are applied.
The action accepts from three to 100 operands: if_match(value, match, action, arg1, argX)
Operand | Data Type | Description |
---|---|---|
value | string | The string value with interpolated fields. |
match | string | The regular expression to match. |
action | string | The action to take if the regular expression succeeds. This action is another transformation. |
arg1 | string | The first argument of the transformation action. |
argX | string | The next arguments of the transformation action. |
lookup_cic
Sample lookup_cic transformation
{
"action": "lookup_cic",
"direction": "inbound",
"operands": [
"false",
"490",
"{{src}}",
"{{dst}}",
"cic",
"ignore",
"e164",
"guess"
]
}
The lookup_cic
action is used to lookup the CIC (Carrier Identification Code) information for calls to toll-free phone numbers.
The action accepts eight operands: lookup_cic(force, lata, phonenumber_src, phonenumber_dst, destination, on_failure, input_format_src, input_format_dst)
Operand | Data Type | Description |
---|---|---|
force | string | Force lookup mode. Values accepted in this field are:
false . |
lata | string | LATA: Local Access and Transport Area, a geographic code representing the location of the call origination. Note, that this operand is required but it does not have a default value, therefore it must always be specified. |
phonenumber_src | string | The call origination phone number. The default value is {{src}} . |
phonenumber_dst | string | The destination toll-free phone number we are looking up the CIC for. The default value is {{dst}} . |
destination | string | The destination field where the CIC will be stored. The default value is cic .
|
on_failure | string | The behavior on the transformation request failure. Values accepted in this field are:
ignore . |
input_format_src | string | The source number (phonenumber_src ) input format. The transformation will try to determine if the number is domestic or international, and only perform a lookup if it looks like domestic. Values accepted in this field are:
guess . |
input_format_dst | string | The destination number (phonenumber_dst ) input format. Values in this field are similar to those of the input_format_src above. |
lookup_cnam
Sample lookup_cnam transformation
{
"action": "lookup_cnam",
"direction": "inbound",
"operands": [
"true",
"{{src}}",
"{{src}}",
"from"
]
}
The lookup_cnam
action is used to lookup the CNAM information for the phone number.
The action accepts four operands: lookup_cnam(force, default, number, target)
Operand | Data Type | Description |
---|---|---|
force | string | Force lookup mode. Values accepted in this field are:
true . |
default | string | The default string to use if no CNAM information can be found. Values accepted in this field are: '' , {{src}} , etc. The default value is '' . |
number | string | The number to lookup. The default value is {{src}} . |
target | string | The target where the result will be saved. If this value is set to or from , it should be written to the name portion of the appropriate field. Otherwise, if it is set to a custom header name, it may be equal to the entire value of a custom header. The default value is from . |
lookup_rn
Sample lookup_rn transformation
{
"action": "lookup_rn",
"direction": "inbound",
"operands": [
"true",
"true",
"{{src}}",
"from",
"ignore",
"e164",
"domestic",
"e164_with_plus",
"passthrough"
]
}
The lookup_rn
action is used to lookup the routing number and return it so that it could be used instead of the source or destination number.
The action accepts nine operands: lookup_rn(force, always, phonenumber, destination, on_failure, input_format, output_format_domestic, output_format_international, output_format_guess_not_found)
Operand | Data Type | Description |
---|---|---|
force | boolean | Force lookup mode.
false . |
always | boolean | Always include the routing number.
false . |
phonenumber | string | The phone number to look up. Usually {{dst}} (destination) to look up the routing number for the called party or {{src}} (source) for the calling party. The default value is {{dst}} . |
destination | string | The destination field where the routing number will be stored.
to . |
on_failure | string | The behavior on the transformation request failure. Values accepted in this field are:
die . |
input_format | string | The destination number input format. The transformation will try to determine if number is domestic or international, and only perform lookup if it looks like domestic. Values accepted in this field are:
guess . |
output_format_domestic | string | The output format for the numbers considered domestic or with the type set to guess by the input_format operand and LRN found. Values accepted in this field are:
domestic . |
output_format_international | string | The output format for the numbers considered international by the input_format . Values accepted in this field are:
passthrough . |
output_format_guess_not_found | string | The output format if the destination number type is set to guess by the input_format operand and no lookup routing number was found. Values accepted in this field are:
passthrough , non-default values will be applied only if the always operand is set to true . |
reject
Sample reject transformation
{
"action": "reject",
"direction": "inbound",
"operands": [
"busy"
]
}
The reject
action is used to reject the call with one of the supported reasons.
The action accepts from one to two operands: reject(reason, message)
Operand | Data Type | Description |
---|---|---|
reason | string | The reject reason. Refer to the table below for a complete list of the reasons available. |
message | string | The additional message about the reject reason. This is an optional field. |
Reject Reasons
An example of the reject transformation with
intermediary-rejected
as a reject reason.My reason for rejecting the call
will be returned as the additional message to the caller as a part of theCall-Info
SIP header:
{
"action": "reject",
"direction": "inbound",
"operands": [
"intermediary-rejected",
"My reason for rejecting the call"
]
}
Sample
Call-Info
SIP header returned from the abovereject
transformation with theintermediary-rejected
reject reason
Call-Info: "My reason for rejecting the call"
Response Code | Reject Reason | Description |
---|---|---|
forbidden/rejected | 403 Forbidden | The destination understood the request, but is refusing to fulfill it. |
not-found | 404 Not Found | The destination could not be found. |
busy-here | 486 Busy Here | The destination is busy at the current location. |
bad-gateway | 502 Bad Gateway | Network is out of order and the call cannot be accepted. |
unavailable | 503 Service Unavailable | Temporary failure. |
busy | 600 Busy Everywhere | All possible destinations are busy. |
decline | 603 Decline | The destination does not wish to participate in the call or cannot do so. |
does-not-exist | 604 Does Not Exist Anywhere | The server has authoritative information that the requested destination does not exist anywhere. |
unwanted | 607 Unwanted | The destination does not want to accept the call from the current calling party. All future attempts from the same source are likely to be similarly rejected. |
intermediary-rejected | 608 Rejected | The intermediary machine or process rejected the call attempt from the calling party. This status code usually informs the calling party that the decision has been made by an analytics engine or some other similar engine. |
rewrite_codec
Sample rewrite_codec transformation (rewrites any incoming codec to
g722
)
{
"action": "rewrite_codec",
"direction": "any",
"operands": [
".*",
"g722"
]
}
Sample rewrite_codec transformation (if
{{orig_codec_src}}
is eitheramrwb
org722
, sets the codec strictly tog722
)
{
"action": "if_match",
"direction": "inbound",
"operands": [
"{{orig_codec_src}}",
"amrwb|g722",
"rewrite_codec",
".*",
"g722"
]
}
The rewrite_codec
action is used to rewrite the destination codec(s), i.e. change the codecs or change their priority order.
The action accepts two operands: rewrite_codec(pattern, replace)
Operand | Data Type | Description |
---|---|---|
pattern | string | The value to be replaced. Also accepts regular expressions. |
replace | string | The new value with which the pattern will be replaced. |
rewrite_from
Sample rewrite_from transformation
{
"action": "rewrite_from",
"direction": "any",
"operands": [
"^([2-9]\\d{9})$",
"1\\1"
]
}
The rewrite_from
action is used to rewrite the phone number of the incoming call.
The action accepts two operands: rewrite_from(pattern, replace)
Operand | Data Type | Description |
---|---|---|
pattern | string | The value to be replaced. Also accepts regular expressions. |
replace | string | The new value with which the pattern will be replaced. |
rewrite_from_header_param
Sample rewrite_from_header_param transformation
{
"action": "rewrite_from_header_param",
"direction": "any",
"operands": [
"cnam",
"(.{1,14})",
"\\1*"
]
}
The rewrite_from_header_param
action is used to replace the parameters of the From
header.
The action accepts three operands: rewrite_from_header_param(parameter, pattern, replace)
Operand | Data Type | Description |
---|---|---|
parameter | string | The parameter of the From header to change. The parameters, which can be safely changed without dropping the call, are: caller-rn , cnam , and isup-oli . |
pattern | string | The value to be replaced. Also accepts regular expressions. |
replace | string | The new value with which the pattern will be replaced. |
rewrite_header
Sample rewrite_header transformation
{
"action": "rewrite_header",
"direction": "any",
"operands": [
"X-Custom-Header",
":5060",
":6060",
"sip:10.1.5.200:5060"
]
}
The rewrite_header
action is used to replace the header (or a part of it) you specify as an operand with the new values, or create it, in the case the call data lacks it.
The action accepts four operands: rewrite_header(header, pattern, replace, default)
Operand | Data Type | Description |
---|---|---|
header | string | The header to change. |
pattern | string | The value to be replaced. Also accepts regular expressions. |
replace | string | The new value with which the pattern will be replaced. |
default | string | If the header is missing from the call, it will be created and set to the default value. |
rewrite_header_parameter
Sample rewrite_header_parameter transformation
{
"action": "rewrite_header_parameter",
"direction": "any",
"operands": [
"Remote-Party-ID",
"privacy",
"full",
"cnam",
"id"
]
}
The rewrite_header_parameter
action is used to replace the parameter of the header you specify as an operand with the new value, or create it, in the case the call data lacks it.
The action accepts five operands: rewrite_header_parameter(header, parameter, pattern, replace, default)
Operand | Data Type | Description |
---|---|---|
header | string | The header in which the parameter will be changed. |
parameter | string | The header parameter to change. |
pattern | string | The value to be replaced. Also accepts regular expressions. |
replace | string | The new value with which the pattern will be replaced. |
default | string | If the parameter is missing from the call, it will be created and set to the default value. |
rewrite_to
Sample rewrite_to transformation
{
"action": "rewrite_to",
"direction": "any",
"operands": [
"^([2-9]\\d{9})$",
"1\\1"
]
}
The rewrite_to
action is used to rewrite the destination phone number.
The action accepts two operands: rewrite_to(pattern, replace)
Operand | Data Type | Description |
---|---|---|
pattern | string | The value to be replaced. Also accepts regular expressions. |
replace | string | The new value with which the pattern will be replaced. |
rewrite_to_header_param
Sample rewrite_to_header_param transformation
{
"action": "rewrite_to_header_param",
"direction": "any",
"operands": [
"npdi",
"yes",
"no"
]
}
The rewrite_to_header_param
action is used to replace the parameters of the To
header.
The action accepts three operands: rewrite_to_header_param(parameter, pattern, replace)
Operand | Data Type | Description |
---|---|---|
parameter | string | The parameter of the To header to change. |
pattern | string | The value to be replaced. Also accepts regular expressions. |
replace | string | The new value with which the pattern will be replaced. |
set_header
Sample set_header transformation
{
"action": "set_header",
"direction": "any",
"operands": [
"X-Custom-Header",
"sip:10.1.5.200:5060"
]
}
The set_header
action is used to add a new header.
The action accepts two operands: set_header(header, value)
Operand | Data Type | Description |
---|---|---|
header | string | The header to be added. |
value | string | The value for the header. |
set_header_parameter
Sample set_header_parameter transformation
{
"action": "set_header_parameter",
"direction": "any",
"operands": [
"P-Charging-Vector",
"orig-ioi",
"privateSIP"
]
}
The set_header_parameter
action is used to set a parameter to an existing header.
The action accepts three operands: set_header_parameter(header, parameter, value)
Operand | Data Type | Description |
---|---|---|
header | string | The header which is going to be modified. |
parameter | string | The header parameter to be set. |
value | string | The value for the header parameter. If the value is "" and the header parameter exists, it will be deleted. |
set_user_data
Sample set_user_data transformation
{
"action": "set_user_data",
"direction": "any",
"operands": [
"identity",
"{{SipHeader_Identity}}"
]
}
The set_user_data
action is used to add custom user data to the call detail records. The transformation saves the data as a JSON object to the user_data
attribute of the Call Detail Record object.
The action accepts two operands: set_user_data(key, value)
Operand | Data Type | Description |
---|---|---|
key | string | A user-defined custom key that will be displayed as a part of the user_data attribute of the call detail record. |
value | string | A user-defined custom value of the key that will be displayed as a part of the user_data attribute of the call detail record. |
sms_normalize
Sample sms_normalize transformation
{
"action": "sms_normalize",
"direction": "outbound",
"operands": [
"e164",
"USA",
"to",
"ignore",
"e164"
]
}
By default, all phone numbers for the SMS Object are always treated as E.164 international numbers.
The sms_normalize
action is used to add a corresponding country prefix to the SMS Object from
and/or to
fields. This transformation is based on the Phonenumber Lookup object mechanism and the Phonenumber Lookup logic. With this transformation, for example, for all outbound messages you can indicate the country you need and by default all SMS messages with domestic number format in the to
field will be routed to phone numbers inside that country, i.e. the system will be automatically converting such numbers to the E.164 format.
The action accepts five operands: sms_normalize(guess, country_code, field, on_failure, output_format)
Operand | Data Type | Description |
---|---|---|
guess | string | Tells the system to make a guess that the DID this transformation is applied to is either an E.164 or a domestic (in-country) number. This operand is activated if the country_code lookup step (see below) results in finding out that the corresponding DID matches both, an E.164 and a domestic phone number. Values accepted in this field are:
e164 . If the guess step does not bring any result, the system proceeds to the on_failure step. |
country_code | string | The ISO 3166-1 alpha-3 code of the country. To check, whether this number is a domestic (in-country) number, the system uses the country_code query parameter, to see if the number passed could be valid in the country specified in the request. This operand the system that before routing any outbound SMS or accepting any inbound SMS without the + prefix, it should first check such phone number and verify whether it is a valid number in that country.If a valid number is found, the system adds the corresponding country code prefix to the phone number and the SMS is processed further (e.g. for the United Kingdom, the +44 prefix will be added), no further checks are made.If no valid number is found, the system tries to find a match for this number among domestic (in-country) and E.164 numbers. Here, tree options are possible:
country_code query parameter is not set, the system uses country_code =USA by default. |
field | string | The SMS Object field this transformation must be applied to. Valued accepted in this field are:
|
on_failure | string | The behavior on the transformation request failure. Only one value is accepted in this field:
|
output_format | string | The output format of the destination phone number. Only one value is accepted in this field:
|
stir_validate
Sample stir_validate transformation
{
"action": "stir_validate",
"direction": "any",
"operands": []
}
The stir_validate
action is used to validate the call and returns data that can be used with other transformations.
The action does not accept any operands, but instead enables the use of the following variables:
{{stir_attest}}
for the attestation level used for the call.{{stir_origid}}
for the ID of the call originator.{{stir_verstat}}
for the TN validation result (available values includeTN-Validation-Passed
,TN-Validation-Failed
, andNo-TN-Validation
).
API Reference
The Core API has the following sections: 10DLC Campaigns, Access Control, Apps, Batch, Calls, Countries, Endpoints, Billing, Lookup, OAuth, Partners, Phone Numbers, Push, Rating, Shortener, SMS, Storage, Trunk Groups, Text-To-Speech and Verification.
10DLC Campaigns
Originally, 10DLC is an abbreviation for a 10-digit long code phone number, i.e. a standard phone number in USA and Canada with a 3-digit area code and 7-digit local phone number. However, currently 10DLC is mainly referred to regulations applied to sending messages over a regular 10-digit long phone number. In order to use a phone number for messaging in the USA and Canada, a partner is required to register their company with the Campaign Registry and create a 10DLC campaign. As soon as the company and the 10DLC campaign are approved, the partner can associate their phone number with their campaign and start messaging to their customer base.
Campaign Object
This section outlines the Campaign object. The fields listed in the table below will be returned in a JSON object when a successful request has been made.
Sample Campaign object
{
"campaign_sid": "fef13cdd-2f65-4ed8-8272-de2a940d0cb5",
"external_id": "CVN1LXI"
"name": "My 10DLC Campaign",
"partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
}
Attribute | Data Type | Description |
---|---|---|
campaign_sid read only | string | An internal secure ID of the 10DLC campaign. |
external_id read only | string | The 10DLC campaign ID the Campaign Registry has assigned to your campaign upon its registration. |
name read only | string | The internal name of the 10DLC Campaign. |
partner_sid read only | string | The secure ID of the partner associated with the campaign |
Get 10DLC Campaigns
GET /10dlc/campaigns
Returns a list of registered 10DLC campaigns
curl -X GET \
'https://api.carrierx.com/core/v2/10dlc/campaigns' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a list of 10DLC campaigns
{
"count": 1,
"has_more": false,
"items": [
{
"campaign_sid": "fef13cdd-2f65-4ed8-8272-de2a940d0cb5",
"external_id": "CVN1LXI"
"name": "My 10DLC Campaign",
"partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
}
],
"limit": 1,
"offset": 0,
"pagination": {
"next": "https://api.carrierx.com/core/v2/10dlc/campaigns?limit=1&offset=1"
},
"total": 1
}
This request returns a list of registered 10DLC campaigns for the current partner.
GET | /10dlc/campaigns |
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Required Scopes
To get information about 10DLC campaigns, the partner must be authenticated.
Get 10DLC Campaign by SID
GET /10dlc/campaigns/{campaign_sid}
Returns a registered 10DLC campaign, targeted by secure ID
curl -X GET \
'https://api.carrierx.com/core/v2/10dlc/campaigns/fef13cdd-2f65-4ed8-8272-de2a940d0cb5' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the Campaign object
{
"campaign_sid": "fef13cdd-2f65-4ed8-8272-de2a940d0cb5",
"external_id": "CVN1LXI"
"name": "My 10DLC Campaign",
"partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
}
This request returns a 10DLC campaign, targeted by secure ID.
GET | /10dlc/campaigns/{campaign_sid} |
This request is enabled for Field Filtering.
Required Scopes
To get information about 10DLC campaigns, the partner must be authenticated.
Path Arguments
Parameter | Data Type | Description |
---|---|---|
campaign_sid required | string | The Campaign secure ID. |
Access Control
Access Control consists of two concepts—Access Control Rules and Access Control Lists. Access Control Rules (ACRs) are criteria that can be applied to calls and SMS to form the building blocks of CarrierX access control policies. Access Control Lists (ACLs) combine ACRs and policy statements to determine if an action will be allowed or rejected.
Access Control List Object
This section describes the elements of the Access Control List object. These fields and values make up the JSON object that gets returned with successful requests.
Sample Access Control List object
{
"access_control_rules": [
"dafd993d-0e99-4af9-b8fc-436fb01b0bbe",
"6fd782fa-c80b-4299-9b91-78797eb392e1"
],
"direction": "outbound",
"sms_action_false": null,
"sms_action_true": null,
"voice_action_false": null,
"voice_action_true": "reject503"
}
Attribute | Data Type | Description |
---|---|---|
access_control_rules read only | array | The list of access control rules secure IDs. Refer to the Access Control Rule object for more information about access control rules. |
direction read only | string | The direction for the access control list. Values accepted in this field are:
|
sms_action_false* read only | string | The action to be executed for SMS messages if no access control rules are applied. Values accepted in this field are accept and reject . |
sms_action_true* read only | string | The action to be executed for SMS messages if any access control rules are applied. Values accepted in this field are accept and reject . |
voice_action_false read only | string | The action to be executed for calls if no access control rules are applied. Values accepted in this field are:
|
voice_action_true read only | string | The action to be executed for calls if any access control rules are applied. Values accepted in this field are:
|
* Please note that for the Trunk Group and the Trunk objects these fields are always null
and read-only
because Trunk Groups and Trunks are used for voice only.
Look Up Effective ACLs for Calls
GET /accesscontrol/effective_acl/calls
Returns effective ACLs for calls
curl -X GET \
'https://api.carrierx.com/core/v2/accesscontrol/effective_acl/calls' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a list of Access Control List objects
{
"count": 1,
"has_more": false,
"items": [
{
"effective_acls": [
{
"access_control_rules": [
"dafd993d-0e99-4af9-b8fc-436fb01b0bbe",
"6fd782fa-c80b-4299-9b91-78797eb392e1"
],
"direction": "outbound",
"sms_action_false": null,
"sms_action_true": null,
"voice_action_false": null,
"voice_action_true": "reject503"
}
],
"layer": 1
}
],
"limit": 1,
"offset": 0,
"pagination": {},
"total": 1
}
This request returns a list of effective Access Control Lists (ACLs) for calls for the partner or trunk group, targeted by secure ID.
GET | /accesscontrol/effective_acl/calls |
This request is enabled for Field Filtering. Additionally, query arguments are used to narrow the results.
Required Scopes
To get information about Access Control Lists the partner must have one of the following scopes enabled:
accesscontrol.manage
accesscontrol.read
Query Arguments
Parameter | Data Type | Description |
---|---|---|
direction | string | The direction for the Access Control List. Values accepted in this field are:
|
partner_sid | string | The partner secure ID. |
trunk_group_sid | string | The trunk group secure ID. |
Look Up Effective ACLs for SMS
GET /accesscontrol/effective_acl/sms
Returns effective ACLS for SMS
curl -X GET \
'https://api.carrierx.com/core/v2/accesscontrol/effective_acl/sms' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a list of Access Control List objects
{
"count": 1,
"has_more": false,
"items": [
{
"effective_acls": [
{
"access_control_rules": [
"93525bae-f9a9-446b-b92a-7f421df7a11e"
],
"direction": "outbound",
"sms_action_false": null,
"sms_action_true": "accept",
"voice_action_false": null,
"voice_action_true": null
}
],
"layer": 1
}
],
"limit": 1,
"offset": 0,
"pagination": {},
"total": 1
}
This request returns the list of effective Access Control Lists (ACLs) for SMS for the partner, targeted by secure ID.
GET | /accesscontrol/effective_acl/sms |
This request is enabled for Field Filtering. Additionally, query arguments are used to narrow the results.
Required Scopes
To get information about Access Control Rules the partner must have one of the following scopes enabled:
accesscontrol.manage
accesscontrol.read
Query Arguments
Parameter | Data Type | Description |
---|---|---|
direction | string | The direction for the Access Control List. Values accepted in this field are:
|
partner_sid | string | The partner secure ID. |
Access Control Rule Object
This section describes the elements of the Access Control Rule object. These fields and values make up the JSON object that gets returned with successful requests.
Sample Access Control Rule object
{
"entries": [
"1800",
"1615"
],
"field": "to",
"name": "N/A",
"operation": "prefix",
"quantifier": "any",
"read_only": false,
"rule_sid": "c9109b54-13f2-4157-ba23-2984b3a207dc"
}
Attribute | Data Type | Description |
---|---|---|
entries create update | array | The list of entries to compare against the field value. |
field create update | string | The field from the call or SMS to check. This value will be used in comparison with entries . |
name create update | string | The access control rule name. The value will be set to N/A if not specified otherwise. |
operation create update | string | Determines how the value is checked. Values accepted in this field are:
|
quantifier create update | string | The type of comparison to be made between entries and field . Values accepted in this field are:
|
read_only read only | boolean | Shows whether the access control rule can be modified or not. Values accepted in this field are:
false for the rules created by the partner, true for the rules created by the parent partner. |
rule_sid read only | string | The access control rule secure ID. |
Create Access Control Rule
POST /accesscontrol/rules
Creates an access control rule
curl -X POST \
'https://api.carrierx.com/core/v2/accesscontrol/rules' \
-H 'Content-Type: application/json' \
--data-binary '{"field":"to", "quantifier":"any", "entries": ["1800","1615"], "operation":"prefix"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the Access Control Rule object
{
"entries": [
"1800",
"1615"
],
"field": "to",
"name": "N/A",
"operation": "prefix",
"quantifier": "any",
"read_only": false,
"rule_sid": "c9109b54-13f2-4157-ba23-2984b3a207dc"
}
This request adds a new Access Control Rule (ACR) for the currently logged in partner.
POST | /accesscontrol/rules |
Required Scopes
To create an Access Control Rule object, the partner must have one of the following scopes enabled:
accesscontrol.manage
accesscontrol.create
Body Arguments
JSON representation of the fields and values of the Access Control Rule object to be created.
Required fields to create an access control rule are:
entries
field
operation
quantifier
The field
parameter should contain the value against which messages or calls will be checked.
- The
calling
andcalled
field values are specific for voice calls. - The
from
(some legacy users may still see the old namingfrom_did
),to
(to_did
) andmessage
field values are specific for SMS.
Refer to this table to view all fields that appear in the Access Control Rule object.
Get Access Control Rules
GET /accesscontrol/rules
Returns access control rules matching the criteria in the request URL
curl -X GET \
'https://api.carrierx.com/core/v2/accesscontrol/rules?offset=0&limit=1' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a list of Access Control Rule objects
{
"count": 1,
"has_more": true,
"items": [
{
"entries": [
"18007"
],
"field": "called",
"name": "1st",
"operation": "prefix",
"quantifier": "any",
"read_only": true,
"rule_sid": "dafd993d-0e99-4af9-b8fc-436fb01b0bbe"
}
],
"limit": 1,
"offset": 0,
"pagination": {
"next": "https://api.carrierx.com/core/v2/accesscontrol/rules?limit=1&offset=1"
},
"total": 56
}
This request returns a list of Access Control Rules (ACRs) that match the given criteria, and that belong to the currently logged-in partner and parent partner.
GET | /accesscontrol/rules |
A partner will not be able to view ACRs created by sub-partners. The read_only
field shows whether or not the ACRs belong to the currently logged-in partner.
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Required Scopes
To get information about Access Control Rule objects, the partner must have one of the following scopes enabled:
accesscontrol.manage
accesscontrol.read
Get Access Control Rule by SID
GET /accesscontrol/rules/{rule_sid}
Returns an access control rule, targeted by secure ID
curl -X GET \
'https://api.carrierx.com/core/v2/accesscontrol/rules/dafd993d-0e99-4af9-b8fc-436fb01b0bbe' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the Access Control Rule object
{
"entries": [
"18007"
],
"field": "called",
"name": "1st",
"operation": "prefix",
"quantifier": "any",
"read_only": true,
"rule_sid": "dafd993d-0e99-4af9-b8fc-436fb01b0bbe"
}
This request returns data for a particular access control rule (ACR), targeted by secure ID.
GET | /accesscontrol/rules/{rule_sid} |
Returned ACRs apply to the partner and the parent partner.
This request is enabled for Field Filtering.
Required Scopes
To get information about an Access Control Rule object, the partner must have one of the following scopes enabled:
accesscontrol.manage
accesscontrol.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
rule_sid required | string | The Access Control Rule secure ID. |
Update Access Control Rule
PATCH /accesscontrol/rules/{rule_sid}
Updates the Access Control Rule object, targeted by secure ID, with the values in the request body
curl -X PATCH \
'https://api.carrierx.com/core/v2/accesscontrol/rules/c9109b54-13f2-4157-ba23-2984b3a207dc' \
-H 'Content-Type: application/json' \
--data-binary '{"operation":"exact"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the updated Access Control Rule object
{
"entries": [
"1800",
"1615"
],
"field": "to",
"name": "N/A",
"operation": "exact",
"quantifier": "any",
"read_only": false,
"rule_sid": "c9109b54-13f2-4157-ba23-2984b3a207dc"
}
This request updates an access control rule, targeted by secure ID.
PATCH | /accesscontrol/rules/{rule_sid} |
PUT | /accesscontrol/rules/{rule_sid} |
An Access Control Rule object can be updated using either a PATCH
or PUT
request.
-
A
PATCH
request can be used to update one or more attribute values. When using aPATCH
request, only the attributes specified in the request payload will be updated, all other attributes and values will remain the same. The access control rule secure ID is passed in the query URL, and the values to be modified are passed in the request body. -
A
PUT
request can be used to update an entire Access Control Rule object. The access control rule secure ID is passed in the query URL, and the entire Access Control Rule object is passed in the request body.
Required Scopes
To update an Access Control Rule object, the partner must have one of the following scopes enabled:
accesscontrol.manage
accesscontrol.update
Path Arguments
Parameter | Data Type | Description |
---|---|---|
rule_sid required | string | The access control rule secure ID. |
Body Arguments
JSON representation of the fields and values to be updated.
Fields that can be modified are:
entries
field
name
operation
quantifier
Refer to this table to view all fields that appear in the Access Control Rule object.
Delete Access Control Rule
DELETE /accesscontrol/rules/{rule_sid}
Deletes an Access Control Rule, targeted by secure ID
curl -X DELETE \
'https://api.carrierx.com/core/v2/accesscontrol/rules/c9109b54-13f2-4157-ba23-2984b3a207dc' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
204
status code with an empty body
This request deletes an Access Control Rule object, targeted by secure ID.
DELETE | /accesscontrol/rules/{rule_sid} |
ACRs can only be deleted when associated with the partner. Partners cannot delete an ACR for a parent partner when the value of read_only
is true
.
Required Scopes
To delete an Access Control Rule object, the partner must have one of the following scopes enabled:
accesscontrol.manage
accesscontrol.delete
Path Arguments
Parameter | Data Type | Description |
---|---|---|
rule_sid required | string | The secure ID of the Access Control Rule to delete. |
Apps
The Apps API is used to display the detailed records of the calls made to the Conference and Mediator endpoints.
With Conference endpoints, the events associated with calling into the meeting trigger the creation of the App DR Conf CDR objects. When the calling party joins the meeting, this creates a related App DR Conf MDR object.
With Mediator endpoints, the events associated with the calls made to the bindings or from the dialouts trigger creation of the App DR Mediator objects. These detail records become available after the call is ended.
App DR Conf CDR Object
This section describes the elements of the App DR Conf CDR object. These fields and values make up the JSON object that gets returned with successful requests.
Sample App DR Conf CDR Object object
{
"address_dst": "\"15162065515\" <sip:15162065515@11.22.33.44>",
"address_src": "<sip:+17605692222@12.34.56.78",
"audio_key": null,
"bridge": "conference-bridge",
"call_sid": "69057c3e-bb90-4ed3-9c53-000000001142",
"custom_call_type": null,
"custom_name": null,
"date_disconnected": "2021-12-14T10:04:04.000Z",
"date_insert": "2021-12-14T11:01:03.195Z",
"date_join": "2021-12-14T10:03:30.000Z",
"date_start": "2021-12-14T10:03:14.000Z",
"date_stop": "2021-12-14T10:04:04.000Z",
"direction": "inbound",
"disconnect_cause": 16,
"disconnect_originator": "src",
"disconnect_reason": "Normal",
"duration": "50",
"duration_meeting": "34",
"endpoint_sid": "e3ddc435-7b07-4f3a-98d5-4fe9be107652",
"meeting_room_sid": "f752b4a5-b821-4322-a26f-db5cfbf014ab",
"meeting_sid": "69057c3e-bb90-4ed3-9c53-000000000392",
"node": "11.22.33.44",
"number_dst": "15162065515",
"number_src": "+17605692222",
"partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
"role": "host",
"user_agent": "CX-IVS-SBC"
}
Attribute | Data Type | Description |
---|---|---|
address_dst read only | string | The fully qualified address of the called party which includes the SIP information with special characters formatted. |
address_src read only | string | The fully qualified address of the calling party which includes the SIP information with special characters formatted. |
bridge read only | string | The name of the bridge which handled the call. |
call_sid read only | string | The secure ID of the call which the system uses to identify it among other calls. |
custom_call_type read only | string | The special field used to identify the origin of the call. Values accepted in this field are:
|
custom_name read only | string | The custom name for the calling party set by the software used, web, or IVR with special characters formatted. |
date_disconnected read only | string | The date and time when the call was disconnected from the meeting. |
date_insert read only | string | The date and time when the detail record about the call was inserted into the database. |
date_join read only | string | The date and time when the calling party joined the meeting. |
date_start read only | string | The date and time when the call started. |
date_stop read only | string | The date and time when the call ended. |
direction read only | string | The call direction, either inbound or outbound . |
disconnect_cause read only | integer | The numeric SIP code used to describe the reason to drop the call. |
disconnect_originator read only | string | The initiator of the disconnection. Values accepted in this field are:
|
disconnect_reason read only | string | The detailed descriptive information about the reason to drop the call. |
duration read only | number | The total call duration, specified in seconds. |
duration_meeting read only | number | The duration of the caller’s participation in the meeting, specified in seconds. |
endpoint_sid read only | string | The secure ID of the Conference endpoint associated with the call. |
meeting_room_sid read only | string | The secure ID of the meeting room with which the meeting is associated. This field is available for the secured call flow type, and for the open call flow type when the calling party enters an access code for an existing meeting room. |
meeting_sid read only | string | The secure ID of the meeting in which the calling party participated. |
node read only | string | The IP address of the bridge node. |
number_dst read only | string | The called party phone number. |
number_src read only | string | The calling party phone number. |
partner_sid read only | string | The secure ID of the partner with which the Conference endpoint is associated. |
role read only | string | The role of the calling party in the meeting. Values accepted in this field are:
|
user_agent read only | string | The details about the user agent used by the calling party, if available. |
Get Conference Calls
GET /app/conference/calls
Returns Conference endpoint Call object call detail records matching the criteria in the request URL
curl -X GET \
'https://api.carrierx.com/core/v2/app/conference/calls' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
response code with a list of App DR Conf CDR objects
{
"count": 1,
"has_more": false,
"items": [
{
"address_dst": "\"15162065515\" <sip:15162065515@11.22.33.44>",
"address_src": "<sip:+17605692222@12.34.56.78",
"audio_key": null,
"bridge": "conference-bridge",
"call_sid": "69057c3e-bb90-4ed3-9c53-000000001142",
"custom_call_type": null,
"custom_name": null,
"date_disconnected": "2021-12-14T10:04:04.000Z",
"date_insert": "2021-12-14T11:01:03.195Z",
"date_join": "2021-12-14T10:03:30.000Z",
"date_start": "2021-12-14T10:03:14.000Z",
"date_stop": "2021-12-14T10:04:04.000Z",
"direction": "inbound",
"disconnect_cause": 16,
"disconnect_originator": "src",
"disconnect_reason": "Normal",
"duration": "50",
"duration_meeting": "34",
"endpoint_sid": "e3ddc435-7b07-4f3a-98d5-4fe9be107652",
"meeting_room_sid": "f752b4a5-b821-4322-a26f-db5cfbf014ab",
"meeting_sid": "69057c3e-bb90-4ed3-9c53-000000000392",
"node": "11.22.33.44",
"number_dst": "15162065515",
"number_src": "+17605692222",
"partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
"role": "host",
"user_agent": "CX-IVS-SBC"
}
],
"limit": 10,
"offset": 0,
"pagination": {},
"total": null
}
This request returns a list of call detail records related to the Conference Call objects.
GET | /app/conference/calls |
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Required Scopes
To get information about App DR Conf CDR objects, the partner must have one of the following scopes enabled:
app.manage
app.read
To view information about App DR Conf CDR objects for the inherited partner, the partner must additionally have the app.read_descendant
scope enabled.
Get Conference Call by SID
GET /app/conference/calls/{call_sid}
Returns a call detail record related to Conference call, targeted by secure ID
curl -X GET \
'https://api.carrierx.com/core/v2/app/conference/calls/69057c3e-bb90-4ed3-9c53-000000001142' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
response code with a serialized copy of the App DR Conf CDR object
{
"address_dst": "\"15162065515\" <sip:15162065515@11.22.33.44>",
"address_src": "<sip:+17605692222@12.34.56.78",
"audio_key": null,
"bridge": "conference-bridge",
"call_sid": "69057c3e-bb90-4ed3-9c53-000000001142",
"custom_call_type": null,
"custom_name": null,
"date_disconnected": "2021-12-14T10:04:04.000Z",
"date_insert": "2021-12-14T11:01:03.195Z",
"date_join": "2021-12-14T10:03:30.000Z",
"date_start": "2021-12-14T10:03:14.000Z",
"date_stop": "2021-12-14T10:04:04.000Z",
"direction": "inbound",
"disconnect_cause": 16,
"disconnect_originator": "src",
"disconnect_reason": "Normal",
"duration": "50",
"duration_meeting": "34",
"endpoint_sid": "e3ddc435-7b07-4f3a-98d5-4fe9be107652",
"meeting_room_sid": "f752b4a5-b821-4322-a26f-db5cfbf014ab",
"meeting_sid": "69057c3e-bb90-4ed3-9c53-000000000392",
"node": "11.22.33.44",
"number_dst": "15162065515",
"number_src": "+17605692222",
"partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
"role": "host",
"user_agent": "CX-IVS-SBC"
}
This request returns data for a Conference call, targeted by secure ID.
GET | /app/conference/calls/{call_sid} |
This request is enabled for Field Filtering.
Required Scopes
To get information about an App DR Conf CDR object, the partner must have one of the following scopes enabled:
app.manage
app.read
To view information about App DR Conf CDR objects for the inherited partner, the partner must additionally have the app.read_descendant
scope enabled.
Path Arguments
Parameter | Data Type | Description |
---|---|---|
call_sid required | string | The conference call secure ID. |
App DR Conf MDR Object
This section describes the elements of the App DR Conf MDR object. These fields and values make up the JSON object that gets returned with successful requests.
Sample App DR Conf MDR Object object
{
"attendee_count": 2,
"audio_attendee_count": 2,
"control_attendee_count": 0,
"data_attendee_count": 0,
"date_insert": "2021-12-14T11:01:20.224Z",
"date_start": "2021-12-14T10:02:26.000Z",
"date_stop": "2021-12-14T10:04:04.000Z",
"duration": "98",
"duration_audio": "98",
"duration_control": "0",
"duration_data": "0",
"duration_meeting": "98",
"duration_recording": "0",
"duration_video": "0",
"endpoint_sid": "e3ddc435-7b07-4f3a-98d5-4fe9be107652",
"has_recording": false,
"meeting_room_sid": "f752b4a5-b821-4322-a26f-db5cfbf014ab",
"meeting_sid": "69057c3e-bb90-4ed3-9c53-000000000392",
"partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
"unique_attendee_count": 2,
"video_attendee_count": 0
}
Attribute | Data Type | Description |
---|---|---|
attendee_count read only | integer | The total number of the meeting attendees. |
audio_attendee_count read only | integer | The number of the attendees which used audio conferencing during the meeting. |
control_attendee_count read only | integer | The number of the attendees which used conference controls during the meeting. |
data_attendee_count read only | integer | The number of the attendees which sent some data during the meeting. |
date_insert read only | string | The date and time when the detail record about the meeting was inserted into the database. |
date_start read only | string | The date and time when the meeting started. |
date_stop read only | string | The date and time when the meeting ended. |
duration read only | number | The total conference duration, measured in seconds. |
duration_audio read only | number | The duration of the meeting audio conferencing, measured in seconds. |
duration_control read only | number | The duration of the conference control usage during the meeting, measured in seconds. |
duration_data read only | number | The duration of the meeting during which some data was sent or received (e.g., the participants used the screensharing feature), measured in seconds. |
duration_meeting read only | number | The duration of the meeting, measured in seconds. |
duration_recording read only | number | The duration of the meeting during which the recording was made, measured in seconds. |
duration_video read only | number | The duration of the meeting during which the video conferencing was used, measured in seconds. |
endpoint_sid read only | string | The secure ID of the Conference endpoint associated with the meeting. |
has_recording read only | boolean | Whether or not the meeting was recorded. |
meeting_room_sid read only | string | The secure ID of the meeting room associated with the meeting. |
meeting_sid read only | string | The secure ID of the meeting which the system uses to identify it among other meetings. |
partner_sid read only | string | The secure ID of the partner with which the Conference endpoint is associated. |
unique_attendee_count read only | integer | The number of the unique attendees which took part in the meeting. |
video_attendee_count read only | integer | The number of the attendees which used video conferencing during the meeting. |
Get Conference Meetings
GET /app/conference/meetings
Returns Conference endpoint Meeting object detail records matching the criteria in the request URL
curl -X GET \
'https://api.carrierx.com/core/v2/app/conference/meetings' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
response code with a list of App DR Conf MDR objects
{
"count": 1,
"has_more": false,
"items": [
{
"attendee_count": 2,
"audio_attendee_count": 2,
"control_attendee_count": 0,
"data_attendee_count": 0,
"date_insert": "2021-12-14T11:01:20.224Z",
"date_start": "2021-12-14T10:02:26.000Z",
"date_stop": "2021-12-14T10:04:04.000Z",
"duration": "98",
"duration_audio": "98",
"duration_control": "0",
"duration_data": "0",
"duration_meeting": "98",
"duration_recording": "0",
"duration_video": "0",
"endpoint_sid": "e3ddc435-7b07-4f3a-98d5-4fe9be107652",
"has_recording": false,
"meeting_room_sid": "f752b4a5-b821-4322-a26f-db5cfbf014ab",
"meeting_sid": "69057c3e-bb90-4ed3-9c53-000000000392",
"partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
"unique_attendee_count": 2,
"video_attendee_count": 0
}
],
"limit": 10,
"offset": 0,
"pagination": {},
"total": null
}
This request returns a list of detail records related to the Conference Meeting objects.
GET | /app/conference/meetings |
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Required Scopes
To get information about App DR Conf MDR objects, the partner must have one of the following scopes enabled:
app.manage
app.read
To view information about App DR Conf MDR objects for the inherited partner, the partner must additionally have the app.read_descendant
scope enabled.
Get Conference Meeting by SID
GET /app/conference/meetings/{meeting_sid}
Returns a detail record related to Conference meeting, targeted by secure ID
curl -X GET \
'https://api.carrierx.com/core/v2/app/conference/meetings/69057c3e-bb90-4ed3-9c53-000000000392' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
response code with a serialized copy of the App DR Conf MDR object
{
"attendee_count": 2,
"audio_attendee_count": 2,
"control_attendee_count": 0,
"data_attendee_count": 0,
"date_insert": "2021-12-14T11:01:20.224Z",
"date_start": "2021-12-14T10:02:26.000Z",
"date_stop": "2021-12-14T10:04:04.000Z",
"duration": "98",
"duration_audio": "98",
"duration_control": "0",
"duration_data": "0",
"duration_meeting": "98",
"duration_recording": "0",
"duration_video": "0",
"endpoint_sid": "e3ddc435-7b07-4f3a-98d5-4fe9be107652",
"has_recording": false,
"meeting_room_sid": "f752b4a5-b821-4322-a26f-db5cfbf014ab",
"meeting_sid": "69057c3e-bb90-4ed3-9c53-000000000392",
"partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
"unique_attendee_count": 2,
"video_attendee_count": 0
}
This request returns data for a Conference meeting, targeted by secure ID.
GET | /app/conference/meetings/{meeting_sid} |
This request is enabled for Field Filtering.
Required Scopes
To get information about an App DR Conf MDR object, the partner must have one of the following scopes enabled:
app.manage
app.read
To view information about App DR Conf MDR objects for the inherited partner, the partner must additionally have the app.read_descendant
scope enabled.
Path Arguments
Parameter | Data Type | Description |
---|---|---|
meeting_sid required | string | The conference meeting secure ID. |
App DR Mediator Object
Sample App DR Mediator object
{
"attributes": {
"hide_origination_did": "true"
},
"date_insert": "2020-10-09T10:15:01.000Z",
"date_start": "2020-10-09T10:12:28.000Z",
"date_stop": "2020-10-09T10:12:43.000Z",
"date_talk": "2020-10-09T10:12:32.000Z",
"direction": "outbound",
"dr_sid": "2ce7599c-8391-4cc2-8e06-7b832f110e48",
"dtmf": null,
"duration": "15",
"endpoint_sid": "d59fbc20-3fda-4624-b58b-a8a4ef64b0a8",
"endpoint_type": "mediator",
"event_type": "dialout",
"number_dst": "14437317761",
"number_redirect": "15162065919",
"number_src": "12029021281",
"partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
"reference_sid": "89b3ef2c-222b-4bd7-bc46-084021e5a770",
"type": "mediator",
"version": 2
}
This section describes the elements of the App DR Mediator object. These fields and values make up the JSON object that gets returned with successful requests.
Attribute | Data Type | Description |
---|---|---|
attributes read only | object | The attributes of a binding or dialout. |
date_insert read only | string | The date and time when the call detail record was processed and added to the database. |
date_start read only | string | The date and time when the call started or SMS was created. |
date_stop read only | string | The date and time when the call stopped or SMS was delivered (with any status). |
date_talk read only | string | The date and time when the call was answered by the destination side. |
direction read only | string | The direction of the call or SMS. Values accepted in this field are:
|
dr_sid read only | string | The detail record secure ID. |
dtmf read only | string | The DTMF signals used during the call in the binding or dialout. |
duration read only | number | The call duration in seconds. The value is calculated as date_stop – date_start . |
endpoint_sid read only | string | The associated endpoint secure ID. |
endpoint_type read only | string | The associated endpoint type. Values accepted in this field are:
|
event_type read only | string | The type of the Mediator event. Values accepted in this field are:
|
number_dst read only | string | The destination number. |
number_redirect read only | string | The Mediator redirect number. |
number_src read only | string | The source number. |
partner_sid read only | string | The secure ID of the Partner, to whom this detail record belongs. |
reference_sid read only | string | The secure ID of the Mediator binding or dialout. |
type read only | string | The type of call. Values accepted in this field are:
|
version | integer | The version of the detail record as it comes from the source. |
Get Mediator CDRs
GET /app/mediator/calls
Returns Mediator endpoint call detail records matching the criteria in the request URL
curl -X GET \
'https://api.carrierx.com/core/v2/app/mediator/calls' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a list of App DR Mediator objects
{
"count": 1,
"has_more": false,
"items": [
{
"attributes": {
"hide_origination_did": "true"
},
"date_insert": "2020-10-09T10:15:01.000Z",
"date_start": "2020-10-09T10:12:28.000Z",
"date_stop": "2020-10-09T10:12:43.000Z",
"date_talk": "2020-10-09T10:12:32.000Z",
"direction": "outbound",
"dr_sid": "2ce7599c-8391-4cc2-8e06-7b832f110e48",
"dtmf": null,
"duration": "15",
"endpoint_sid": "d59fbc20-3fda-4624-b58b-a8a4ef64b0a8",
"endpoint_type": "mediator",
"event_type": "dialout",
"number_dst": "14437317761",
"number_redirect": "15162065919",
"number_src": "12029021281",
"partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
"reference_sid": "89b3ef2c-222b-4bd7-bc46-084021e5a770",
"type": "mediator",
"version": 2
}
],
"limit": 10,
"offset": 0,
"pagination": {},
"total": null
}
This request returns a list of call detail records related to the Mediator endpoint.
GET | /app/mediator/calls |
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Required Scopes
To get information about App DR Mediator objects, the partner must have one of the following scopes enabled:
app.manage
app.read
To view information about App DR Mediator objects for the inherited partner, the partner must additionally have the app.read_descendant
scope enabled.
Batch
Batch tasks create, edit, or delete phonenumber
, prefix
and file
objects.
Task Object
This section describes the elements of the batch task object.
Sample Task object
{
"data": {
"trunk_group_sid": "b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"
},
"date_created": "2019-10-30T20:47:32.517Z",
"date_modified": "2019-10-30T20:47:32.517Z",
"entries": [
"18053355112",
"18053355280"
],
"error_details": [],
"failure": null,
"field": "phonenumber",
"method": "PATCH",
"partner_sid": "923840ce-0b63-44a9-b4ce-09dc4181fb9d",
"processed": null,
"review": true,
"status": "created",
"success": null,
"task_sid": "2d9e546e-634b-4f6b-97ca-c2158163540c",
"total": null,
"type": "phonenumber"
}
Attribute | Data Type | Description |
---|---|---|
data create | array of objects | The payload for this request. This field should be empty for DELETE . |
date_created read only | string | The date and time when the task was created. |
date_modified read only | string | The date and time when the task was modified. |
entries create | array | This is based on field . Determines the existing entry. This value should be empty for POST . |
failure read only | integer | The count of unsuccessful operations. |
field create | string | The field used to determine the existing entry. This value only applies to the PATCH and DELETE methods. The value should be empty for POST . |
method create | string | The method used for the request, either POST , PATCH , or DELETE . |
partner_sid read only | string | The secure ID of the partner associated with the task. |
processed read only | integer | The count of processed operations. |
review create | boolean | Whether the task needs reviewing. |
status update | string | The status for the current task. Refer to the table below for a comprehensive list of statuses. |
success read only | integer | The count of successful operations. |
task_sid read only | string | The task secure ID. |
total read only | integer | The total count of operations. |
type create | string | The type of task, either phonenumber , prefix or file . |
status
Value | Description |
---|---|
approved | The task has been approved and will execute. |
cancelled | The task has been cancelled and will not execute. |
completed | The task is completed. |
created | The batch of objects has been created. |
pending_review | The task is pending review and has not been executed. |
queued | The task is in queue. |
running | The task is currently running. |
Create Task
POST /batch/tasks
Creates a batch task
curl -X POST \
'https://api.carrierx.com/core/v2/batch/tasks' \
-H 'Content-Type: application/json' \
--data-binary '{"method": "PATCH", "type": "phonenumber", "field":"phonenumber", "entries":["18053355112", "18053355280"], "data":{"trunk_group_sid": "b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"}}'\
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the Task object
{
"data": {
"trunk_group_sid": "b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"
},
"date_created": "2019-10-30T20:47:32.517Z",
"date_modified": "2019-10-30T20:47:32.517Z",
"entries": [
"18053355112",
"18053355280"
],
"error_details": [],
"failure": null,
"field": "phonenumber",
"method": "PATCH",
"partner_sid": "923840ce-0b63-44a9-b4ce-09dc4181fb9d",
"processed": null,
"review": true,
"status": "created",
"success": null,
"task_sid": "2d9e546e-634b-4f6b-97ca-c2158163540c",
"total": null,
"type": "phonenumber"
}
This request creates a batch task.
POST | /batch/tasks |
Required Scopes
To create a Task object, the partner must have one of the following scopes enabled:
batch.manage
batch.create
Body Arguments
JSON representation of the fields and values of the Task object to be created.
Required fields to create a batch task depend on the method
field value of the Task object:
“method” Field Value | Required Fields |
---|---|
"DELETE" |
entries , field , method , type |
"PATCH" |
data , entries , field , method , type |
"POST" |
data , method , type |
Refer to this table to view all fields that appear in the Task object.
Get Tasks
GET /batch/tasks
Returns tasks matching the criteria in the request URL
curl -X GET \
'https://api.carrierx.com/core/v2/batch/tasks' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a list of Task objects associated with the credentials
{
"count": 1,
"has_more": false,
"items": [
{
"data": {
"trunk_group_sid": "b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"
},
"date_created": "2019-10-30T20:47:32.000Z",
"date_modified": "2019-10-30T20:47:38.000Z",
"entries": [
"18053355112",
"18053355280"
],
"error_details": [],
"failure": 0,
"field": "phonenumber",
"method": "PATCH",
"partner_sid": "923840ce-0b63-44a9-b4ce-09dc4181fb9d",
"processed": 0,
"review": true,
"status": "pending_review",
"success": 0,
"task_sid": "2d9e546e-634b-4f6b-97ca-c2158163540c",
"total": 1,
"type": "phonenumber"
}
],
"limit": 10,
"offset": 0,
"pagination": {},
"total": 1
}
This request returns a list of tasks.
GET | /batch/tasks |
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Required Scopes
To get information about a Task object, the partner must have one of the following scopes enabled:
batch.manage
batch.read
Get Task by SID
GET /batch/tasks/{task_sid}
Returns a batch task, targeted by secure ID
curl -X GET \
'https://api.carrierx.com/core/v2/batch/tasks/2d9e546e-634b-4f6b-97ca-c2158163540c' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the Task object
{
"data": {
"trunk_group_sid": "b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"
},
"date_created": "2019-10-30T20:47:32.000Z",
"date_modified": "2019-10-30T20:47:38.000Z",
"entries": [
"18053355112",
"18053355280"
],
"error_details": [],
"failure": 0,
"field": "phonenumber",
"method": "PATCH",
"partner_sid": "923840ce-0b63-44a9-b4ce-09dc4181fb9d",
"processed": 0,
"review": true,
"status": "pending_review",
"success": 0,
"task_sid": "2d9e546e-634b-4f6b-97ca-c2158163540c",
"total": 2,
"type": "phonenumber"
}
This request returns data for a batch task, targeted by secure ID.
GET | /batch/tasks/{task_sid} |
This request is enabled for Pagination.
Required Scopes
To get information about a Task object, the partner must have one of the following scopes enabled:
batch.manage
batch.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
task_sid required | string | The secure ID of the task. |
Update Task
PATCH /batch/tasks/{task_sid}
Updates the Task object, targeted by secure ID, with the values in the request body
curl -X PATCH \
'https://api.carrierx.com/core/v2/batch/tasks/2d9e546e-634b-4f6b-97ca-c2158163540c' \
-H 'Content-Type: application/json' \
--data-binary '{"status":"approved"}'\
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the updated Task object
{
"data": {
"trunk_group_sid": "b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"
},
"date_created": "2019-10-30T20:47:32.000Z",
"date_modified": "2019-10-30T20:51:23.189Z",
"entries": [
"18053355112",
"18053355280"
],
"error_details": [],
"failure": 0,
"field": "phonenumber",
"method": "PATCH",
"partner_sid": "923840ce-0b63-44a9-b4ce-09dc4181fb9d",
"processed": 0,
"review": true,
"status": "approved",
"success": 0,
"task_sid": "2d9e546e-634b-4f6b-97ca-c2158163540c",
"total": 2,
"type": "phonenumber"
}
This request updates a task, targeted by secure ID.
PATCH | /batch/tasks/{task_sid} |
PUT | /batch/tasks/{task_sid} |
A Task object can be updated using either a PATCH
or PUT
request.
-
A
PATCH
request can be used to update one or more attribute values. When using aPATCH
request, only the attributes specified in the request payload will be updated, all other attributes and values will remain the same. The task secure ID is passed in the query URL, and the values to be modified are passed in the request body. -
A
PUT
request can be used to update an entire Task object. The task secure ID is passed in the query URL, and the entire Task object is passed in the request body.
Required Scopes
To update a Task object, the partner must have one of the following scopes enabled:
batch.manage
batch.update
Path Arguments
Parameter | Data Type | Description |
---|---|---|
task_sid required | string | The task secure ID. |
Body Arguments
JSON representation of the fields and values to be updated.
The only field that can be updated is status
if the current value is pending_review
. The status
can be changed to either approved
or cancelled
.
Refer to this table to view all fields that appear in the Task object.
Delete Task
DELETE /batch/tasks/{task_sid}
Deletes a batch task, targeted by secure ID
curl -X DELETE \
'https://api.carrierx.com/core/v2/batch/tasks/2630eb9b-55c2-4e29-9217-ed133e2f22d6' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
204
status code with an empty body
This request deletes a Task object, targeted by task secure ID.
DELETE | /batch/tasks/{task_sid} |
Required Scopes
To delete a Task object, the partner must have one of the following scopes enabled:
batch.manage
batch.delete
Batch Review
When you create a batch task, it has an option to review the items. To enable it, the review
field of the Task object must be set to true
.
To see the review items and check if they are valid or need corrections, you can use the Get Task Review Items by SID method. It will return the Batch Review Response object with the list of the items, which can be reviewed.
The Download CSV of Task Review Items by SID method can also be used to download the list of the task review items in the CSV format for a more convenient visual representation.
If the changes look correct, you can make a PATCH
or PUT
request to change the status
from pending_review
to approved
. If the items look incorrect, the batch request can be prevented from proceeding by changing the status
to cancelled
.
Batch Review Response Object
Attribute | Data Type | Description |
---|---|---|
method read only | string | The batch review method. Values accepted in this field are: DELETE , GET , HEAD , OPTIONS , PATCH , POST , PUT , and TRACE . |
review_items read only | array of objects | Items to be reviewed before approving the batch task. Refer to the table below for more information. |
type read only | string | The batch task type. Values accepted in this field are phonenumber , prefix or file . |
Batch Review Item Object
Attribute | Data Type | Description |
---|---|---|
description read only | string | The batch review item description. |
fields read only | object | The batch review item fields, which require reviewing. |
sid read only | string | The batch review item secure ID. |
version read only | integer | The batch review item version. |
Get Task Review Items by SID
GET /batch/tasks/{task_sid}/review_items
Returns batch task review items, targeted by task secure ID
curl -X GET \
'https://api.carrierx.com/core/v2/batch/tasks/2630eb9b-55c2-4e29-9217-ed133e2f22d6/review_items' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of any associated review items
{
"method": "PATCH",
"review_items": [
{
"description": "18053355280",
"fields": {
"trunk_group_sid": [
null,
"b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"
]
},
"sid": "97de0cef-4c1a-478a-bb7e-e45fdca03035",
"version": 1
},
{
"description": "18053355112",
"fields": {
"trunk_group_sid": [
null,
"b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"
]
},
"sid": "0493d917-e23c-41db-8067-0c986df71007",
"version": 1
}
],
"type": "phonenumber"
}
This request returns task review items associated with the task secure ID.
GET | /batch/tasks/{task_sid}/review_items |
This request is enabled for Pagination.
Required Scopes
To get information about task review items the partner must have one of the following scopes enabled:
batch.manage
batch.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
task_sid required | string | The secure ID of the task. |
Download CSV of Task Review Items by SID
GET /batch/tasks/{task_sid}/review_items.csv
Returns task review items for a partner in the CSV format
curl -X GET \
'https://api.carrierx.com/core/v2/batch/tasks/2630eb9b-55c2-4e29-9217-ed133e2f22d6/review_items.csv' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code and a CSV download
This request returns a CSV of all task review items associated with the task secure ID.
GET | /batch/tasks/{task_sid}/review_items.csv |
This request is enabled for Field Filtering.
Required Scopes
To get a CSV of all task review items the partner must have one of the following scopes enabled:
batch.manage
batch.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
task_sid required | string | The secure ID of the task. |
Task Error Detail Object
This section describes the elements of the Batch Task Error Detail object.
Sample Task Error Detail object
{
"items": [
{
"error": {
"message": "object validation error",
"errors": [
{
"field": "phonenumber",
"message": "this phonenumber already exists",
"reference_sid": "940f3315-9ae7-4a1a-a66c-2df33933e10c"
}
]
}
"key": "{\"phonenumber\":19796101570}",
}
]
}
Attribute | Data Type | Description |
---|---|---|
error read only | object | The error detail error object. |
key read only | object | The error detail key object. |
Get Batch Task Error Details
GET /batch/tasks/{task_sid}/errors
Returns error details data for a batch task, targeted by secure ID
curl -X GET \
'https://qa-api.carrierx.com/core/v2/batch/tasks/2ab7081f-db4a-42b3-b7ed-74e1019f30a6/errors?offset=0&limit=1000' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a list of Error Detail objects
{
"items": [
{
"error": {
"message": "object validation error",
"errors": [
{
"field": "phonenumber",
"message": "this phonenumber already exists",
"reference_sid": "940f3315-9ae7-4a1a-a66c-2df33933e10c"
}
]
}
"key": "{\"phonenumber\":19796101570}",
}
]
}
This request returns error details data for a batch task, targeted by secure ID.
GET | /batch/tasks/{task_sid}/errors |
This request is enabled for Pagination.
Required Scopes
To get information about a Task object, the partner must have one of the following scopes enabled:
batch.manage
batch.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
task_sid required | string | The secure ID of the batch task. |
Billing
The Billing API allows the partners to get information about invoices and control their subscriptions.
An Invoice object is automatically created when a new partner is added to the system. One invoice exists for each partner and is updated when new charges occur.
In general, CarrierX invoice items can be of three types:
- DID rentals,
- event-based, e.g. calls, messaging, lookup, TTS requests to the API, etc.,
- subscription-based, i.e. any recurring regular monthly charges.
A Rate Subscription object is a customizable, recurring invoice item that is billed each month. It allows the Partners to view their subscriptions and their details. Every subscription has a price
, which is composed of a certain quantity
of items (units) the Partner is subscribed to and the rate
, which is the cost of one subscription unit
(price
== rate
* quantity
).
Invoice Object
This section describes the elements of the Invoice object. These fields and values make up the JSON object that gets returned with successful requests.
Sample Invoice object
{
"amount": "0.38",
"amount_due": "0",
"amount_tax": "0.32",
"balance_forward": "-0.45",
"balance_previous": "-351.91",
"date_billing_period_end": "2019-01-19T23:59:59.000Z",
"date_billing_period_start": "2018-12-20T00:00:00.000Z",
"date_charge_expected": "2019-01-19T23:59:59.000Z",
"date_charged": null,
"date_created": "2018-12-19T23:30:01.000Z",
"date_issued": null,
"display_id": "004",
"invoice_items": [
{
"amount": "0.37",
"country_code": "USA",
"date_billing_period_end": "2019-01-19T23:59:59.000Z",
"date_billing_period_start": "2018-12-20T00:00:00.000Z",
"direction": "inbound",
"type": "toll",
"usage": 8880
},
{
"amount": "0",
"country_code": "USA",
"date_billing_period_end": "2023-07-04T23:59:59.000Z",
"date_billing_period_start": "2023-06-06T00:00:00.000Z",
"type": "sms_enablement",
"usage": 1,
}
],
"invoice_sid": "4169705e-4284-482f-8e72-e962a8aaad9d",
"paid": false,
"partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
"pay_items": [],
"status": "open",
"tax_items": [
{
"amount": "0.32",
"jurisdiction": "federal",
"type": "fed_universal_service_fund"
}
]
}
Attribute | Data Type | Description |
---|---|---|
amount read only | number | The amount on the invoice. This is not necessarily due at this time. |
amount_due read only | number | The amount due. |
amount_tax read only | number | The total of the tax items included on the invoice. |
balance_forward read only | number | The balance that will be used as balance_previous for the next invoice. |
balance_previous read only | number | The previous balance on the invoice. |
date_billing_period_end read only | string | The date and time when the billing period ends. |
date_billing_period_start read only | string | The date and time when the billing period begins. |
date_charge_expected read only | string | The date and time when the invoice will be charged. |
date_charged read only | string | The date and time when the invoice was charged. |
date_created read only | string | The date and time when the invoice was created. |
date_issued read only | string | The date and time when the invoice was issued. |
display_id read only | string | The ID on the rendered invoice. |
invoice_items read only | array of objects | The details about each of the invoice items. Refer to the table below for more information. |
invoice_sid read only | string | The invoice secure ID. |
paid read only | boolean | Shows if the invoice has been paid. Values accepted in this field are: true and false . |
partner read only | object | The Partner object associated with the invoice. This field is displayed if with_related is set to true when performing the GET queries. |
partner_sid read only | string | The secure ID of the partner associated with the invoice. |
pay_items read only | array of objects | The payments made while the invoice was open. Refer to the table below for more information. |
status read only | string | The invoice status. Values accepted in this field are:
|
tax_items read only | array of objects | The tax items details. Refer to the table below for more information. |
Invoice Item Object
Attribute | Data Type | Description |
---|---|---|
amount read only | number | The invoice item price total. |
country_code read only | string | The ISO 3166-1 alpha-3 code of the service type associated with this invoice item. |
date_billing_period_end read only | string | The date and time when this item billing period ended. |
date_billing_period_start read only | string | The date and time when this item billing period started. |
direction read only | string | The direction of the call or SMS/MMS, either inbound or outbound . |
type read only | string | The type of call, SMS/MMS, transcription, or text-to-speech used. Values accepted in this field are:
|
usage read only | integer | The number of times the item was used. |
Invoice Pay Item Object
Attribute | Data Type | Description |
---|---|---|
amount read only | number | The amount of payment. |
billing_method read only | object | The billing method that was used for the payment. |
check_number read only | string | The check number that was used for the payment. |
date_charged read only | string | The date and time when the payment was made. |
pay_item_sid read only | string | The pay item secure ID. |
status read only | string | The invoice payment status. Values accepted in this field are:
|
type read only | string | The invoice payment type. Values accepted in this field are:
|
Invoice Tax Item Object
Attribute | Data Type | Description |
---|---|---|
amount read only | number | The amount of taxes. |
jurisdiction read only | string | The invoice tax jurisdiction. Values accepted in this field are: county , county_local , federal , local , other , state , state_county_local , and unincorporated . |
type read only | string | The invoice tax type. Values accepted in this field are: business_and_occupation_tax , ca_teleconnect_fund , carrier_gross_receipts , district_tax , district_tax_residential , e911_tax , e911_tax_business , e911_tax_pbx_trunk_line , e911_tax_residential , excise_tax , fed_telecommunications_relay_service , fed_universal_service_fund , fed_usf_a_school , federal_excise_tax , franchise_tax , license_tax , license_tax_business , ny_mctd_184a , ny_mctd_186c , optional_telecommunications_infrastructure_maintenance_fee , puc_fee , sales_tax , sales_tax_business , sales_web_hosting , service_tax , special_tax , state_deaf_and_disabled_fund , state_high_cost_fund , state_poison_control_fund , state_universal_service_fund , statutory_gross_receipts , surcharge , telecom_relay_surcharge , telecommunications_assistance_service_fund , telecommunications_infrastructure_fund , telecommunications_infrastructure_maintenance_fee , transit_tax , trs_business , universal_lifeline_telephone_service_charge , universal_service_fund_access_trunk_line , universal_service_fund_business_line , utility_users_tax , and utility_users_tax_business . |
Get Invoices
GET /billing/invoices
Returns invoices matching the criteria in the request URL
curl -X GET \
'https://api.carrierx.com/core/v2/billing/invoices?limit=1' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a list of Invoice objects
{
"count": 1,
"has_more": true,
"items": [
{
"amount": "0.38",
"amount_due": "0",
"amount_tax": "0.32",
"balance_forward": "-0.45",
"balance_previous": "-351.91",
"date_billing_period_end": "2019-01-19T23:59:59.000Z",
"date_billing_period_start": "2018-12-20T00:00:00.000Z",
"date_charge_expected": "2019-01-19T23:59:59.000Z",
"date_charged": null,
"date_created": "2018-12-19T23:30:01.000Z",
"date_issued": null,
"display_id": "004",
"invoice_items": [
{
"amount": "0.37",
"country_code": "USA",
"date_billing_period_end": "2019-01-19T23:59:59.000Z",
"date_billing_period_start": "2018-12-20T00:00:00.000Z",
"direction": "inbound",
"type": "toll",
"usage": 8880
},
{
"amount": "0.01",
"country_code": "USA",
"date_billing_period_end": "2019-01-19T23:59:59.000Z",
"date_billing_period_start": "2018-12-20T00:00:00.000Z",
"direction": "outbound",
"type": "toll",
"usage": 60
},
{
"amount": "0",
"country_code": "USA",
"date_billing_period_end": "2023-07-04T23:59:59.000Z",
"date_billing_period_start": "2023-06-06T00:00:00.000Z",
"type": "sms_enablement",
"usage": 2,
}
],
"invoice_sid": "4169705e-4284-482f-8e72-e962a8aaad9d",
"paid": false,
"partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
"pay_items": [],
"status": "open",
"tax_items": [
{
"amount": "0.32",
"jurisdiction": "federal",
"type": "fed_universal_service_fund"
}
]
}
],
"limit": 1,
"offset": 0,
"pagination": {
"next": "https://api.carrierx.com/core/v2/billing/invoices?limit=1&offset=1"
},
"total": 4
}
This request returns a list of invoices.
GET | /billing/invoices |
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Required Scopes
To get information about Invoice objects, the partner must have one of the following scopes enabled:
invoices.manage
invoices.read
Query Arguments
Parameter | Data Type | Description |
---|---|---|
with_related | boolean | Determines if the partner information related to the invoice should be shown. Values accepted in this field are true and false . The default value is false . |
Get Invoice by SID
GET /billing/invoices/{invoice_sid}
Returns an invoice, targeted by secure ID
curl -X GET \
'https://api.carrierx.com/core/v2/billing/invoices/4169705e-4284-482f-8e72-e962a8aaad9d' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the Invoice object
{
"amount": "0.38",
"amount_due": "0",
"amount_tax": "0.32",
"balance_forward": "-0.45",
"balance_previous": "-351.91",
"date_billing_period_end": "2019-01-19T23:59:59.000Z",
"date_billing_period_start": "2018-12-20T00:00:00.000Z",
"date_charge_expected": "2019-01-19T23:59:59.000Z",
"date_charged": null,
"date_created": "2018-12-19T23:30:01.000Z",
"date_issued": null,
"display_id": "004",
"invoice_items": [
{
"amount": "0.37",
"country_code": "USA",
"date_billing_period_end": "2019-01-19T23:59:59.000Z",
"date_billing_period_start": "2018-12-20T00:00:00.000Z",
"direction": "inbound",
"type": "toll",
"usage": 8880
},
{
"amount": "0.01",
"country_code": "USA",
"date_billing_period_end": "2019-01-19T23:59:59.000Z",
"date_billing_period_start": "2018-12-20T00:00:00.000Z",
"direction": "outbound",
"type": "toll",
"usage": 60
},
{
"amount": "0",
"country_code": "USA",
"date_billing_period_end": "2023-07-04T23:59:59.000Z",
"date_billing_period_start": "2023-06-06T00:00:00.000Z",
"type": "sms_enablement",
"usage": 2,
}
],
"invoice_sid": "4169705e-4284-482f-8e72-e962a8aaad9d",
"paid": false,
"partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
"pay_items": [],
"status": "open",
"tax_items": [
{
"amount": "0.32",
"jurisdiction": "federal",
"type": "fed_universal_service_fund"
}
]
}
This request returns data for an invoice, targeted by secure ID.
GET | /billing/invoices/{invoice_sid} |
This request is enabled for Field Filtering.
Required Scopes
To get information about an Invoice object, the partner must have one of the following scopes enabled:
invoices.manage
invoices.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
invoice_sid required | string | The invoice secure ID. |
Query Arguments
Parameter | Data Type | Description |
---|---|---|
with_related | boolean | Determines if the partner information related to the invoice should be shown. Values accepted in this field are true and false . The default value is false . |
Get Invoice HTML Report by SID
GET /billing/invoices/{invoice_sid}.html
Returns an invoice, targeted by secure ID, in the HTML format
curl -X GET \
'https://api.carrierx.com/core/v2/billing/invoices/6765ca8a-91c7-4241-98c6-42803de77e74.html' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with the invoice in the HTML format
This request returns data for a particular invoice in the HTML format. If the request succeeds, there will be a download link.
GET | /billing/invoices/{invoice_sid}.html |
Required Scopes
To get an invoice in the HTML format the partner must have one of the following scopes enabled:
invoices.manage
invoices.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
invoice_sid required | string | The invoice secure ID. |
Send Invoice HTML Report by SID to Email Addresses
POST /billing/invoices/{invoice_sid}.html/emails
Sends an invoice, targeted by secure ID, in the HTML format to the email addresses specified in the request
curl -X POST \
'https://api.carrierx.com/core/v2/billing/invoices/6765ca8a-91c7-4241-98c6-42803de77e74.html/emails' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-binary 'emails=john.doe%40mail.com' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
204
status code and sends the invoice in the HTML format to an email address
This request sends this particular invoice in the HTML format to the email addresses specified in the request.
POST | /billing/invoices/{invoice_sid}.html/emails |
Required Scopes
To send an invoice in the HTML format to an email address the partner must have one of the following scopes enabled:
invoices.manage
invoices.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
invoice_sid required | string | The invoice secure ID. |
Body Arguments
The body contains the list of the email addresses in the URL-encoded format this invoice must be sent to. If several email addresses are passed, they must be separated with commas also in the URL-encoded format.
Get Invoice PDF Report by SID
GET /billing/invoices/{invoice_sid}.pdf
Returns an invoice, targeted by secure ID, in the PDF format
curl -X GET \
'https://api.carrierx.com/core/v2/billing/invoices/6765ca8a-91c7-4241-98c6-42803de77e74.pdf' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with the invoice in the PDF format
This request returns data for a particular invoice in the PDF format. If the request succeeds, there will be a download link.
GET | /billing/invoices/{invoice_sid}.pdf |
Required Scopes
To get an invoice in the PDF format the partner must have one of the following scopes enabled:
invoices.manage
invoices.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
invoice_sid required | string | The invoice secure ID. |
Send Invoice PDF Report by SID to Email Addresses
POST /billing/invoices/{invoice_sid}.pdf/emails
Sends an invoice, targeted by secure ID, in the PDF format to the email addresses specified in the request
curl -X POST \
'https://api.carrierx.com/core/v2/billing/invoices/6765ca8a-91c7-4241-98c6-42803de77e74.pdf/emails' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-binary 'emails=john.doe%40mail.com' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
204
status code and sends the invoice in the PDF format to an email address
This request sends this particular invoice in the PDF format to the email addresses specified in the request.
POST | /billing/invoices/{invoice_sid}.pdf/emails |
Required Scopes
To send an invoice in the PDF format to an email address the partner must have one of the following scopes enabled:
invoices.manage
invoices.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
invoice_sid required | string | The invoice secure ID. |
Body Arguments
The body contains the list of the email addresses in the URL-encoded format this invoice must be sent to. If several email addresses are passed, they must be separated with commas also in the URL-encoded format.
Rate Subscription Object
This section describes the elements of the Rate Subscription object. The Rate Subscription Object describes a monthly charge that appears on the associated partner’s invoice. These fields and values make up the JSON object that gets returned with successful requests.
Sample Rate Subscription object
{
"count": 1,
"has_more": true,
"items": [
{
"date_start": "2024-07-31T00:00:00.000Z",
"date_stop": "2024-09-31T23:59:59.000Z",
"display_name": "Application Hosting/Maintenance",
"name": "Application Hosting/Maintenance",
"partner_sid": "cee93bf3-5746-43fe-b1a2-822c05fef687",
"price": "0.01",
"quantity": "1",
"rate": "0.01",
"subscription_sid": "f61a205c-8fc2-435a-9233-e27bed232b04",
"type": "static"
},
]
"limit": 1,
"offset": 0,
"pagination": {
"next": "https://api.carrierx.com/core/v2/billing/subscriptions?limit=1&offset=1"
},
"total": 2
}
Attribute | Data Type | Description |
---|---|---|
date_start read only | string | The date and time when this subscription becomes active, and charges start to apply. The default value is the first day of the next billing period. |
date_stop read only | string | The date and time when this subscription becomes inactive and, and charges cease to apply. The default value is null . |
display_name read only | string | The subscription name that appears on the customer invoice. The length is limited to 25 characters. |
name read only | string | An internal arbitrary, human readable subscription name. |
partner_sid read only | string | The secure ID of the Partner this subscription belongs to. |
price read only | number | The calculated total price for this subscription: rate * quantity . |
quantity read only | number | The quantity of units in this subscription. |
rate read only | number | The cost in USD for 1 unit of quantity of this subscription. |
subscription_sid read only | string | The subscription secure ID. |
type read only | string | The subscription type. The only value returned in this field is static , which means a regular subscription type. |
Get Subscriptions
GET /billing/subscriptions
Returns subscriptions matching the criteria in the request URL
curl -X GET \
'https://api.carrierx.com/core/v2/billing/subscriptions?limit=1' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a list of Rate Subscription objects
{
"count": 1,
"has_more": true,
"items": [
{
"date_start": "2024-07-31T00:00:00.000Z",
"date_stop": "2024-09-31T23:59:59.000Z",
"display_name": "Application Hosting/Maintenance",
"name": "Application Hosting/Maintenance",
"partner_sid": "cee93bf3-5746-43fe-b1a2-822c05fef687",
"price": "0.01",
"quantity": "1",
"rate": "0.01",
"subscription_sid": "f61a205c-8fc2-435a-9233-e27bed232b04",
"type": "static"
},
]
"limit": 1,
"offset": 0,
"pagination": {
"next": "https://api.carrierx.com/core/v2/billing/subscriptions?limit=1&offset=1"
},
"total": 2
}
This request returns a list of subscriptions.
GET | /billing/subscriptions |
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Get Subscription by SID
GET /billing/subscriptions/{subscription_sid}
Returns a subscription, targeted by secure ID
curl -X GET \
'https://api.carrierx.com/core/v2/billing/subscriptions/f61a205c-8fc2-435a-9233-e27bed232b04' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the Invoice object
{
"date_start": "2024-07-31T00:00:00.000Z",
"date_stop": "2024-09-31T23:59:59.000Z",
"display_name": "Application Hosting/Maintenance",
"name": "Application Hosting/Maintenance",
"partner_sid": "cee93bf3-5746-43fe-b1a2-822c05fef687",
"price": "0.01",
"quantity": "1",
"rate": "0.01",
"subscription_sid": "f61a205c-8fc2-435a-9233-e27bed232b04",
"type": "static"
}
This request returns data for a subscription, targeted by secure ID.
GET | /billing/subscriptions/{subscription_sid} |
This request is enabled for Field Filtering.
Path Arguments
Parameter | Data Type | Description |
---|---|---|
subscription_sid required | string | The subscription secure ID. |
Calls
Calls are communications between two or more phone numbers.
Call Detail Record Object
This section describes the elements of the Call Detail Record object. These fields and values make up the JSON object that gets returned with successful requests.
Sample Call Detail Record object
{
"cic": null,
"cic_original": null,
"cic_transformed": null,
"codec_dst": "g722"
"codec_src": "amrwb",
"date_insert": "2019-01-18T15:35:03.000Z",
"date_start": "2019-01-18T15:32:15.589Z",
"date_stop": "2019-01-18T15:32:19.839Z",
"date_talk": "2019-01-18T15:32:16.535Z",
"direction": "inbound",
"disconnect_originator": "DST",
"diversion_dst": "+15162065451",
"diversion_src": "+15162065451",
"dr_sid": "c02a73b2-8401-459a-af7e-f4cc3eee7854",
"duration": "4.25015",
"duration_billing": "60",
"endpoint_sid_dst": "1ce5a6da-7d72-448a-ab81-897fe24b8f02",
"endpoint_sid_src": "7fc3e7ea-a0df-4de1-836f-50318ed66466",
"identity": null,
"ip_dst": "10.222.2.197:5060",
"ip_src": "162.251.180.18",
"number_billing": "15162065451",
"number_dst": "15162065451",
"number_dst_original": null,
"number_dst_transformed": null,
"number_external": "15012678830",
"number_src": "+15012678830",
"number_src_original": null,
"number_src_transformed": null,
"partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
"price": "0.0025",
"price_lcr_dst": "0.0025",
"price_lcr_src": null,
"rate": "0.0025",
"rate_lcr_dst": "0.005",
"rate_lcr_src": null,
"sipcallid_dst": "11b5b29c3486cac52a7d5baa52c937c9@12.7.193.174",
"sipcallid_src": "428ac5df4582bea66501f7d45199a18d@162.251.180.24",
"sipcause": "200",
"stir_attest" : "A",
"stir_identity" : "false",
"stir_orig_id" : "+15012678830",
"stir_signing_entity" : "carrierX",
"stir_verstat": null,
"transcoded": true,
"trunk_group_sid_dst": "cf7db13f-5c63-4c62-a447-fe3008cd72ef",
"trunk_group_sid_src": null,
"trunk_sid_dst": "7098d9f8-c8f2-400f-a31a-61ef7755985c",
"trunk_sid_src": null,
"type": "telecom",
"user_data" : {
"identity" : "eyJ0eXAiOiJwYXNzcG9ydCIsImFsZyI6I...alg=ES256;ppt=shaken"
},
"version": 2
}
Attribute | Data Type | Description |
---|---|---|
cic read only | string | The current Carrier Identification Code (CIC) information. |
cic_original read only | string | The CIC information before any transformations were applied. |
cic_transformed read only | string | The CIC information after any transformations were applied. |
codec_dst read only | string | The codec of the destination leg of the call. May be null if the call did not complete. |
codec_src read only | string | The codec of the source leg of the call. |
date_insert read only | string | The date and time when the detail record was inserted into the database. |
date_start read only | string | The date and time when the call was started. |
date_stop read only | string | The date and time when the call ended. |
date_talk read only | string | The date and time when the destination phone number answered the call. |
direction read only | string | The direction of the call. Values accepted in this field are:
|
disconnect_originator read only | string | The originator of a call drop. |
diversion_dst read only | string | The destination diversion header. |
diversion_src read only | string | The source diversion header. |
dr_sid read only | string | The secure ID of the record. |
duration read only | number | The call duration in seconds. The value is calculated as date_stop – date_start . |
duration_billing read only | number | The calculated call duration in seconds to set the price. |
endpoint_sid_dst read only | string | The destination endpoint secure ID. If the destination is an external phone number, this value will be populated with the System Gateway secure ID. |
endpoint_sid_src read only | string | The source endpoint secure ID. If the source is an external phone number, this value will be populated with the System Gateway secure ID. |
identity read only | string | The real phone number that the call is coming from. This field is populated from either PAI or RPID. |
ip_dst read only | string | The IP address of the destination of call. |
ip_src read only | string | The IP address of the source of call. |
number_billing read only | string | The subscriber phone number. |
number_dst read only | string | The destination phone number. Values accepted in this field are the calling number if the call is outbound , or the called number if the call is inbound . |
number_dst_original read only | string | The destination phone number before any transformations were applied. This field will populate if this value is different from number_dst . |
number_dst_transformed read only | string | The destination phone number after any transformations were applied. This field will populate if this value is different from number_dst . |
number_external read only | string | The non-subscriber phone number. |
number_src read only | string | The source number. Values accepted in this field are the calling number if the call is outbound , or the called number if the call is inbound . |
number_src_original read only | string | The source phone number before any transformations were applied. This field will populate if this value is different from number_src . |
number_src_transformed read only | string | The source phone number after any transformations were applied. This field will populate if this value is different from number_src . |
partner_sid read only | string | The secure ID of the partner associated with the call detail record. |
price read only | number | The price for the detail record. |
price_lcr_dst read only | number | The least-cost routing (LCR) price of the incoming call based on the rate_lcr_dst and duration. |
price_lcr_src read only | number | The least-cost routing (LCR) price of the outgoing call based on the rate_lcr_src and duration. |
rate read only | number | The rate that the system uses to calculate the price of the call. |
rate_lcr_dst read only | number | The least-cost routing (LCR) rate based on the secure ID of the receiving endpoint associated with the call. |
rate_lcr_src read only | number | The least-cost routing (LCR) rate based on the secure ID of the sending endpoint associated with the call. |
sipcallid_dst read only | string | The SIP call ID of the destination call. |
sipcallid_src read only | string | The SIP call ID of the source of call. |
sipcause read only | string | The SIP code that was used to end the call. |
stir_attest read only | string | The attestation level returned by the stir_validate transformation if the system ran it. |
stir_identity read only | boolean | Whether the identity was received in the outbound calls or sent in the inbound calls. |
stir_orig_id read only | string | The ID of the call originator returned by the stir_validate transformation if the system ran it. |
stir_signing_entity read only | string | If the call is signed, this field will display the signing authority which performed the call attestation. |
stir_verstat read only | string | The TN validation result returned by the stir_validate transformation if the system ran it. Is set to null for the calls with the inbound direction. |
transcoded read only | string | Shows whether the call was transcoded or not. The value returned in this field is true if the call was transcoded or false if it was not. |
trunk_group_sid_dst read only | string | The destination trunk group secure ID. |
trunk_group_sid_src read only | string | The source trunk group secure ID. |
trunk_sid_dst read only | string | The destination trunk secure ID. |
trunk_sid_src read only | string | The source trunk secure ID. |
type read only | string | The type of call. Values accepted in this field are:
|
user_data read only | object | The custom user data set by the set_user_data transformation. |
version read only | integer | The version of the detail record as it comes from the resource. |
Get Call Detail Records
GET /calls/call_drs
Returns call detail records matching the criteria in the request URL
curl -X GET \
'https://api.carrierx.com/core/v2/calls/call_drs?before=e4db6148-ed3b-4eb8-83ce-17d71763a359&limit=1' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a list of Call Detail Record objects
{
"count": 1,
"has_more": true,
"items": [
{
"cic": null,
"cic_original": null,
"cic_transformed": null,
"codec_dst": "g722"
"codec_src": "amrwb",
"date_insert": "2019-01-18T15:35:03.000Z",
"date_start": "2019-01-18T15:32:15.589Z",
"date_stop": "2019-01-18T15:32:19.839Z",
"date_talk": "2019-01-18T15:32:16.535Z",
"direction": "inbound",
"disconnect_originator": "DST",
"diversion_dst": "+15162065451",
"diversion_src": "+15162065451",
"dr_sid": "c02a73b2-8401-459a-af7e-f4cc3eee7854",
"duration": "4.25015",
"duration_billing": "60",
"endpoint_sid_dst": "1ce5a6da-7d72-448a-ab81-897fe24b8f02",
"endpoint_sid_src": "7fc3e7ea-a0df-4de1-836f-50318ed66466",
"identity": null,
"ip_dst": "10.222.2.197:5060",
"ip_src": "162.251.180.18",
"number_billing": "15162065451",
"number_dst": "15162065451",
"number_dst_original": null,
"number_dst_transformed": null,
"number_external": "15012678830",
"number_src": "+15012678830",
"number_src_original": null,
"number_src_transformed": null,
"partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
"price": "0.0025",
"price_lcr_dst": "0.0025",
"price_lcr_src": null,
"rate": "0.0025",
"rate_lcr_dst": "0.005",
"rate_lcr_src": null,
"sipcallid_dst": "11b5b29c3486cac52a7d5baa52c937c9@12.7.193.174",
"sipcallid_src": "428ac5df4582bea66501f7d45199a18d@162.251.180.24",
"sipcause": "200",
"stir_attest" : "A",
"stir_identity" : "false",
"stir_orig_id" : "+15012678830",
"stir_signing_entity" : "carrierX",
"stir_verstat": null,
"transcoded": true,
"trunk_group_sid_dst": "cf7db13f-5c63-4c62-a447-fe3008cd72ef",
"trunk_group_sid_src": null,
"trunk_sid_dst": "7098d9f8-c8f2-400f-a31a-61ef7755985c",
"trunk_sid_src": null,
"type": "telecom",
"user_data" : {
"identity" : "eyJ0eXAiOiJwYXNzcG9ydCIsImFsZyI6I...alg=ES256;ppt=shaken"
},
"version": 2
}
],
"limit": 1,
"offset": 0,
"pagination": {
"previous": "https://api.carrierx.com/core/v2/calls/call_drs?before=c02a73b2-8401-459a-af7e-f4cc3eee7854&limit=1&offset=0"
},
"total": null
}
This request returns data about sent and received calls including the date and time, originating and destination phone numbers, and IP addresses of the calling numbers.
GET | /calls/call_drs |
This request is enabled for Pagination (including after
and before
parameters), Result Filtering, and Field Filtering.
Required Scopes
To get information about Call Detail Record objects, the partner must have one of the following scopes enabled:
calls.manage
calls.read
To get information about Call Detail Record objects for the inherited partners, the partner must additionally have the calls.read_descendant
scope enabled.
Get Call Detail Record by SID
GET /calls/call_drs/{dr_sid}
Returns a Call Detail Record, targeted by secure ID
curl -X GET \
'https://api.carrierx.com/core/v2/calls/call_drs/c02a73b2-8401-459a-af7e-f4cc3eee7854' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the Call Detail Record object
{
"cic": null,
"cic_original": null,
"cic_transformed": null,
"codec_dst": "g722"
"codec_src": "amrwb",
"date_insert": "2019-01-18T15:35:03.000Z",
"date_start": "2019-01-18T15:32:15.589Z",
"date_stop": "2019-01-18T15:32:19.839Z",
"date_talk": "2019-01-18T15:32:16.535Z",
"direction": "inbound",
"disconnect_originator": "DST",
"diversion_dst": "+15162065451",
"diversion_src": "+15162065451",
"dr_sid": "c02a73b2-8401-459a-af7e-f4cc3eee7854",
"duration": "4.25015",
"duration_billing": "60",
"endpoint_sid_dst": "1ce5a6da-7d72-448a-ab81-897fe24b8f02",
"endpoint_sid_src": "7fc3e7ea-a0df-4de1-836f-50318ed66466",
"identity": null,
"ip_dst": "10.222.2.197:5060",
"ip_src": "162.251.180.18",
"number_billing": "15162065451",
"number_dst": "15162065451",
"number_dst_original": null,
"number_dst_transformed": null,
"number_external": "15012678830",
"number_src": "+15012678830",
"number_src_original": null,
"number_src_transformed": null,
"partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
"price": "0.0025",
"price_lcr_dst": "0.0025",
"price_lcr_src": null,
"rate": "0.0025",
"rate_lcr_dst": "0.005",
"rate_lcr_src": null,
"sipcallid_dst": "11b5b29c3486cac52a7d5baa52c937c9@12.7.193.174",
"sipcallid_src": "428ac5df4582bea66501f7d45199a18d@162.251.180.24",
"sipcause": "200",
"stir_attest" : "A",
"stir_identity" : "false",
"stir_orig_id" : "+15012678830",
"stir_signing_entity" : "carrierX",
"stir_verstat": null,
"transcoded": true,
"trunk_group_sid_dst": "cf7db13f-5c63-4c62-a447-fe3008cd72ef",
"trunk_group_sid_src": null,
"trunk_sid_dst": "7098d9f8-c8f2-400f-a31a-61ef7755985c",
"trunk_sid_src": null,
"type": "telecom",
"user_data" : {
"identity" : "eyJ0eXAiOiJwYXNzcG9ydCIsImFsZyI6I...alg=ES256;ppt=shaken"
},
"version": 2
}
This request returns data for a call detail record, targeted by secure ID.
GET | /calls/call_drs/{dr_sid} |
This request is enabled for Field Filtering.
Required Scopes
To get information about a Call Detail Record object, the partner must have one of the following scopes enabled:
calls.manage
calls.read
To get information about a Call Detail Record object for the inherited partners, the partner must additionally have the calls.read_descendant
scope enabled.
Path Arguments
Parameter | Data Type | Description |
---|---|---|
dr_sid required | string | The secure ID of the Call Detail Record. |
Rate Object
This section describes the elements of the Rate object. These fields and values make up the JSON object that gets returned with successful requests.
Sample Rate object
{
"active": "yes",
"count": 1,
"effective_date": "2020-08-23T00:00:00.000Z",
"has_more": true,
"items": [
{
"billing_increment": "60",
"billing_minimum": "60",
"country_code": null,
"country_name": null,
"prefix": null,
"price": "0.005"
}
],
"limit": 1,
"offset": 0,
"pagination": null,
"partner_sid": "99953792-bd20-4ed0-a523-8c22788f15v6",
"rates_plan": {
"name": "retail_voice_in_rates-2020-07-05",
"rates_plan_sid": "141e0b1f-ac9b-4347-bd44-cfaef65e6f93"
},
"total": 9
}
Parameter | Data Type | Description |
---|---|---|
active read only | string | Whether or not that rate is effective, as determined by effective_date . |
effective_date read only | string | The date and time when the rate becomes effective. |
items read only | array of objects | The rate details. Refer to the table below for more information. |
partner_sid read only | string | The secure ID of the partner associated with the rate. |
rates_plan read only | object | The rate plan. Refer to the table below for more information. |
Rate Call Object
Parameter | Data Type | Description |
---|---|---|
billing_increment read only | number | The increment in seconds by which billing will occur. Calls are rounded up to the nearest billing_increment . |
billing_minimum read only | number | The minimum length of the call in seconds for billing. |
country_code read only | string | The ISO 3166-1 alpha-3 code of this rate. |
country_name read only | string | The common country name of this rate. |
prefix read only | string | The prefix of this call rate. |
price read only | number | The price of this rate. The price is per billing_minimum . |
Rate Plan Object
Parameter | Data Type | Description |
---|---|---|
name read only | string | The name of the rate plan. |
rates_plan_sid read only | string | The rate plan secure ID. |
Get Inbound PSTN Rates
GET /calls/rates/inbound/pstn
Returns rates for inbound PSTN calls
curl -X GET \
'https://api.carrierx.com/core/v2/calls/rates/inbound/pstn' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a list of Rate objects
{
"active": "yes",
"count": 1,
"effective_date": "2019-08-23T00:00:00.000Z",
"has_more": true,
"items": [
{
"billing_increment": "60",
"billing_minimum": "60",
"country_code": null,
"country_name": null,
"prefix": null,
"price": "0.005"
}
],
"limit": 1,
"offset": 0,
"pagination": null,
"partner_sid": "99953792-bd20-4ed0-a523-8c22788f15v6",
"rates_plan": {
"name": "retail_voice_in_rates-2019-07-05",
"rates_plan_sid": "141e0b1f-ac9b-4347-bd44-cfaef65e6f93"
},
"total": 9
}
This request returns a list of rates for receiving calls from PSTN.
GET | /calls/rates/inbound/pstn |
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Download CSV of Inbound PSTN Rates
GET /calls/rates/inbound/pstn/csv
Returns inbound PSTN rates for a partner in the CSV format
curl -X GET \
'https://api.carrierx.com/core/v2/calls/rates/inbound/pstn/csv' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code and a CSV download
This request returns a CSV with the list of all rates for receiving calls from PSTN.
GET | /calls/rates/inbound/pstn/csv |
This request is enabled for Field Filtering.
Get Inbound VoIP Rates
GET /calls/rates/inbound/voip/{sub_type}
Returns inbound VoIP rates for calls, targeted by the subtype
curl -X GET \
'https://api.carrierx.com/core/v2/calls/rates/inbound/voip/conference' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the Rate object
{
"active": "yes",
"count": 1,
"effective_date": "2018-08-29T00:00:00.000Z",
"has_more": false,
"items": [
{
"billing_increment": "60",
"billing_minimum": "60",
"country_code": null,
"country_name": null,
"prefix": null,
"price": "0"
}
],
"limit": 1000,
"offset": 0,
"pagination": null,
"partner_sid": "99953792-bd20-4ed0-a523-8c22788f15v6",
"rates_plan": {
"name": "voip_conference_in_zero_rate.txt",
"rates_plan_sid": "141e0b1f-ac9b-4347-bd44-cfaef65e6f93"
},
"total": 1
}
This request returns a list of rates for receiving calls from VoIP, targeted by the endpoint type.
GET | /calls/rates/inbound/voip/{sub_type} |
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Path Arguments
Parameter | Data Type | Description |
---|---|---|
sub_type required | string | The rate subtype. Values accepted in this field are:
|
Download CSV of Inbound VoIP Rates
GET /calls/rates/inbound/voip/{sub_type}/csv
Returns inbound VoIP rates for a partner in the CSV format
curl -X GET \
'https://api.carrierx.com/core/v2/calls/rates/inbound/voip/conference/csv' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code and a CSV download
This request returns a CSV with the list of all rates for receiving calls from VoIP, targeted by the endpoint type.
GET | /calls/rates/inbound/voip/{sub_type}/csv |
This request is enabled for Field Filtering.
Path Arguments
Parameter | Data Type | Description |
---|---|---|
sub_type required | string | The rate subtype. Values accepted in this field are:
|
Get Outbound PSTN Rates
GET /calls/rates/outbound/pstn
Returns outbound PSTN rates for calls
curl -X GET \
'https://api.carrierx.com/core/v2/calls/rates/outbound/pstn?limit=1' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the Rate object
{
"active": "yes",
"count": 1,
"effective_date": "2019-08-23T00:00:00.000Z",
"has_more": true,
"items": [
{
"billing_increment": "6",
"billing_minimum": "6",
"country_code": "USA",
"country_name": "United States",
"prefix": "1207991",
"price": "0.01"
}
],
"limit": 1,
"offset": 0,
"pagination": null,
"partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
"rates_plan": {
"name": "retail_voice_out-2019-08-16",
"rates_plan_sid": "0428d20f-7869-4cf5-aa5c-f44f99a19515"
},
"total": 110170
}
This request returns a list of rates for sending calls to PSTN.
GET | /calls/rates/outbound/pstn |
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Download CSV of Outbound PSTN Rates
GET /calls/rates/outbound/pstn/csv
Returns outbound PSTN rates for a partner in the CSV format
curl -X GET \
'https://api.carrierx.com/core/v2/calls/rates/outbound/pstn/csv' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code and a CSV download
This request returns a CSV with the list of all rates for sending calls to PSTN.
GET | /calls/rates/outbound/pstn/csv |
This request is enabled for Field Filtering.
Get Outbound VoIP Rates
GET /calls/rates/outbound/voip/{sub_type}
Returns outbound VoIP rates for calls, targeted by the subtype
curl -X GET \
'https://api.carrierx.com/core/v2/calls/rates/outbound/voip/conference' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the Rate object
{
"active": "yes",
"count": 1,
"effective_date": "2018-08-29T00:00:00.000Z",
"has_more": false,
"items": [
{
"billing_increment": "60",
"billing_minimum": "60",
"country_code": null,
"country_name": null,
"prefix": null,
"price": "0"
}
],
"limit": 1000,
"offset": 0,
"pagination": null,
"partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
"rates_plan": {
"name": "voip_conference_out_zero_rate.txt",
"rates_plan_sid": "0428d20f-7869-4cf5-aa5c-f44f99a19515"
},
"total": 1
}
This request returns a list of rates for sending calls to VoIP, targeted by the endpoint type.
GET | /calls/rates/outbound/voip/{sub_type} |
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Path Arguments
Parameter | Data Type | Description |
---|---|---|
sub_type required | string | The rate subtype. Values accepted in this field are:
|
Download CSV of Outbound VoIP Rates
GET /calls/rates/outbound/voip/{sub_type}/csv
Returns outbound VoIP rates for a partner in the CSV format
curl -X GET \
'https://api.carrierx.com/core/v2/calls/rates/outbound/voip/conference/csv' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code and a CSV download
This request returns a CSV with the list of all rates for sending calls to VoIP, targeted by the endpoint type.
GET | /calls/rates/outbound/voip/{sub_type}/csv |
This request is enabled for Field Filtering.
Path Arguments
Parameter | Data Type | Description |
---|---|---|
sub_type required | string | The rate subtype. Values accepted in this field are:
|
Countries
The Countries API holds data about countries, including universally accepted formats, mobile country codes, dialing prefixes, and more.
Country Object
This section describes the elements of the Country object. These fields and values make up the JSON object that gets returned with successful requests.
Sample Country object
{
"capital": "Washington D.C.",
"common_name": "United States",
"dialing_prefix": "1",
"domain": "us",
"iso_3166_alpha_2": "US",
"iso_3166_alpha_3": "USA",
"iso_3166_numeric": 840,
"mcc": "310,311,312,313,316",
"official_name": "United States of America",
"region": "Americas",
"subregion": "Northern America"
}
Attribute | Data Type | Description |
---|---|---|
capital read only | string | The capital of the country. |
common_name read only | string | The common name of the country. |
dialing_prefix read only | string | The telephone code of the country. |
domain read only | string | The Internet domain of the country. |
iso_3166_alpha_2 read only | string | The ISO 3166-1 alpha-2 code of the country. |
iso_3166_alpha_3 read only | string | The ISO 3166-1 alpha-3 code of the country. |
iso_3166_numeric read only | integer | The ISO 3166-1 numeric code of the country. |
mcc read only | string | The mobile country code. |
official_name read only | string | The official name of the country. |
region read only | string | The region of the country. |
subregion read only | string | The subregion of the country. |
Get Countries
GET /countries
Returns a list of countries
curl -X GET \
'https://api.carrierx.com/core/v2/countries?limit=1' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a list of Country objects
{
"count": 1,
"has_more": true,
"items": [
{
"capital": "Washington D.C.",
"common_name": "United States",
"dialing_prefix": "1",
"domain": "us",
"iso_3166_alpha_2": "US",
"iso_3166_alpha_3": "USA",
"iso_3166_numeric": 840,
"mcc": "310,311,312,313,316",
"official_name": "United States of America",
"region": "Americas",
"subregion": "Northern America"
}
],
"limit": 1,
"offset": 0,
"pagination": {
"next": "https://api.carrierx.com/core/v2/countries?limit=1&offset=1"
},
"total": 249
}
This request returns a list of countries.
GET | /countries |
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Required Scopes
To get information about Country objects, the partner must have one of the following scopes enabled:
countries.manage
countries.read
Get Country by ISO Code
GET /countries/{country_code}
Returns a country, targeted by ISO code
curl -X GET \
'https://api.carrierx.com/core/v2/countries/ITA?exclude_fields=common_name' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the Country object
{
"capital": "Rome",
"dialing_prefix": "39",
"domain": "it",
"iso_3166_alpha_2": "IT",
"iso_3166_alpha_3": "ITA",
"iso_3166_numeric": 380,
"mcc": "222",
"official_name": "Italian Republic",
"region": "Europe",
"subregion": "Southern Europe"
}
This request returns the country associated with an ISO 3166-1 alpha-3 code.
GET | /countries/{country_code} |
This request is enabled for Field Filtering.
Required Scopes
To get information about a Country object, the partner must have one of the following scopes enabled:
countries.manage
countries.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
country_code required | string | The ISO 3166-1 alpha-3 code of the country. |
Get Country by IP Address
GET /countries/ip/{ip_address}
Returns a country, targeted by IP address
curl -X GET \
'https://api.carrierx.com/core/v2/countries/ip/2.6.26.2' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the Country object
{
"city": "Bordeaux",
"common_name": "France",
"iso_3166_alpha_2": "FR",
"region": "Nouvelle-Aquitaine",
"state": null
}
This request returns the country associated with the IP address.
GET | /countries/ip/{ip_address} |
This request is enabled for Field Filtering.
Required Scopes
To get information about a Country object, the partner must have one of the following scopes enabled:
countries.manage
&lookup.ip_addresses.read
countries.read
&lookup.ip_addresses.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
ip_address required | string | The IPv4 address. |
Endpoints
An endpoint represents a device that can receive voice calls. It may be an external SIP device, such as an Asterisk server or SIP PBX, or a hosted application that CarrierX runs.
New partners are provided a system_gateway
endpoint, which cannot be modified. This endpoint is a logical representation of the CarrierX switches, and determines the IP addresses where traffic is sent and received.
In call detail records, a call coming into the PSTN would designate the system_gateway
endpoint as the inbound leg. The endpoint being routed to would be listed as the outbound leg. Alternatively, for inbound calls sent to a third-party endpoint, users will need their switch to accept traffic from any of the IPs listed in the system_gateway
endpoint.
Endpoint Object
This section outlines the Endpoint object. The fields listed in the table below will be returned in a JSON object when a successful request has been made.
Sample Endpoint object
{
"addresses": [],
"attributes": {},
"capacity": 0,
"cps_limit": null,
"endpoint_sid": "358d56f9-1482-4b3d-85a9-efd29afc6ff2",
"name": "my_conf",
"out_sip_password": null,
"out_sip_username": null,
"partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
"properties": {
"account_sid": "6DcA986G-vcBel19O02iIbYUAawVidvB",
"api_url": "https://api.carrierx.com/conference/v1",
"container_sid": "null",
"login": "sample_conference_775",
"password": "YnAa9s8ixJKi"
},
"transformations": [],
"type": "conference",
"voip_token": null
}
Attribute | Data Type | Description |
---|---|---|
addresses create update | array of objects | The endpoint addresses. Refer to the table below for more information. |
attributes create update | object | The endpoint attributes. Refer to the table below for more information. |
capacity create update | integer | The maximum number of simultaneous inbound calls. |
cps_limit read only | integer | The maximum number of outbound calls per second. 0 or null means unlimited. |
endpoint_sid read only | string | The endpoint secure ID. |
name create update | string | The endpoint name. |
out_sip_password create | string | For calls sent to this endpoint and if proxy authentication is required, this password and out_sip_username will be used if no sip_password is set for the Endpoint Address object. |
out_sip_username create | string | For calls sent to this endpoint and if proxy authentication is required, this username and out_sip_password will be used if no sip_username is set for the Endpoint Address object. |
partner read only | object | The Partner object associated with the endpoint. This field is displayed if with_related is set to true when performing the GET queries. |
partner_sid create | string | The secure ID of the partner associated with the endpoint. |
properties create update | object | The endpoint properties. Refer to the table below for more information. |
transformations create update | array of objects | The transformations that apply to the endpoint. Refer to the transformations section for more information. |
type create | string | The type of endpoint. Values accepted in this field are:
|
voip_token read only | string | The endpoint authentication token. |
Endpoint Address Object
Attribute | Data Type | Description |
---|---|---|
direction create update | string | The direction for the address. Values accepted in this field are: inbound , outbound , and any . The default value for this field is any . |
dst_port create update | integer | If specified, this entry is only valid for calls that reach CarrierX on this port. CarrierX listens on port 5060-5069 , and any of these ports may be specified. The default port value is 5060 . |
ip create update | string | The IP address or fully qualified domain name (FQDN) associated with the endpoint. |
location_sid create update | string | The location secure ID. |
port create update | integer | The port. The default port value is 5060 . |
priority create update | integer | The priority of the address. Lower values have higher priority. The default value is 0 . |
sip_password create update | string | For calls sent to this endpoint and if proxy authentication is required, this password and sip_username will be used. This value overrides the out_sip_password value of the Endpoint object. |
sip_username create update | string | For calls sent to this endpoint and if proxy authentication is required, this username and sip_password will be used. This value overrides the out_sip_username value of the Endpoint object. |
srtp create update | boolean | Allows the endpoint to receive and send calls that require the use of secure real-time transport protocol (SRTP). Values accepted in this field are:
false . |
subnet_mask create update | integer | The subnet mask associated with the endpoint. The default value for this field is 32. This value cannot be changed unless the endpoint direction is “outbound”. When set, calls can be accepted from any IP address within the range defined by the IP field and the subnet mask field. For outbound endpoints values within the range between 29 and 32 are allowed. To modify this range, please contact technical support at support@carrierx.com. |
transport create update | string | The protocol for the address. Values accepted in this field are: tcp , tls , and udp . The default value for this field is udp . This field applies to the Third Party endpoint. |
Attributes Object
Attribute | Data Type | Description | Applicable Endpoints |
---|---|---|---|
account_sid create update | string | The account secure ID. | FlexML, Mediator |
api_url create update | string | The URL of the API. | FlexML, Mediator |
did_group_id create update | string | The DID group ID. | Conference, FlexML |
key create update | string | The attribute key. | Any |
subscriber_sid create update | string | The subscriber secure ID. | Conference, FlexML |
value create update | string | The attribute value. | Any |
Properties Object
Attribute | Data Type | Description | Applicable Endpoints |
---|---|---|---|
account_sid read only | string | The account secure ID. | Conference, Conference Playback, FlexML, Mediator, Voicemail |
api_url read only | string | The URL of the API. | Conference, Conference Playback, FlexML, Mediator, Voicemail |
callback_method create update | string | The callback method used with the Voicemail endpoint. Values accepted in this field are POST and GET . The default value is POST . |
Voicemail |
callback_url create update | string | The callback URL used with the Voicemail endpoint. The default value is null . |
Voicemail |
container_sid create update | string | The secure ID of the container where recordings will be stored. The default value is null . |
Conference, FlexML, Voicemail |
conference_endpoint_sid create update | string | The secure ID of the Conference endpoint associated with the Conference Playback endpoint. | Conference Playback |
greeting create update | string | The name of the file used as a greeting for the Voicemail endpoint. The default value is null . |
Voicemail |
login read only | string | The login for the endpoint. | Conference, Conference Playback, FlexML, Mediator, Voicemail |
max_duration create update | number | The maximum length of the recording in seconds used with the Voicemail endpoint. | Voicemail |
password read only | string | The password for the endpoint. | Conference, Conference Playback, FlexML, Mediator, Voicemail |
subscriber_sid read only | string | The subscriber secure ID. | Conference |
Create Endpoint
POST /endpoints
Creates an endpoint
The following request creates 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'
Response
200
status code with a serialized copy of the Endpoint object
{
"addresses": [],
"attributes": {},
"capacity": 0,
"cps_limit": null,
"endpoint_sid": "358d56f9-1482-4b3d-85a9-efd29afc6ff2",
"name": "my_conf",
"out_sip_password": null,
"out_sip_username": null,
"partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
"properties": {
"account_sid": "6DcA986G-vcBel19O02iIbYUAawVidvB",
"api_url": "https://api.carrierx.com/conference/v1",
"container_sid": "null",
"login": "sample_conference_775",
"password": "YnAa9s8ixJKi"
},
"transformations": [],
"type": "conference",
"voip_token": null
}
The following request creates a Third-party endpoint
curl -X POST \
'https://api.carrierx.com/core/v2/endpoints' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"EP_Т_1","addresses": ["ip": "1.1.2.13", "port": "5060"], "type":"third_party"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the Endpoint object
{
"addresses": [
{
"direction": "any",
"dst_port": 5060,
"ip": "1.1.2.13",
"location_sid": null,
"port": 5060,
"priority": 0,
"sip_password": null,
"sip_username": null,
"srtp": false,
"transport": "udp"
}
],
"attributes": {},
"capacity": 0,
"cps_limit": null,
"endpoint_sid": "473d1623-c615-4b43-ab4f-01cd5491c56b",
"name": "my_third_party",
"out_sip_password": null,
"out_sip_username": null,
"partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
"properties": {},
"transformations": [],
"type": "third_party",
"voip_token": "0cac0ffe-fed4-4ee3-8212-e50659e28088"
}
This request creates an endpoint.
POST | /endpoints |
For the Mediator, Conference, Conference Playback, and FlexML endpoints, only the name
and capacity
values can be edited after the endpoint has been created. For the Voicemail endpoint, the properties
attributes can be also modified.
Required Scopes
To create an Endpoint object, the partner must have one of the following scopes enabled:
endpoints.manage
endpoints.create
Body Arguments
JSON representation of the fields and values of the Endpoint object to be created.
A required field to create an endpoint is type
, for the third-party endpoint the required fields are ip
and type
. If no value for port
is specified, the value for port
will be assigned as 5060
.
Refer to this table to view all fields that appear in the Endpoint object.
Get Endpoints
GET /endpoints
Returns endpoints matching the criteria in the request URL
curl -X GET \
'https://api.carrierx.com/core/v2/endpoints?filter=addresses.ip+eq+"1.1.2.13"' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a list of Endpoint objects
{
"count": 1,
"has_more": false,
"items": [
{
"addresses": [
{
"direction": "any",
"dst_port": 5060,
"ip": "1.1.2.13",
"location_sid": null,
"port": 5060,
"priority": 0,
"sip_password": null,
"sip_username": null,
"srtp": false,
"transport": "udp"
}
],
"attributes": {},
"capacity": 0,
"cps_limit": null,
"endpoint_sid": "473d1623-c615-4b43-ab4f-01cd5491c56b",
"name": "my_third_party",
"out_sip_password": null,
"out_sip_username": null,
"partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
"properties": {},
"transformations": [],
"type": "third_party",
"voip_token": "0cac0ffe-fed4-4ee3-8212-e50659e28088"
}
],
"limit": 1000,
"offset": 0,
"pagination": {},
"total": 1
}
This request returns a list of endpoints.
GET | /endpoints |
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Required Scopes
To get information about Endpoint objects, the partner must have one of the following scopes enabled:
endpoints.manage
endpoints.read
Query Arguments
Parameter | Data Type | Description |
---|---|---|
with_related | boolean | Determines if the partner information related to the endpoint should be shown. Values accepted in this field are true and false . The default value is false . |
Get Endpoint by SID
GET /endpoints/{endpoint_sid}
Returns an endpoint, targeted by secure ID
curl -X GET \
'https://api.carrierx.com/core/v2/endpoints/473d1623-c615-4b43-ab4f-01cd5491c56b' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the Endpoint object
{
"addresses": [
{
"direction": "any",
"dst_port": 5060,
"ip": "1.1.2.13",
"location_sid": null,
"port": 5060,
"priority": 0,
"sip_password": null,
"sip_username": null,
"srtp": false,
"transport": "udp"
}
],
"attributes": {},
"capacity": 0,
"cps_limit": null,
"endpoint_sid": "473d1623-c615-4b43-ab4f-01cd5491c56b",
"name": "my_third_party",
"out_sip_password": null,
"out_sip_username": null,
"partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
"properties": {},
"transformations": [],
"type": "third_party",
"voip_token": "0cac0ffe-fed4-4ee3-8212-e50659e28088"
}
This request returns data for an endpoint, targeted by secure ID.
GET | /endpoints/{endpoint_sid} |
This request is enabled for Field Filtering.
Required Scopes
To get information about an Endpoint object, the partner must have one of the following scopes enabled:
endpoints.manage
endpoints.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
endpoint_sid required | string | The endpoint secure ID. |
Query Arguments
Parameter | Data Type | Description |
---|---|---|
with_related | boolean | Determines if the partner information related to the endpoint should be shown. Values accepted in this field are true and false . The default value is false . |
Update Endpoint
PATCH /endpoints/{endpoint_sid}
Updates the Endpoint object, targeted by secure ID, with the values in the request body
curl -X PATCH \
'https://api.carrierx.com/core/v2/endpoints/00bf8b25-1e20-4f80-8529-8448df32d71a' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"my_third_party_ep"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the updated Endpoint object
{
"addresses": [
{
"direction": "any",
"dst_port": 5060,
"ip": "1.1.2.13",
"location_sid": null,
"port": 5060,
"priority": 0,
"sip_password": null,
"sip_username": null,
"srtp": false,
"transport": "udp"
}
],
"attributes": {},
"capacity": 0,
"cps_limit": null,
"endpoint_sid": "1a34c5e9-3a09-4de5-b553-5f6a9ef202ac",
"name": "my_third_party_ep",
"out_sip_password": null,
"out_sip_username": null,
"partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
"properties": {},
"transformations": [],
"type": "third_party",
"voip_token": "2c95517b-a5e8-4415-b471-cdd81d5a6dcb"
}
This request updates an endpoint, targeted by secure ID.
PATCH | /endpoints/{endpoint_sid} |
PUT | /endpoints/{endpoint_sid} |
An Endpoint object can be updated using either a PATCH
or PUT
request.
-
A
PATCH
request can be used to update one or more attribute values. When using aPATCH
request, only the attributes specified in the request payload will be updated, all other attributes and values will remain the same. The endpoint secure ID is passed in the query URL, and the values to be modified are passed in the request body.The Endpoint object also contains nested Addresses, Attributes, Properties, and Transformations objects. Refer to this section to learn how nested objects can be updated using the
PATCH
request. -
A
PUT
request can be used to update an entire Endpoint object. The endpoint secure ID is passed in the query URL, and the entire Endpoint object is passed in the request body.
Required Scopes
To update an Endpoint object, the partner must have one of the following scopes enabled:
endpoints.manage
endpoints.update
Path Arguments
Parameter | Data Type | Description |
---|---|---|
endpoint_sid required | string | The endpoint secure ID. |
Query Arguments
Parameter | Data Type | Description |
---|---|---|
nested_objects | string | Determines if the nested objects fields and values should be replaced. Value accepted in this field is replace . |
Body Arguments
JSON representation of the fields and values to be updated.
Refer to this table to view all fields that appear in the Endpoint object.
Delete Endpoint
DELETE /endpoints/{endpoint_sid}
Deletes an endpoint, targeted by secure ID
curl -X DELETE \
'https://api.carrierx.com/core/v2/endpoints/1a34c5e9-3a09-4de5-b553-5f6a9ef202ac' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
204
status code with an empty body
This request deletes an endpoint, targeted by secure ID, from a partner account.
DELETE | /endpoints/{endpoint_sid} |
Required Scopes
To delete an Endpoint object, the partner must have one of the following scopes enabled:
endpoints.manage
endpoints.delete
Path Arguments
Parameter | Data Type | Description |
---|---|---|
endpoint_sid required | string | The secure ID of the endpoint to be removed. |
Lookup
The Lookup API returns data regarding phone numbers and IP addresses.
Phonenumber Lookup Object
Sample Phonenumber Lookup object
{
"country_code": "USA",
"details": {
"carrier": {
"mcc": null,
"mnc": null,
"name": null,
"type": null
},
"cnam": {
"name": "",
"type": null
},
"lrn": "6466531111"
},
"e164_format": "+15162065319",
"in_country_format": "(516) 206-5319",
"international_format": "+1 516-206-5319",
"phonenumber": "15162065319",
"state": "NY"
}
This section outlines the Phonenumber Lookup object. The fields listed in the table below will be returned in a JSON object when a successful request has been made.
Attribute | Data Type | Description |
---|---|---|
country_code read only | string | The ISO 3166-1 alpha-3 code of the country. |
details read only | object | The detail object contains cnam , lrn , and carrier data. Refer to the table below for more information. |
e164_format read only | string | The DID in the E.164 format. |
in_country_format read only | string | The DID in a national format. |
international_format read only | string | The DID in an international format. |
phonenumber read only | string | The phone number. |
state read only | string | Geographic area codes of this DID (for the US DIDs only). |
Phonenumber Lookup Detail Object
Attribute | Data Type | Description |
---|---|---|
carrier read only | object | The carrier information for the phone number. Refer to the carrier table for more information. |
cnam read only | object | The cnam information for the phone number. Refer to the cnam table for more information. |
lrn read only | string | The location routing number. |
Phonenumber Lookup Detail Carrier Object
Attribute | Data Type | Description |
---|---|---|
mcc read only | integer | The mobile country code. |
mnc read only | integer | The mobile network code. |
name read only | string | The carrier name. |
type read only | string | The type of the DID. Values accepted in this field are: landline , mobile , and unknown . |
Phonenumber Lookup Detail Cnam Object
Attribute | Data Type | Description |
---|---|---|
name read only | string | The caller name. |
type read only | string | The caller type. |
Get Details for Phone Number
GET /lookup/dids/{phonenumber}
Returns the phone number details.
curl -X GET \
'https://api.carrierx.com/core/v2/lookup/dids/14353035210?cnam=true&lrn=true&carrier=true&hlr=true' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with the phone number details
{
"country_code": "USA",
"details": {
"carrier": {
"mcc": "312",
"mnc": "850",
"name": "INTELIQUENT",
"type": "mobile"
}
"cnam": null,
"lrn": null
}
"e164_format": "+14353035210",
"in_country_format": "(435) 303-5210",
"international_format": "+1 435-303-5210",
"phonenumber": "14353035210",
"state": "UT"
}
This request returns data for the specified phone number.
GET | /lookup/dids/{phonenumber} |
This request is enabled for Field Filtering.
Required Scopes
To query information for phone numbers the partner must have the following scopes enabled:
lookup.dids.read
to send requests and lookup general information about phone numbers,lookup.dids.allow_carrier
to query detailed information about the carrier (using thecarrier
query argument set totrue
),lookup.dids.allow_cnam
to query detailed information about the CNAM (using thecnam
query argument set totrue
),lookup.dids.allow_lrn
to query information about the location routing number (using thelrn
query argument set totrue
).
Path Arguments
Parameter | Data Type | Description |
---|---|---|
phonenumber required | string | The phone number to look up. |
Query Arguments
Parameter | Data Type | Description |
---|---|---|
carrier | boolean | Determines if the carrier information should be shown. Values accepted in this field are true and false . |
cnam | boolean | Determines if the CNAM information should be shown. Values accepted in this field are true and false . |
cnam_ttl | integer | Overrides the default CNAM cache TTL. |
country_code | string | The ISO 3166-1 alpha-3 code of the country for this phone number. |
guess | string | Optional recommendation whether this number is domestic or not. Values accepted in this field are:
e164 . |
hlr | boolean | Determines if the carrier will be looked up in the Home Location Registry. Values accepted in this field are true and false . The default value is true . |
lrn | boolean | Determines if the location routing number should be shown. Values accepted in this field are true and false . |
Phone Number Lookup Logic
CarrierX performs the phone number lookup based on the following logic:
- If the queried number is prefixed with
+
, the system will check for a full E.164 match only.- If there is a match, the system will return this match.
- Otherwise, it will return the
400
status code.
- When the
country_code
query parameter is passed, the system checks if the number passed could be valid in the country specified in the request (either the in-country format or by international prefix).- If the number is valid against the specified country, the system returns this value immediately, no further checks are made.
- If no
country_code
query parameter was passed or if the match did not succeed, the system will check if it is both a valid domestic number or if it is a valid E.164 number (the prefix matches a valid country code).- If the number is only a valid domestic number or only a valid E.164 number, this match is returned.
- Otherwise, the system will make a guess. The
guess
query parameter parameter helps choose between the domestic (in_country
) match and the E.164 match. The default value ofe164
will prefer the E.164 number.
If the number could not be matched with any available valid phone numbers, the system will return the 400
error status code. If the number format is invalid, the system will return the 404
error status code.
Using Home Location Registry for Carrier Lookup
The Home Location Registry (HLR) is an external paid database containing data regarding carriers and subscribers. You can set the hlr
query argument of your phone number lookup request to true
and the system will make an API call to the HLR. The returned results in this case will most likely be more accurate than the results returned without using this flag. Please note that for using this option you will be charged extra.
On the other hand, if the hlr
query argument is set to false
, the carrier will be determined without the HLR lookup. Only static databases will be used. In this case the mcc
and mnc
fields can be returned as null
in the reply if the phone number is other than a mobile phone number.
IP2Location Object
Sample IP2Location object
{
"city": "Mountain View",
"common_name": "United States",
"iso_3166_alpha_2": "US",
"iso_3166_alpha_3": "USA",
"region": null,
"state": "CA"
}
This section outlines the IP2Location object. The fields listed in the table below will be returned in a JSON object when a successful request has been made.
Attribute | Data Type | Description |
---|---|---|
city read only | string | The IP address city. |
common_name read only | string | The common name of the country the IP address belongs to. |
iso_3166_alpha_2 read only | string | The ISO 3166-1 alpha-2 two-letter code of the country. |
iso_3166_alpha_3 read only | string | The ISO 3166-1 alpha-3 three-letter code of the country. |
region read only | string | The IP address region. |
state read only | string | The IP address state. |
Get Details for IP Address
GET /lookup/lookup/ip_addresses/{ip_address}
Returns the IP address details
curl -X GET \
'https://api.carrierx.com/core/v2/lookup/ip_addresses/8.8.8.8' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with the IP address details
{
"city": "Mountain View",
"common_name": "United States",
"iso_3166_alpha_2": "US",
"iso_3166_alpha_3": "USA",
"region": null,
"state": "CA"
}
This request returns data for the specified IP address.
GET | /lookup/lookup/ip_addresses/{ip_address} |
This request is enabled for Field Filtering.
Required Scopes
To query information for IP addresses the partner must have the following scope enabled:
lookup.ip_addresses.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
ip_address required | string | The IP address to look up. |
CIC Lookup Object
Sample CIC Lookup object
{
"cic": "5102",
"resporg": "TZN99"
}
This section outlines the CIC (Carrier Identification Code) Lookup object for outbound calls to toll-free phone numbers. The fields listed in the table below will be returned in a JSON object when a successful request has been made.
Attribute | Data Type | Description |
---|---|---|
cic read only | string | The Carrier Identification Code used to route and bill calls in the PSTN. |
resporg read only | string | The identifier of a company that owns and manages the toll-free phone number. |
Get CIC Details for Toll-free Phone Number
GET /lookup/toll_free/{tollfree_phonenumber}/{calling_number}/{lata}
Returns a CIC and (optionally) a RespOrg ID for a specific toll-free phone number.
curl -X GET \
'https://api.carrierx.com/core/v2/lookup/toll_free/18002446227/12092551162/490?cic=true&resporg=true' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with the CIC and (optionally) RespOrg details.
{
"cic": "5102",
"resporg": "TZN99"
}
This request returns CIC data and (optionally) a RespOrg ID for the specified toll-free phone number.
GET | /lookup/toll_free/{tollfree_phonenumber}/{calling_number}/{lata} |
This request is enabled for Field Filtering.
Required Scopes
To query the CIC information the partner must have the following scope enabled:
lookup.toll_free.allow_cic
to query a CIC (using thecic
query argument set totrue
).
To query the RespOrg information (provided as an option in the scope of the CIC Lookup Object) the partner must have the following scope enabled:
lookup.toll_free.allow_resporg
to query a RespOrg’s ID (using theresporg
query argument set totrue
).
Path Arguments
Parameter | Data Type | Description |
---|---|---|
tollfree_phonenumber required | string | The toll-free phone number to look up a CIC for. |
calling_number required | string | The phone number that is placing the call to the toll-free number. |
lata required | string | LATA: Local Access and Transport Area, a geographic code representing the location of the call origination. |
Query Arguments
Parameter | Data Type | Description |
---|---|---|
cic | boolean | Determines whether the CIC information should be looked up and shown in the response. Values accepted in this field are true and false. The default value is true. Returns null if set to false. |
cic_ttl | integer | Overrides the default CIC cache TTL (in seconds). |
resporg | boolean | Determines whether the RespOrg information should be looked up and shown in the response. Values accepted in this field are true and false. The default value is false. Returns null if set to false. |
resporg_ttl | integer | Overrides the default RespOrg cache TTL (in seconds). |
RespOrg Lookup Object
Sample RespOrg Lookup object
{
"cic": null,
"resporg": "TZN99"
}
This section outlines the RespOrg (Responsible Organization) Lookup object for a toll-free phone number. The fields listed in the table below will be returned in a JSON object when a successful request has been made.
Attribute | Data Type | Description |
---|---|---|
cic read only | string | Always returns null. |
resporg read only | string | The identifier of a company that owns and manages the toll-free phone number. |
Get RespOrg Details for Toll-free Phone Number
GET /lookup/toll_free/{tollfree_phonenumber}
Returns a RespOrg ID for a specific toll-free phone number.
curl -X GET \
'https://api.carrierx.com/core/v2/lookup/toll_free/8002446227?resporg=true' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with the RespOrg details.
{
"cic": null,
"resporg": "TZN99"
}
This request returns RespOrg ID data for a specified toll-free phone number.
GET | /lookup/toll_free/{tollfree_phonenumber} |
This request is enabled for Field Filtering.
Required Scopes
To query the RespOrg information the partner must have the following scope enabled:
lookup.toll_free.allow_resporg
to query a RespOrg’s ID (using theresporg
query argument set totrue
).
Path Arguments
Parameter | Data Type | Description |
---|---|---|
tollfree_phonenumber required | string | The toll-free phone number to look up a RespOrg’s ID for. |
Query Arguments
Parameter | Data Type | Description |
---|---|---|
resporg | boolean | Determines if the RespOrg information should be shown in the response. Values accepted in this field are true and false . The default value is true . Returns null if set to false . |
resporg_ttl | integer | Overrides the default RespOrg cache TTL (in seconds). |
OAuth
OAuth tokens are used in API requests and allow to manage all other Core API objects for which the partner has the appropriate scopes set.
OAuth tokens with the token_type
set to bearer
are passed in request headers (e.g., -H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
) and are used as credentials for the authentication with the API.
The partners with appropriate scopes can generate OAuth tokens both for themselves and for sub-partners, targeting the sub-partners by their secure IDs.
OAuth Token Object
This section outlines the OAuth Token object. The fields listed in the table below will be returned in a JSON object when a successful request has been made.
Sample OAuth Token object
{
"access_token": "8bfd6c6d-6291-488a-bed1-8784c195ce87",
"client_id": "5c7965f285344165b003ce1a3202e589",
"date_created": "2020-09-11T13:46:42.211Z",
"date_expiration_access_token": "2120-08-18T13:46:42.169Z",
"date_expiration_refresh_token": "2120-08-18T13:46:42.169Z",
"date_last_accessed": null,
"ip_last_accessed": null,
"name": "test_token",
"partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
"refresh_token": "ed07dcd6-dfc5-4d7b-b7b4-891441371b3e",
"scopes": [
"accesscontrol.manage",
"endpoints.manage",
"oauth.manage",
"partners.manage",
"phonenumber.manage",
"push.manage",
"shortener.manage",
"sms.manage",
"storage.manage",
"trunk_groups.manage",
"trunk_groups.trunks.manage"
],
"token_sid": "b3f45e4d-7d46-467b-9724-272f57ac420e",
"token_type": "bearer"
}
Attribute | Data Type | Description |
---|---|---|
access_token read only | string | The access token value to be used in authentication. |
client_id read only | string | The client ID. This is a unique string representing the registration information provided to the client upon request. |
client_secret read only | string | The client secret string. This is a unique string representing the registration information provided to the client upon request. This field is hidden and not returned in the response. |
date_created read only | string | The date and time when the token was created. |
date_expiration_access_token create update | string | The date and time when the token expires. |
date_expiration_refresh_token create update | string | The date and time when the refresh token expires. |
date_last_accessed read only | string | The date and time when the token was last accessed. |
ip_last_accessed read only | string | The IP address from which the token was last accessed. |
name create update | string | The friendly name used to identify the token. |
partner read only | object | The Partner object associated with the OAuth token. This field is displayed if with_related is set to true when performing the GET queries. |
partner_sid read only | string | The secure ID of the partner associated with the OAuth token. |
refresh_token read only | string | The refresh token value to create a new token. |
scopes create update | string | The scope of the access request available for this specific token. Any values in scopes must exist in available_scopes on the Partner object. Refer to the available_scopes table for a comprehensive list of scopes that can be assigned to a partner. If this field is not specified when creating an OAuth Token object, all available_scopes from the Partner object are added. |
token_sid read only | string | The token secure ID. |
token_type read only | string | The token type. |
Generate OAuth Bearer Token
POST /oauth/token
Generates an OAuth bearer token for a partner
curl -X POST \
'https://api.carrierx.com/core/v2/oauth/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-binary 'grant_type=password&client_id=5c7965f285344165b003ce1a3202e589&client_secret=5033909114fe442cbbcb83b674dbf90c&username=carrierx_partner&password=qwerty123' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the OAuth Token object
{
"access_token": "8bfd6c6d-6291-488a-bed1-8784c195ce87",
"client_id": "5c7965f285344165b003ce1a3202e589",
"date_created": "2020-09-11T13:46:42.211Z",
"date_expiration_access_token": "2120-08-18T13:46:42.169Z",
"date_expiration_refresh_token": "2120-08-18T13:46:42.169Z",
"date_last_accessed": null,
"ip_last_accessed": null,
"name": "test_token",
"partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
"refresh_token": "ed07dcd6-dfc5-4d7b-b7b4-891441371b3e",
"scopes": [
"accesscontrol.manage",
"endpoints.manage",
"oauth.manage",
"partners.manage",
"phonenumber.manage",
"push.manage",
"shortener.manage",
"sms.manage",
"storage.manage",
"trunk_groups.manage",
"trunk_groups.trunks.manage"
],
"token_sid": "b3f45e4d-7d46-467b-9724-272f57ac420e",
"token_type": "bearer"
}
This request generates a token for the partner upon request.
POST | /oauth/token |
Required Scopes
To generate an OAuth token the partner must have one of the following scopes enabled:
oauth.manage_all_tokens
oauth.manage
oauth.create
Body Arguments
Parameter | Data Type | Description |
---|---|---|
access_token_expires_in | integer | The access token expiration in seconds. |
client_id required | string | The client ID. This is a unique string representing the registration information provided to the client upon request. |
client_secret required | string | The client secret string. This is a unique string representing the registration information provided to the client upon request. |
grant_type required | string | The grant type for the token. Values accepted in this field are:
|
name | string | The friendly name used to identify the token. |
password required* | string | The password of the partner (used with grant_type = password ). |
refresh_token required** | string | The refresh token (used with grant_type = refresh_token ). |
refresh_token_expires_in | integer | The refresh token expiration in seconds. |
refresh_token_type | string | The type of request (used with grant_type = refresh_token ). Values accepted in this field are:
access_token . |
scope | string | The list of comma-separated partner scopes available for the generated token. |
username required* | string | The login of the partner (used with grant_type = password ). |
*These fields are required if the grant_type
attribute is set to password
.
**This field is required if the grant_type
attribute is set to refresh_token
.
Generate OAuth Bearer Token for Sub-partner
POST /oauth/token/{partner_sid}
Generates an OAuth bearer token for a sub-partner
curl -X POST \
'https://api.carrierx.com/core/v2/oauth/token/cee93bf3-5746-43fe-a1a2-822c05fef687' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-binary 'client_id=5c7965f285344165b003ce1a3202e589&client_secret=5033909114fe442cbbcb83b674dbf90c' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the OAuth Token object
{
"access_token": "8bfd6c6d-6291-488a-bed1-8784c195ce87",
"client_id": "5c7965f285344165b003ce1a3202e589",
"date_created": "2020-09-11T13:46:42.211Z",
"date_expiration_access_token": "2120-08-18T13:46:42.169Z",
"date_expiration_refresh_token": "2120-08-18T13:46:42.169Z",
"date_last_accessed": null,
"ip_last_accessed": null,
"name": "test_token",
"partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
"refresh_token": "ed07dcd6-dfc5-4d7b-b7b4-891441371b3e",
"scopes": [
"accesscontrol.manage",
"endpoints.manage",
"oauth.manage",
"partners.manage",
"phonenumber.manage",
"push.manage",
"shortener.manage",
"sms.manage",
"storage.manage",
"trunk_groups.manage",
"trunk_groups.trunks.manage"
],
"token_sid": "b3f45e4d-7d46-467b-9724-272f57ac420e",
"token_type": "bearer"
}
This request generates a token for a sub-partner, targeted by secure ID.
POST | /oauth/token/{partner_sid} |
Required Scopes
To generate an OAuth token for a sub-partner the partner must have one of the following scopes enabled:
oauth.manage_all_tokens
oauth.manage
oauth.create
Path Arguments
Parameter | Data Type | Description |
---|---|---|
partner_sid required | string | The sub-partner secure ID. |
Body Arguments
Parameter | Data Type | Description |
---|---|---|
access_token_expires_in | integer | The access token expiration in seconds. |
client_id required | string | The client ID. This is a unique string representing the registration information provided to the client upon request. |
client_secret required | string | The client secret string. This is a unique string representing the registration information provided to the client upon request. |
name | string | The friendly name used to identify the token. |
refresh_token_expires_in | integer | The refresh token expiration in seconds. |
scope | string | The list of comma-separated partner scopes available for the generated token. |
Revoke OAuth Token
POST /oauth/revoke
Terminates an OAuth token, targeted by the partner client ID and client secret
curl -X POST \
'https://api.carrierx.com/core/v2/oauth/revoke' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-binary 'client_id=5c7965f285344165b003ce1a3202e589&client_secret=5033909114fe442cbbcb83b674dbf90c' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
204
status code with an empty body
This request terminates the session of the partner targeted by cient ID and client secret.
POST | /oauth/revoke |
Required Scopes
To revoke an OAuth token the partner must have one of the following scopes enabled:
oauth.manage_all_tokens
oauth.manage
Body Arguments
Parameter | Data Type | Description |
---|---|---|
token | string | The access token that will be revoked. If no token is specified, the token that is used for the authorization in the current request will be revoked. |
client_id required | string | The client ID. This is a unique string representing the registration information provided to the client upon request. |
client_secret required | string | The client secret string. This is a unique string representing the registration information provided to the client upon request. |
token_type | string | The token type. |
Get All Active OAuth Tokens
GET /oauth/tokens
Returns all active tokens for the logged-in partner
curl -X GET \
'https://api.carrierx.com/core/v2/oauth/tokens' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with token data
{
"count": 1,
"has_more": false,
"items": [
{
"access_token": "8bfd6c6d-6291-488a-bed1-8784c195ce87",
"client_id": "5c7965f285344165b003ce1a3202e589",
"date_created": "2020-09-11T13:46:42.211Z",
"date_expiration_access_token": "2120-08-18T13:46:42.169Z",
"date_expiration_refresh_token": "2120-08-18T13:46:42.169Z",
"date_last_accessed": null,
"ip_last_accessed": null,
"name": "test_token",
"partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
"refresh_token": "ed07dcd6-dfc5-4d7b-b7b4-891441371b3e",
"scopes": [
"accesscontrol.manage",
"endpoints.manage",
"oauth.manage",
"partners.manage",
"phonenumber.manage",
"push.manage",
"shortener.manage",
"sms.manage",
"storage.manage",
"trunk_groups.manage",
"trunk_groups.trunks.manage"
],
"token_sid": "b3f45e4d-7d46-467b-9724-272f57ac420e",
"token_type": "bearer"
}
],
"limit": 10,
"offset": 0,
"pagination": {},
"total": null
}
This request returns the tokens of the logged-in partner.
GET | /oauth/tokens |
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Required Scopes
To get information about OAuth tokens the partner must have one of the following scopes enabled:
oauth.manage_all_tokens
oauth.manage
oauth.read
Query Arguments
Parameter | Data Type | Description |
---|---|---|
with_related | boolean | Determines if the partner information related to the OAuth token should be shown. Values accepted in this field are true and false . The default value is false . |
Get OAuth Token by SID
GET /oauth/tokens/{token_sid}
Returns an OAuth token, targeted by secure ID
curl -X GET \
'https://api.carrierx.com/core/v2/oauth/tokens/b3f45e4d-7d46-467b-9724-272f57ac420e' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the OAuth Token object
{
"access_token": "8bfd6c6d-6291-488a-bed1-8784c195ce87",
"client_id": "5c7965f285344165b003ce1a3202e589",
"date_created": "2020-09-11T13:46:42.211Z",
"date_expiration_access_token": "2120-08-18T13:46:42.169Z",
"date_expiration_refresh_token": "2120-08-18T13:46:42.169Z",
"date_last_accessed": null,
"ip_last_accessed": null,
"name": "test_token",
"partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
"refresh_token": "ed07dcd6-dfc5-4d7b-b7b4-891441371b3e",
"scopes": [
"accesscontrol.manage",
"endpoints.manage",
"oauth.manage",
"partners.manage",
"phonenumber.manage",
"push.manage",
"shortener.manage",
"sms.manage",
"storage.manage",
"trunk_groups.manage",
"trunk_groups.trunks.manage"
],
"token_sid": "b3f45e4d-7d46-467b-9724-272f57ac420e",
"token_type": "bearer"
}
This request returns data for an OAuth token, targeted by secure ID.
GET | /oauth/tokens/{token_sid} |
This request is enabled for Field Filtering.
Required Scopes
To get information about an OAuth token the partner must have one of the following scopes enabled:
oauth.manage_all_tokens
oauth.manage
oauth.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
token_sid required | string | The OAuth token secure ID. |
Query Arguments
Parameter | Data Type | Description |
---|---|---|
with_related | boolean | Determines if the partner information related to the OAuth token should be shown. Values accepted in this field are true and false . The default value is false . |
Update OAuth Token
PATCH /oauth/tokens/{token_sid}
Updates the OAuth Token object, targeted by secure ID, with the values in the request body
curl -X PATCH \
'https://api.carrierx.com/core/v2/oauth/tokens/b3f45e4d-7d46-467b-9724-272f57ac420e' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"new_test_token"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the updated OAuth Token object
{
"access_token": "8bfd6c6d-6291-488a-bed1-8784c195ce87",
"client_id": "5c7965f285344165b003ce1a3202e589",
"date_created": "2020-09-11T13:46:42.211Z",
"date_expiration_access_token": "2120-08-18T13:46:42.169Z",
"date_expiration_refresh_token": "2120-08-18T13:46:42.169Z",
"date_last_accessed": null,
"ip_last_accessed": null,
"name": "new_test_token",
"partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
"refresh_token": "ed07dcd6-dfc5-4d7b-b7b4-891441371b3e",
"scopes": [
"accesscontrol.manage",
"endpoints.manage",
"oauth.manage",
"partners.manage",
"phonenumber.manage",
"push.manage",
"shortener.manage",
"sms.manage",
"storage.manage",
"trunk_groups.manage",
"trunk_groups.trunks.manage"
],
"token_sid": "b3f45e4d-7d46-467b-9724-272f57ac420e",
"token_type": "bearer"
}
This request updates an OAuth token, targeted by secure ID.
PATCH | /oauth/tokens/{token_sid} |
PUT | /oauth/tokens/{token_sid} |
An OAuth Token object can be updated using either a PATCH
or PUT
request.
-
A
PATCH
request can be used to update one or more attribute values. When using aPATCH
request, only the attributes specified in the request payload will be updated, all other attributes and values will remain the same. The OAuth token secure ID is passed in the query URL, and the values to be modified are passed in the request body. -
A
PUT
request can be used to update an entire OAuth Token object. The OAuth token secure ID is passed in the query URL, and the entire OAuth Token object is passed in the request body.
Required Scopes
To update an OAuth Token object, the partner must have one of the following scopes enabled:
oauth.manage_all_tokens
oauth.manage
oauth.update
To update an OAuth Token object scope
parameter, the partner must additionally have the oauth.allow_token_scope_update
scope enabled.
Path Arguments
Parameter | Data Type | Description |
---|---|---|
token_sid required | string | The OAuth token secure ID. |
Body Arguments
JSON representation of the fields and values to be updated.
Fields that can be modified are:
date_expiration_access_token
date_expiration_refresh_token
name
scopes
Refer to this table to view all fields that appear in the OAuth Token object.
Get Current Partner
GET /oauth/whoami
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'
Response
200
status code with data about the currently logged-in partner
{
"acls": [],
"address1": null,
"address2": null,
"attributes": {},
"available_scopes" : [
"accesscontrol.manage",
"endpoints.manage",
"oauth.manage",
"partners.manage",
"phonenumber.manage",
"push.manage",
"shortener.manage",
"sms.manage",
"storage.manage",
"trunk_groups.manage",
"trunk_groups.trunks.manage"
],
"balance": "351.53",
"billing_email": "jsmith@freeconferencecall.com",
"callbacks": {},
"charge_at": "20",
"city": null,
"company_name": "CarrierX",
"country_code": "USA",
"date_created": "2018-09-20T21:34:55.000Z",
"display_id": "CX90576809",
"login": "johnsmith",
"name": "John Smith",
"owner_email": "jsmith@freeconferencecall.com",
"parent_assigned_acls": [],
"parent_sid": "ac38746e-d2e2-4cd6-29ae-b6658f0728b6",
"partner_sid": "ed437907-002d-4ecc-aa3a-efdf5e50dba0",
"payment_type": "prepay",
"phonenumber": "5162065319",
"prepay_amount": "100",
"spending_limit": "0",
"state": null,
"status": "active",
"tech_email": "jsmith@freeconferencecall.com",
"transformations": [],
"zip": "90804"
}
This request returns the currently logged-in partner.
GET | /oauth/whoami |
Refer to the Partner Object for a full list of the fields that appear in the Partner object.
Partner Login Object
This section outlines the Partner Login object. The fields listed in the table below will be returned in a JSON object when a successful request has been made.
Sample Partner Login object
{
"login": "carrierx_partner",
"login_sid": "abcf6b1f-7281-4da9-a4d6-3fb53e3a76de",
"partner_sid": "edebf627-ebce-4f77-8160-75db76154168",
"token_scopes": [
"partners.read",
"partners.update"
]
}
Attribute | Data Type | Description |
---|---|---|
login create | string | The partner additional login (sub-login) to the system. |
login_sid read only | string | The partner login secure ID. |
partner_sid read only | string | The secure ID of the partner associated with the partner sub-login. |
password create update | string | The partner password for the partner sub-login to the system. This field is required to create a Partner Login object, but is hidden in the serialized copy of the Partner Login objects received in responses to the requests for the security reasons. |
token_scopes create update | array | The list of scopes that will be applied to the tokens created with this partner sub-login. |
Create Partner Login
POST /oauth/logins
Creates a partner sub-login
curl -X POST \
'https://api.carrierx.com/core/v2/oauth/logins' \
-H 'Content-Type: application/json' \
--data-binary '{"login":"carrierx_partner","password":"myStrongPassword123","token_scopes":["partners.read","partners.update"]}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the Partner Login object
{
"login": "carrierx_partner",
"login_sid": "abcf6b1f-7281-4da9-a4d6-3fb53e3a76de",
"partner_sid": "edebf627-ebce-4f77-8160-75db76154168",
"token_scopes": [
"partners.read",
"partners.update"
]
}
This request creates an additional login for a partner.
POST | /oauth/logins |
Required Scopes
To create a Partner Login object, the partner must have one of the following scopes enabled:
oauth.manage
oauth.create
Body Arguments
JSON representation of the fields and values of the Partner Login object to be created.
Required fields to create a partner login are:
login
password
token_scopes
- the first part must contain the current partner login to the system (
<partner.login>
); - the second part contains the sub-login used as additional login to the system (
<sub-login>
); - the two parts must be separated with the underscore.
Thus, the login
attribute value must look like the following:
<partner.login>_<sub-login> (e.g., carrierx_sublogin
)
Refer to this table to view all fields that appear in the Partner Login object.
Get Partner Logins
GET /oauth/logins
Returns partner logins matching the criteria in the request URL
curl -X GET \
'https://api.carrierx.com/core/v2/oauth/logins' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a list of Partner Login objects
{
"count": 1,
"has_more": false,
"items": [
{
"login": "carrierx_partner",
"login_sid": "abcf6b1f-7281-4da9-a4d6-3fb53e3a76de",
"partner_sid": "edebf627-ebce-4f77-8160-75db76154168",
"token_scopes": [
"partners.read",
"partners.update"
]
}
],
"limit": 10,
"offset": 0,
"pagination": {},
"total": 1
}
This request returns a list of partner logins.
GET | /oauth/logins |
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Required Scopes
To get information about Partner Login objects, the partner must have one of the following scopes enabled:
oauth.manage
oauth.read
Get Partner Login by SID
GET /oauth/logins/{login_sid}
Returns a partner login, targeted by secure ID
curl -X GET \
'https://api.carrierx.com/core/v2/oauth/logins/abcf6b1f-7281-4da9-a4d6-3fb53e3a76de' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the Partner Login object
{
"login": "carrierx_partner",
"login_sid": "abcf6b1f-7281-4da9-a4d6-3fb53e3a76de",
"partner_sid": "edebf627-ebce-4f77-8160-75db76154168",
"token_scopes": [
"partners.read",
"partners.update"
]
}
This request returns data for a partner login, targeted by secure ID.
GET | /oauth/logins/{login_sid} |
This request is enabled for Field Filtering.
Required Scopes
To get information about a Partner Login object, the partner must have one of the following scopes enabled:
oauth.manage
oauth.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
login_sid required | string | The partner login secure ID. |
Update Partner Login
PATCH /oauth/logins/{login_sid}
Updates the Partner Login object, targeted by secure ID, with the values in the request body
curl -X PATCH \
'https://api.carrierx.com/core/v2/oauth/logins/abcf6b1f-7281-4da9-a4d6-3fb53e3a76de' \
-H 'Content-Type: application/json' \
--data-binary '{"password":"myNewStrongPassword"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the updated Partner Login object
{
"login": "carrierx_partner",
"login_sid": "abcf6b1f-7281-4da9-a4d6-3fb53e3a76de",
"partner_sid": "edebf627-ebce-4f77-8160-75db76154168",
"token_scopes": [
"partners.read",
"partners.update"
]
}
This request updates a partner login, targeted by secure ID.
PATCH | /oauth/logins/{login_sid} |
PUT | /oauth/logins/{login_sid} |
A Partner Login object can be updated using either a PATCH
or PUT
request.
-
A
PATCH
request can be used to update one or more attribute values. When using aPATCH
request, only the attributes specified in the request payload will be updated, all other attributes and values will remain the same. The partner login secure ID is passed in the query URL, and the values to be modified are passed in the request body. -
A
PUT
request can be used to update an entire Partner Login object. The partner login secure ID is passed in the query URL, and the entire Partner Login object is passed in the request body.
Required Scopes
To update a Partner Login object, the partner must have one of the following scopes enabled:
oauth.manage
oauth.update
Path Arguments
Parameter | Data Type | Description |
---|---|---|
login_sid required | string | The partner login secure ID. |
Body Arguments
JSON representation of the fields and values to be updated.
The field that can be modified is password
.
Refer to this table to view all fields that appear in the Partner Login object.
Delete Partner Login
DELETE /oauth/logins/{login_sid}
Deletes a partner login, targeted by secure ID
curl -X DELETE \
'https://api.carrierx.com/core/v2/oauth/logins/abcf6b1f-7281-4da9-a4d6-3fb53e3a76de' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
204
status code with an empty body
This request deletes a partner login, targeted by secure ID.
DELETE | /oauth/logins/{login_sid} |
Required Scopes
To delete a Partner Login object, the partner must have one of the following scopes enabled:
oauth.manage
oauth.delete
Path Arguments
Parameter | Data Type | Description |
---|---|---|
login_sid required | string | The partner login secure ID. |
Partners
A partner is an individual or company with CarrierX credentials. Partners can have sub-partners, each of which is governed by its own set of credentials.
Partner Object
This section goes over the parts of the Partner object. These fields and values make up the JSON object that gets returned with successful requests.
Sample Partner object
{
"acls": [],
"address1": null,
"address2": null,
"attributes": {},
"available_scopes": [],
"balance": "5",
"billing_email": null,
"callbacks": {
"sms":"https://example.com/sms-callback-url"
},
"charge_at": null,
"city": null,
"company_name": "ABC",
"country_code": "USA",
"daily_spending_limit": "500",
"daily_spent_amount": "0",
"date_created": "2019-01-22T17:16:30.844Z",
"display_id": "CX57121051",
"login": "john",
"name": "John Smith",
"owner_email": null,
"parent_assigned_acls": [],
"parent_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
"partner_sid": "aeda835c-6627-4f4c-ac73-9edcae95640b",
"payment_type": "postpay",
"phonenumber": "180045012323",
"prepay_amount": null,
"spending_limit": "100",
"state": "",
"status": "unverified",
"tech_email": null,
"transformations": [],
"zip": "90804"
}
Attribute | Data Type | Description |
---|---|---|
acls create update | array of objects | The Access Control List, as defined on the Partner object directly. This holds a list of rules that determine the scope of data to be checked in SIP calls. This field is assigned on the Partner object itself and cannot be assigned by a parent partner. Refer to the table below for more information. |
address1 create update | string | The partner address. |
address2 create update | string | The partner address second field. |
attributes create update | object | The partner attributes. |
available_scopes read only | array | The abilities that this specific partner has. This field is for internal use only. Refer to this table for the complete list of available scopes. |
balance read only | number | The current balance of the partner. |
billing_email create update | string | The partner email address used for billing purposes. If this field is empty, the owner_email is used. In this field, you can add multiple email addresses separated by commas. |
callbacks create update | object | The callback URLs. The allowed callback URL types include:
|
charge_at create update | number | The balance value when the prepay account will be charged. |
city create update | string | The partner city. |
company_name create update | string | The partner company name. |
country_code create update | string | The partner country ISO 3166-1 alpha-3 code. |
daily_spending_limit create update | number | The maximum amount that the partner is allowed to spend on the account per day. |
daily_spent_amount read only | number | The amount that the partner has spent on the account during the current day. If this value exceeds the daily_spending_limit , the partner will be suspended until the end of the day. |
date_created read only | string | The date and time when the partner was created. |
display_id read only | string | The partner unique ID. |
login create | string | The login for web and Core API. |
name create update | string | The partner name. |
owner_email create update | string | The partner primary email address. |
parent_assigned_acls create update | array of objects | The Access Control List, as defined by a parent partner. This holds a list of rules that determine the scope of data to be checked in SIP calls. This field is assigned by the parent partner only. Refer to the table below for more information. |
parent_sid create update | string | The parent partner secure ID. |
partner_sid read only | string | The partner secure ID. |
password create update | string | The partner password for web and Core API. This field is required to create a partner, but is hidden in the serialized copy of the Partner objects received in responses to the requests for the security reasons. |
payment_type create | string | The type of payment. Values accepted in this field are prepay and postpay . Note that the default value is prepay . To change the payment_type , contact technical support at support@carrierx.com. |
phonenumber create update | string | The partner contact phone number. |
prepay_amount create update | number | The charge amount for prepay customers. |
spending_limit create | number | The maximum amount that a partner is allowed to spend on the account. |
state create update | string | The partner state; two-letter abbreviation code. |
status read only | string | The status of the partner. Values accepted in this field are:
suspended or soft_suspended . To learn about the conditions of activating the soft_suspended option, please contact support@carrierx.com. |
tech_email create update | string | The partner email address used for technical purposes. If this field is empty, the owner_email is used. In this field, you can add multiple email addresses separated by commas. |
transformations create update | array of objects | The list of transformations that a call will undergo. Refer to the transformations section for more information. |
zip create update | string | The partner zip code. |
ACL Object
This object is used with acls
and parent_assigned_acls
.
Attribute | Data Type | Description |
---|---|---|
access_control_rules create update | array | The list of access control rules secure IDs. Refer to the Access Control Rule object for more information about access control rules. |
direction create update | string | The direction for the access control list. Values accepted in this field are:
|
sms_action_false create update | string | The action to be executed for SMS messages if no access control rules are applied. Values accepted in this field are accept and reject . |
sms_action_true create update | string | The action to be executed for SMS messages if any access control rules are applied. Values accepted in this field are accept and reject . |
voice_action_false create update | string | The action to be executed for calls if no access control rules are applied. Values accepted in this field are:
|
voice_action_true create update | string | The action to be executed for calls if any access control rules are applied. Values accepted in this field are:
|
Create Partner
POST /partners
Creates a partner
curl -X POST \
'https://api.carrierx.com/core/v2/partners' \
-H 'Content-Type: application/json' \
--data-binary '{"login":"john", "password":"sample_password", "name":"John Smith", "company_name": "ABC", "parent_sid":"", "country_code":"USA", "zip":"90804", "owner_email": "johnsmith@carriex.com", "payment_type": "postpay", "phonenumber": "180045012323", "charge_at": 20, "prepay_amount": "100"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the Partner object
{
"acls": [],
"address1": null,
"address2": null,
"attributes": {},
"available_scopes": [],
"balance": "5",
"billing_email": null,
"callbacks": {
"sms":"https://example.com/sms-callback-url"
},
"charge_at": null,
"city": null,
"company_name": "ABC",
"country_code": "USA",
"daily_spending_limit": "500",
"daily_spent_amount": "0",
"date_created": "2019-01-22T17:16:30.844Z",
"display_id": "CX57121051",
"login": "john",
"name": "John Smith",
"owner_email": null,
"parent_assigned_acls": [],
"parent_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
"partner_sid": "aeda835c-6627-4f4c-ac73-9edcae95640b",
"payment_type": "postpay",
"phonenumber": "180045012323",
"prepay_amount": null,
"spending_limit": "100",
"state": "",
"status": "unverified",
"tech_email": null,
"transformations": [],
"zip": "90804"
}
This request creates a partner.
POST | /partners |
When a partner is created, a verification message is sent to the owner_email
, tech_email
, and billing_email
addresses provided. The email addresses will not appear in the Partner object until the link in the email body has been clicked, thereby confirming the email address and allowing the partner to use CarrierX services.
Required Scopes
To create a Partner object, the partner must have one of the following scopes enabled:
partners.manage
partners.create
Body Arguments
JSON representation of the fields and values of the Partner object to be created.
Required fields to create a partner are:
charge_at
company_name
country_code
login
owner_email
password
payment_type
phonenumber
prepay_amount
zip
Refer to this table to view all fields that appear in the Partner object.
Get Partners
GET /partners
Returns partners matching the criteria in the request URL
curl -X GET \
'https://api.carrierx.com/core/v2/partners' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a list of Partner objects
{
"count": 1,
"has_more": false,
"items": [
{
"acls": [],
"address1": null,
"address2": null,
"attributes": {},
"available_scopes": [
"accesscontrol.manage",
"app.manage",
"calls.manage",
"countries.manage",
"endpoints.manage",
"invoices.manage",
"lookup.dids.read",
"oauth.allow_token_scope_update",
"oauth.manage",
"oauth.manage_all_tokens",
"partners.billing_method.manage",
"partners.read",
"partners.update",
"phonenumber.manage",
"push.manage",
"rating.manage",
"shortener.manage",
"sms.manage",
"storage.manage",
"trunk_groups.manage",
"trunk_groups.trunks.manage",
"verification.manage"
],
"balance": "4.4",
"billing_email": "example@example.com",
"callbacks": {},
"charge_at": "20",
"city": null,
"company_name": "FreeConferenceCall",
"country_code": "USA",
"daily_spending_limit": "500",
"daily_spent_amount": "0",
"date_created": "2019-05-20T18:32:37.000Z",
"display_id": "CX15650613",
"login": "example",
"name": "John Smith",
"owner_email": "example@example.com",
"parent_assigned_acls": [
{
"access_control_rules": [
"41f8b2d4-68e4-42f7-43b7-357a090cb1ab"
],
"direction": "outbound",
"sms_action_false": null,
"sms_action_true": null,
"voice_action_false": null,
"voice_action_true": "reject403"
},
{
"access_control_rules": [
"50d74234-73c7-4da4-819e-6e34c451ed71"
],
"direction": "outbound",
"sms_action_false": null,
"sms_action_true": "reject",
"voice_action_false": null,
"voice_action_true": null
}
],
"parent_sid": "be128456-3098-4564-b0d1-67dbceee265f",
"partner_sid": "6bace9c5-3eef-4f75-8f48-fb98e04408be",
"payment_type": "prepay",
"phonenumber": "8448440707",
"prepay_amount": "100",
"spending_limit": "500",
"state": null,
"status": "active",
"tech_email": "example@example.com",
"transformations": [],
"zip": "90804"
}
],
"limit": 1000,
"offset": 0,
"pagination": {},
"total": 1
}
This request returns a list of partners.
GET | /partners |
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Required Scopes
To get information about Partner objects, the partner must have one of the following scopes enabled:
partners.manage
partners.read
Get Partner by SID
GET /partners/{partner_sid}
Returns a partner, targeted by secure ID
curl -X GET \
'https://api.carrierx.com/core/v2/partners/ed437757-002d-4ecc-aa5a-efdf5e50dba0' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the Partner object
{
"acls": [],
"address1": null,
"address2": null,
"attributes": {},
"available_scopes": [],
"balance": "351.52",
"billing_email": "example@example.com",
"callbacks": {},
"charge_at": "20",
"city": null,
"company_name": "CarrierX",
"country_code": "USA",
"daily_spending_limit": "500",
"daily_spent_amount": "0",
"date_created": "2018-09-20T21:34:55.000Z",
"display_id": "CX72521509",
"login": "example",
"name": "John Smith",
"owner_email": "example@example.com",
"parent_assigned_acls": [
{
"access_control_rules": [
"93525bae-f9a9-446b-b92a-7f421df7a11e"
],
"direction": "outbound",
"sms_action_false": null,
"sms_action_true": "accept",
"voice_action_false": null,
"voice_action_true": null
}
],
"parent_sid": "ac38616e-d2e7-4cd6-99ae-b6658f0728b6",
"partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
"payment_type": "prepay",
"phonenumber": "15162065819",
"prepay_amount": "100",
"spending_limit": "0",
"state": null,
"status": "active",
"tech_email": "example@example.com",
"transformations": [],
"zip": "90804"
}
This request returns data for a partner, targeted by secure ID.
GET | /partners/{partner_sid} |
This request is enabled for Field Filtering.
Required Scopes
To get information about a Partner object, the partner must have one of the following scopes enabled:
partners.manage
partners.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
partner_sid required | string | The partner secure ID. |
Update Partner
PATCH /partners/{partner_sid}
Updates the Partner object, targeted by secure ID, with the values in the request body
curl -X PATCH \
'https://api.carrierx.com/core/v2/partners/ed437757-002d-4ecc-aa5a-efdf5e50dba0' \
-H 'Content-Type: application/json' \
--data-binary '{"address1":"4300 E Pacific Coast Hwy"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the updated Partner object
{
"acls": [],
"address1": "4300 E Pacific Coast Hwy",
"address2": null,
"attributes": {},
"available_scopes": [],
"balance": "351.52",
"billing_email": "example@example.com",
"callbacks": {},
"charge_at": "20",
"city": null,
"company_name": "CarrierX",
"country_code": "USA",
"daily_spending_limit": "500",
"daily_spent_amount": "0",
"date_created": "2018-09-20T21:34:55.000Z",
"display_id": "CX72521509",
"login": "example",
"name": "John Smith",
"owner_email": "example@example.com",
"parent_assigned_acls": [
{
"access_control_rules": [
"93525bae-f9a9-336b-b92a-7f421df7a11e"
],
"direction": "outbound",
"sms_action_false": null,
"sms_action_true": "accept",
"voice_action_false": null,
"voice_action_true": null
}
],
"parent_sid": "ac38616e-d2e3-4cd6-99ae-b6658f0728b6",
"partner_sid": "ed437757-001d-4ecc-aa5a-efdf5e50dba0",
"payment_type": "prepay",
"phonenumber": "15162065574",
"prepay_amount": "100",
"spending_limit": "0",
"state": null,
"status": "active",
"tech_email": "example@example.com",
"transformations": [],
"zip": "90804"
}
This request updates a partner, targeted by secure ID.
PATCH | /partners/{partner_sid} |
PUT | /partners/{partner_sid} |
A Partner object can be updated using either a PATCH
or PUT
request.
-
A
PATCH
request can be used to update one or more attribute values. When using aPATCH
request, only the attributes specified in the request payload will be updated, all other attributes and values will remain the same. The partner secure ID is passed in the query URL, and the values to be modified are passed in the request body.The Partner object also contains nested ACLs, Attributes, Callbacks, Parent Assigned ACLs, and Transformations objects. Refer to this section to learn how nested objects can be updated using the
PATCH
request. -
A
PUT
request can be used to update an entire Partner object. The partner secure ID is passed in the query URL, and the entire Partner object is passed in the request body.
Required Scopes
To update a Partner object, the partner must have one of the following scopes enabled:
partners.manage
partners.update
Path Arguments
Parameter | Data Type | Description |
---|---|---|
partner_sid required | string | The partner secure ID. |
Query Arguments
Parameter | Data Type | Description |
---|---|---|
nested_objects | string | Determines if the nested objects fields and values should be replaced. Value accepted in this field is replace . |
Body Arguments
JSON representation of the fields and values to be updated.
Fields that can be modified are:
acls
address1
address2
attributes
billing_email
callbacks
city
company_name
name
owner_email
parent_assigned_acls
phonenumber
tech_email
transformations
zip
Refer to this table to view all fields that appear in the Partner object.
Delete Partner
DELETE /partners/{partner_sid}
Deletes a partner, targeted by secure ID
curl -X DELETE \
'https://api.carrierx.com/core/v2/partners/aeda835c-6627-4f4c-ac73-9edcae95640b' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
204
status code with an empty body
This request deletes a partner, targeted by secure ID.
DELETE | /partners/{partner_sid} |
This action is not possible to accomplish until the selected partner owns sub-partners. All sub-partner accounts must be deleted before a parent partner is deleted.
Required Scopes
To delete a Partner object, the partner must have one of the following scopes enabled:
partners.manage
partners.delete
Path Arguments
Parameter | Data Type | Description |
---|---|---|
partner_sid required | string | The secure ID of the partner to be deleted. |
Billing Method Object
A billing method is how a partner will pay for services rendered. This section goes over the parts of the Billing Method object. These fields and values make up the JSON response that gets returned when a request is successful.
Sample Billing Method object
{
"address1":"4300 E Pacific Coast Hwy",
"address2":"Suite 1",
"cc_expiration":"022019",
"cc_number":"8888",
"city":"Long Beach",
"country_code":"USA",
"first_name":"John",
"last_name":"Smith",
"phone":"15162065574",
"state":"CA",
"type":"visa",
"zip": "90804"
}
Attribute | Data Type | Description |
---|---|---|
address1 create | string | The customer address. |
address2 create | string | The customer address second field. |
cc_cid create | string | The credit card CID. This field is hidden in the serialized copy of the Billing Method objects received in responses to the requests for the security reasons. |
cc_expiration create | string | The credit card expiration date in the mmyyyy format. |
cc_number create | string | The credit card number. |
city create | string | The customer city. |
country_code create | string | The partner country code. |
ec_account_number create | string | The electronic check account number. |
ec_routing_number create | string | The electronic check routing number. |
first_name create | string | The partner first name. |
last_name create | string | The partner last name. |
phone create | string | The partner phone number. |
state create | string | The customer state in a two-letter abbreviation format. |
type create | string | The type of the billing method. Values accepted in this field are:
|
zip create | string | The customer zip code. |
Register Billing Method
POST /partners/{partner_sid}/billing_method
Registers a billing method to a specific partner
curl -X POST \
'https://api.carrierx.com/core/v2/partners/ed437757-002d-4ecc-aa5a-efdf5e50dba0/billing_method' \
-H 'Content-Type: application/json' \
--data-binary '{"type":"visa", "cc_number":"4012888818888", "cc_expiration":"022019", "cc_cid":"318", "first_name":"John", "last_name":"Smith", "address1":"4300 E Pacific Coast Hwy", "address2":"Suite 1", "city":"Los Angeles", "state":"CA", "zip":"90804", "country_code":"USA", "phone":"15162065574"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the Billing Method object
{
"address1":"4300 E Pacific Coast Hwy",
"address2":"Suite 1",
"cc_expiration":"022019",
"cc_number":"8888",
"city":"Long Beach",
"country_code":"USA",
"first_name":"John",
"last_name":"Smith",
"phone":"15162065574",
"state":"CA",
"type":"visa",
"zip": "90804"
}
This request registers the billing method for a customer.
POST | /partners/{partner_sid}/billing_method |
Required Scopes
To register a billing method the partner must have one of the following scopes enabled:
partners.billing_method.manage
partners.billing_method.create
Path Arguments
Parameter | Data Type | Description |
---|---|---|
partner_sid required | string | The partner secure ID. |
Body Arguments
JSON representation of the fields and values of the Billing Method object to be created.
Required fields to create a billing method are:
address1
(forcheck
,electronic_check
, andwire
billing methods)cc_cid
(for credit card billing methods)cc_expiration
(for credit card billing methods)cc_number
(for credit card billing methods)city
(forcheck
,electronic_check
, andwire
billing methods)country_code
first_name
last_name
phone
type
zip
Refer to this table to view all fields that appear in the Billing Method object.
Get Billing Method by Partner SID
GET /partners/{partner_sid}/billing_method
Returns a billing method, targeted by partner secure ID
curl -X GET \
'https://api.carrierx.com/core/v2/partners/ed437757-002d-4ecc-aa5a-efdf5e50dba0/billing_method' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the Billing Method object
{
"address1": "4300 E Pacific Coast Hwy",
"address2": "Suite 1",
"cc_expiration": "022020",
"cc_number": "8888",
"city": "Long Beach",
"country_code": "USA",
"first_name": "John",
"last_name": "Smith",
"phone": "15162065574",
"state": "CA",
"type": "visa",
"zip": "90804"
}
This request returns information registered for the selected partner.
GET | /partners/{partner_sid}/billing_method |
This request is enabled for Field Filtering.
Required Scopes
To get information about a Billing Method object, the partner must have one of the following scopes enabled:
partners.billing_method.manage
partners.billing_method.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
partner_sid required | string | The partner secure ID. |
Delete Billing Method
DELETE /partners/{partner_sid}/billing_method
Deletes a billing method associated with the targeted partner secure ID
curl -X DELETE \
'https://api.carrierx.com/core/v2/partners/ed437757-002d-4ecc-aa5a-efdf5e50dba0/billing_method' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
204
status code with an empty body
This request deletes a billing method of the partner, targeted by secure ID.
DELETE | /partners/{partner_sid}/billing_method |
When completed, no billing method will be registered for the specified partner.
Required Scopes
To delete a Billing Method object, the partner must have one of the following scopes enabled:
partners.billing_method.manage
partners.billing_method.delete
Path Arguments
Parameter | Data Type | Description |
---|---|---|
partner_sid required | string | The partner secure ID. |
Effective Rate Object
Sample Effective Rate object
{
"assignment": {
"active": "yes",
"assignment_sid": "2aa25903-6312-4c4f-9ea6-bbc7a060e142",
"direction": "inbound",
"effective_date": "2017-10-03T00:00:00.000Z",
"endpoint_sid": null,
"partner_sid": "b9Ua99icuAdvDvv2kvlNaPzMLDXwuEYJ",
"plan_name": "voice_inbound_rates-2017-10-15",
"plan_sid": "6ab7df5d-7603-4d1b-8f5e-223b7dee0c6d",
"sub_type": null,
"type": "pstn"
},
"plan": {
"date_created": "2017-10-19T14:33:07.000Z",
"name": "voice_inbound_rates-2017-10-15",
"owner_sid": "b9Ua99icuAdvDvv2kvlNaPzMLDXwuEYJ",
"plan_sid": "6ab7df5d-7603-4d1b-8f5e-223b7dee0c6d",
"type": "phonenumber"
}
}
This section outlines the Effective Rate object. An effective rate is the current rate the partner has. An effective rate is a combination of a rate plan and the actual instance of assigning that rate plan to the partner. The fields listed in the table below will be returned in a JSON object when a successful request has been made.
Attribute | Data Type | Description |
---|---|---|
assignment read only | object | Information about the rate assignment used to assign this rate plan to the partner. Every time a rate plan is assigned, a rate assignment record is created. Values returned in this field are:
|
plan read only | object | Information about the rate plan associated with this rate assignment. Values returned in this field are:
|
Rate Assignment Object
Attribute | Data Type | Description |
---|---|---|
active read only | string | Whether this rate assignment is currently active or not. Values returned in this field are no and yes . This field depends on the effective_date value and on the parent partner rate assignments. The assignment becomes active at the time specified in the effective_date attribute. The assignment can be inactive in two cases: until the effective_date has occurred and if it is replaced by a succeeding rate assignment of the same type and a new effective_date . |
assignment_sid read only | string | The rate assignment secure ID. |
direction read only | string | The rate plan direction. Values returned in this field are:
|
effective_date read only | string | The date and time when the rate plan goes into effect. |
endpoint_sid read only | string | The secure ID of the endpoint for which this rate plan is effective. This field contains a value only if the rate assignment is of the lcr type. Otherwise it will be null . |
partner_sid read only | string | The secure ID of the partner with which this rate assignment is associated. |
plan_name read only | string | The rate plan name. |
plan_sid read only | string | The rate plan secure ID. |
sub_type read only | string | The rate assignment subtype that this rate plan affects.
|
type read only | string | The rate assignment type. Values returned in this field are: did , event , lcr , mms , pstn , sms , sms_mms_passthrough and voip . |
Rate Plan Object
Attribute | Data Type | Description |
---|---|---|
date_created read only | string | The date and time when the rate plan was created. |
name read only | string | The rate plan file name. |
owner_sid read only | string | The secure ID of the partner to whom the rate plan belongs. |
plan_sid read only | string | The rate plan secure ID. |
type read only | string | The rate plan type. Values returned in this field are:
|
Get Effective Rates for Partner
GET /partners/{partner_sid}/effective_rates
Returns all currently Effective Rates for a specific partner
curl -X GET \
'https://api.carrierx.com/core/v2/partners/b9Ua99icuAdvDvv2kvlNaPzMLDXwuEYJ/effective_rates' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a list of Effective Rate objects
{
"assignment": {
"active": "yes",
"assignment_sid": "2aa25903-6312-4c4f-9ea6-bbc7a060e142",
"direction": "inbound",
"effective_date": "2017-10-03T00:00:00.000Z",
"endpoint_sid": null,
"partner_sid": "b9Ua99icuAdvDvv2kvlNaPzMLDXwuEYJ",
"plan_name": "voice_inbound_rates-2017-10-15",
"plan_sid": "6ab7df5d-7603-4d1b-8f5e-223b7dee0c6d",
"sub_type": null,
"type": "pstn"
},
"plan": {
"date_created": "2017-10-19T14:33:07.000Z",
"name": "voice_inbound_rates-2017-10-15",
"owner_sid": "b9Ua99icuAdvDvv2kvlNaPzMLDXwuEYJ",
"plan_sid": "6ab7df5d-7603-4d1b-8f5e-223b7dee0c6d",
"type": "phonenumber"
}
}
This request returns all currently Effective Rates for a specific partner.
GET | /partners/{partner_sid}/effective_rates |
This request is enabled for Field Filtering.
Required Scopes
To get information about the Effective Rates, the partner must have one of the following scopes enabled:
partners.manage
partners.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
partner_sid required | string | The secure ID of the partner whose rate plans will be returned. |
Phone Numbers
Phone numbers rentable through the CarrierX API are called Direct Inward Dialing numbers (DIDs). DIDs can be organized into DID groups.
Refer to the Browse Available DIDs section to query the phone number inventory for available phone numbers, their supported and active capabilities.
Prefixes allow you to route outbound calls based on the starting segment of the dialed phone number. Prefixes are sequences of digits you can set up to route your outbound calls to a desired trunk group on your partner.
Short codes are short phone numbers used for SMS communications.
DID Object
This section outlines the DID object. The fields listed in the table below will be returned in a JSON object when a successful request has been made.
Sample DID object
{
"active_capabilities": 4,
"attributes": {},
"callback_url": null,
"campaign_sid": null,
"capabilities": 7,
"classification_sid": "17f4d954-d635-4cda-912b-c2a2fa3a6860",
"country_code": "USA",
"did_group_sid": null,
"did_sid": "f448e2c3-88c1-4cd1-8cf2-3567c16e0794",
"in_country_format": "(516) 206-5575",
"international_format": "+1 516-206-5575",
"locality": "NEW YORK",
"lrn_sid": null,
"name": "N/A",
"partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
"phonenumber": "15162065575",
"porting_pin": null,
"price": "0.6",
"state": "NY",
"status": "assigned",
"string_key_1": null,
"string_key_2": null,
"transformations": [],
"trunk_group_sid": null
}
Attribute | Data Type | Description |
---|---|---|
active_capabilities read only | integer | The phone number enabled (activated) capabilities. Criteria are similar to the capabilities attribute below. Note that this attribute is fully managed by the system and its status depends on whether SMS/MMS is enabled for a DID. To activate the SMS/MMS capabilities of your rented DIDs, you need to enable them. See also SMS/MMS enablement. |
attributes create update | object | The DID attributes. |
callback_url create update | string | The callback URL to receive events for SMS. |
campaign_sid read only | string | The secure ID of the 10DLC campaign associated with the DID. |
capabilities read only | integer | The phone number supported capabilities. Capabilities represent what this DID is potentially capable of: receiving, sending SMS, MMS, voice calls, etc. This field accepts numerical values. To enable more than one capability, add the corresponding integers together. The following are the numerical values for each capability:
1 and 4 together to make 5 . The maximum value for this field is 31 (1 + 2 + 4 + 8 + 16 ) for all capabilities: SMS (receiving and sending), voice, and MMS (receiving and sending). Note, that by default, SMS/MMS messaging capabilities are disabled for all rented DIDs. To enable these capabilities, you need to have them activated. With non-activated capabilities an error will be returned when trying to send an SMS/MMS. See also the active_capabilities attribute above. |
classification_sid read only | string | The phone number classification secure ID, which can be set to one of the DID Classification object secure IDs. |
country_code read only | string | The ISO 3166-1 alpha-3 code of this DID. This field is assigned automatically. |
did_group_sid create update | string | The DID group secure ID. |
did_sid read only | string | The DID secure ID. |
in_country_format read only | string | The DID in a national format. |
international_format read only | string | The DID in an international format. |
locality read only | string | The locality or city of the DID. |
lrn_sid read only | string | The secure ID of the Location Routing Number assigned to this DID. |
name create update | string | The DID name. The default value is N/A . |
partner read only | object | The Partner object associated with the DID. This field is displayed if with_related is set to true when performing the GET queries. |
partner_sid read only | string | The secure ID of the partner associated with the DID. |
phonenumber create | string | The phone number for the DID in the E.164 format. |
porting_pin create update | string | A random 6-digit PIN code automatically assigned to a DID when it is rented. The porting PIN is used to verify requests for DID porting. The PIN code can be changed at any time. |
price read only | number | The price of the DID. |
state read only | string | The state or province of the DID. |
status read only | string | The current DID status. Values accepted in this field are:
|
string_key_1 create update | string | A user-defined string key. |
string_key_2 create update | string | A user-defined string key. |
transformations create update | array of objects | The transformations that are applied to the DID. Refer to the transformations section for more information. |
trunk_group_sid create update | string | The secure ID of the trunk group associated with the DID. |
Rent DID
POST /phonenumber/dids
Assigns a DID to a partner
curl -X POST \
'https://api.carrierx.com/core/v2/phonenumber/dids' \
-H 'Content-Type: application/json' \
--data-binary '{"phonenumber":"15162065575", "callback_url":null}'
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the DID object
{
"active_capabilities": 4,
"attributes": {},
"callback_url": null,
"campaign_sid": null,
"capabilities": 31,
"classification_sid": "17f4d954-d635-4cda-912b-c2a2fa3a6860",
"country_code": "USA",
"did_group_sid": null,
"did_sid": "f448e2c3-88c1-4cd1-8cf2-3567c16e0794",
"in_country_format": "(516) 206-5575",
"international_format": "+1 516-206-5575",
"locality": "NEW YORK",
"lrn_sid": null,
"name": "N/A",
"partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
"phonenumber": "15162065575",
"porting_pin": null,
"price": "0.6",
"state": "NY",
"status": "assigned",
"string_key_1": null,
"string_key_2": null,
"transformations": [],
"trunk_group_sid": null
}
This request assigns a DID to a partner.
POST | /phonenumber/dids |
Required Scopes
To create a DID object, the partner must have one of the following scopes enabled:
phonenumber.manage
phonenumber.create
Body Arguments
JSON representation of the fields and values of the DID object to be created.
No fields are required to rent a DID, an empty object can be passed.
If you do not specify a phone number, the system will assign the first available phone number to you.
If you want to rent a specific phone number, you need to pass it as a value for the phonenumber
body attribute.
Query Arguments
Parameter | Data Type | Description |
---|---|---|
include_external | boolean | Determines whether the system should look for a phone number from an external provider in case it cannot locate a DID matching your filter criteria among the DIDs owned by CarrierX. Values accepted in this field are true and false . The default value is false . |
filter | string | Restricts the phone number to be rented by some parameters (e.g., capabilities, state, country_code , etc.) and returns the first available phone number matching the filter when you do not specify any body arguments. If include_external=true the country_code parameter is required except for the case when you pass a specific DID as the phonenumber body argument. If include_external=true only the following combinations of filter parameters and operators are available in the result filter:
|
Refer to this table to view all fields that appear in the DID object.
Response
The status of the DID you have ordered will depend on whether it is an internal DID from CarrierX or an external one.
In case it is an internal DID, it will immediately get the assigned
status.
If you have ordered an external DID, its initial status is pending_assignment
meaning that an external order for the DID has been created but not completed yet. After a while it changes to assigned
. CarrierX will send you a callback on the external order completion, i.e. when a phone number changes its state from pending_assignment
to assigned
. The callback is identified as phonenumber_order and is configured by the partner on the Partner object. Please be aware that you cannot use your DID until its status changes to assigned
.
Get DIDs
GET /phonenumber/dids
Returns rented DIDs matching the criteria in the request URL
curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/dids' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a list of DID objects
{
"count": 1,
"has_more": true,
"items": [
{
"active_capabilities": 4,
"attributes": {},
"callback_url": null,
"campaign_sid": null,
"capabilities": 7,
"classification_sid": "17f4d954-d635-4cda-912b-c2a2fa3a6860",
"country_code": "USA",
"did_group_sid": null,
"did_sid": "e8df62d5-07a3-4189-a67e-87585067c5fe",
"in_country_format": "(516) 206-5574",
"international_format": "+1 516-206-5574",
"locality": "NEW YORK",
"lrn_sid": null,
"name": "N/A",
"partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
"phonenumber": "15162065574",
"porting_pin": null,
"price": "0.6",
"state": "NY",
"status": "assigned",
"string_key_1": null,
"string_key_2": null,
"transformations": [],
"trunk_group_sid": null
}
],
"limit": 1,
"offset": 0,
"pagination": {
"next": "https://api.carrierx.com/core/v2/phonenumber/dids?limit=1&offset=1"
},
"total": 2
}
This request returns a list of DIDs that have been rented.
GET | /phonenumber/dids |
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Required Scopes
To get information about DID objects, the partner must have one of the following scopes enabled:
phonenumber.manage
phonenumber.read
Query Arguments
Parameter | Data Type | Description |
---|---|---|
trunk_group_sid | string | The trunk group secure ID, used to return DIDs only for a specific trunk group. |
with_related | boolean | Determines if the partner information related to the phone number should be shown. Values accepted in this field are true and false . The default value is false . |
Get DID by SID
GET /phonenumber/dids/{did_sid}
Returns data for a DID, targeted by secure ID
curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/dids/e8df62d5-07a3-4189-a67e-87585067c5fe' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the DID object
{
"active_capabilities": 4,
"attributes": {},
"callback_url": null,
"campaign_sid": null,
"capabilities": 7,
"classification_sid": "17f4d954-d635-4cda-912b-c2a2fa3a6860",
"country_code": "USA",
"did_group_sid": null,
"did_sid": "e8df62d5-07a3-4189-a67e-87585067c5fe",
"in_country_format": "(516) 206-5574",
"international_format": "+1 516-206-5574",
"locality": "NEW YORK",
"lrn_sid": null,
"name": "N/A",
"partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
"phonenumber": "15162065574",
"porting_pin": null,
"price": "0.6",
"state": "NY",
"status": "assigned",
"string_key_1": null,
"string_key_2": null,
"transformations": [],
"trunk_group_sid": null
}
This request returns data for a DID, targeted by secure ID.
GET | /phonenumber/dids/{did_sid} |
This request is enabled for Field Filtering.
Required Scopes
To get information about a DID object, the partner must have one of the following scopes enabled:
phonenumber.manage
phonenumber.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
did_sid required | string | The secure ID of the DID. |
Query Arguments
Parameter | Data Type | Description |
---|---|---|
with_related | boolean | Determines if the partner information related to the phone number should be shown. Values accepted in this field are true and false . The default value is false . |
Update DID
PATCH /phonenumber/dids/{did_sid}
Updates the DID object, targeted by secure ID, with the values in the request body
curl -X PATCH \
'https://api.carrierx.com/core/v2/phonenumber/dids/e8df62d5-07a3-4189-a67e-87585067c5fe' \
-H 'Content-Type: application/json' \
--data-binary '{"attributes":{"name":"main line"}}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the updated DID object
{
"active_capabilities": 4,
"attributes": {
"name": "main line"
},
"callback_url": null,
"campaign_sid": null,
"capabilities": 7,
"classification_sid": "17f4d954-d635-4cda-912b-c2a2fa3a6860",
"country_code": "USA",
"did_group_sid": null,
"did_sid": "e8df62d5-07a3-4189-a67e-87585067c5fe",
"in_country_format": "(516) 206-5574",
"international_format": "+1 516-206-5574",
"locality": "NEW YORK",
"lrn_sid": null,
"name": "N/A",
"partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
"phonenumber": "15162065574",
"porting_pin": null,
"price": "0.6",
"state": "NY",
"status": "assigned",
"string_key_1": null,
"string_key_2": null,
"transformations": [],
"trunk_group_sid": null
}
This request updates a DID, targeted by secure ID.
PATCH | /phonenumber/dids/{did_sid} |
PUT | /phonenumber/dids/{did_sid} |
A DID object can be updated using either a PATCH
or PUT
request.
-
A
PATCH
request can be used to update one or more attribute values. When using aPATCH
request, only the attributes specified in the request payload will be updated, all other attributes and values will remain the same. The DID secure ID is passed in the query URL, and the values to be modified are passed in the request body.The DID object also contains nested Attributes and Transformations objects. Refer to this section to learn how nested objects can be updated using the
PATCH
request. -
A
PUT
request can be used to update an entire DID object. The DID secure ID is passed in the query URL, and the entire DID object is passed in the request body.
Required Scopes
To update a DID object, the partner must have one of the following scopes enabled:
phonenumber.manage
phonenumber.update
Path Arguments
Parameter | Data Type | Description |
---|---|---|
did_sid required | string | The DID secure ID. |
Query Arguments
Parameter | Data Type | Description |
---|---|---|
nested_objects | string | Determines if the nested objects fields and values should be replaced. Value accepted in this field is replace . |
Body Arguments
JSON representation of the fields and values to be updated.
Fields that can be modified are:
attributes
callback_url
did_group_sid
name
string_key_1
string_key_2
transformations
trunk_group_sid
Refer to this table to view all fields that appear in the DID object.
Release DID
DELETE /phonenumber/dids/{did_sid}
Releases a DID, targeted by secure ID, from the partner account
curl -X DELETE \
'https://api.carrierx.com/core/v2/phonenumber/dids/e8df62d5-07a3-4189-a67e-87585067c5fe' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
204
status code with an empty body
This request releases a DID, targeted by secure ID, from the partner account. The DID status changes from assigned
to ‘aging’.
DELETE | /phonenumber/dids/{did_sid} |
Required Scopes
To release a DID object, the partner must have one of the following scopes enabled:
phonenumber.manage
phonenumber.delete
Path Arguments
Parameter | Data Type | Description |
---|---|---|
did_sid required | string | The secure ID of the DID. |
Browse Available DIDs
GET /phonenumber/available_dids
Returns available DIDs matching the criteria in the request URL
curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/available_dids?limit=1' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a list of available DID objects
{
"count": 1,
"has_more": true,
"items": [
{
"active_capabilities": 4,
"attributes": {},
"callback_url": null,
"campaign_sid": null,
"capabilities": 7,
"classification_sid": "17f4d954-d635-4cda-912b-c2a2fa3a6860",
"country_code": "USA",
"did_group_sid": null,
"did_sid": "07e3dee3-2f0d-4254-b635-21334ccde8b9",
"in_country_format": "(516) 206-5573",
"international_format": "+1 516-206-5573",
"locality": "NEW YORK",
"lrn_sid": null,
"name": "N/A",
"partner_sid": null,
"phonenumber": "15162065573",
"porting_pin": null,
"price": "0.6",
"state": "NY",
"status": "available",
"string_key_1": null,
"string_key_2": null,
"transformations": [],
"trunk_group_sid": null
}
],
"limit": 1,
"offset": 0,
"pagination": {
"next": "https://api.carrierx.com/core/v2/phonenumber/available_dids?limit=1&offset=1"
},
"total": null
}
This request returns a pool of rentable phone numbers.
GET | /phonenumber/available_dids |
GET | /dids/inventory deprecated |
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Required Scopes
To get information about rentable numbers the partner must have one of the following scopes enabled:
phonenumber.manage
phonenumber.read
Filtering by Location
CarrierX allows you to filter the available phone numbers by their geographical location and area codes. Refer to the table below to see the parameters which you can use to do this.
Parameter | Description | Syntax | Examples |
---|---|---|---|
latlng | Use this option to search for the phone numbers located closer to the area described by geographical coordinates specified. | phonenumber nearby latlng:<latitude,longitude> | filter=phonenumber+nearby+latlng%3A40.801912%2C-73.9681657 |
npa | Use this option to search for the phone numbers located closer to the area associated with the NANP area code specified. | phonenumber nearby npa:<npa> | filter=phonenumber+nearby+npa%3A516 |
zip | Use this option to search for the phone numbers located closer to the area associated with the ZIP code specified. | phonenumber nearby zip:<zip> | filter=phonenumber+nearby+zip%3A10025 |
Query Arguments
Parameter | Data Type | Description |
---|---|---|
include_external | boolean | Determines whether the system should look for a phone number from an external provider in case it cannot locate a DID matching your filter criteria among the DIDs owned by CarrierX. Values accepted in this field are true and false . The default value is false .If include_external=true , pagination is not supported; the offset must be 0, the limit is set by the user but the number of records in the response depends on the external provider. The system will try to offer a sufficient amount of DIDs satisfying the request criteria from its internal database first, and if this amount is not sufficient, then the system will send a request to the external DIDs provider. Note that the maximum number of external DIDs shown per request is 10. Internally available phone numbers are shown in the request results list first, followed by external numbers.Important: if include_external=true the request must contain a filter with the country_code parameter.If include_external=true only the following combinations of filter parameters and operators are allowed in the result filter:
|
Get Available DID by SID
GET /phonenumber/available_dids/{did_sid}
Returns available DID, targeted by secure ID
curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/available_dids/07e3dee3-2f0d-4254-b635-21334ccde8b9' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the DID object
{
"active_capabilities": 4,
"attributes": {},
"callback_url": null,
"campaign_sid": null,
"capabilities": 7,
"classification_sid": "17f4d954-d635-4cda-912b-c2a2fa3a6860",
"country_code": "USA",
"did_group_sid": null,
"did_sid": "07e3dee3-2f0d-4254-b635-21334ccde8b9",
"in_country_format": "(516) 206-5573",
"international_format": "+1 516-206-5573",
"locality": "NEW YORK",
"lrn_sid": null,
"name": "N/A",
"partner_sid": null,
"phonenumber": "15162065573",
"porting_pin": null,
"price": "0.6",
"state": "NY",
"status": "available",
"string_key_1": null,
"string_key_2": null,
"transformations": [],
"trunk_group_sid": null
}
This request returns data for a rentable phone number, targeted by secure ID.
GET | /phonenumber/available_dids/{did_sid} |
This request is enabled for Field Filtering.
Required Scopes
To get information about rentable numbers the partner must have one of the following scopes enabled:
phonenumber.manage
phonenumber.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
did_sid required | string | The secure ID of the DID. |
DID Messaging Enablement Object
This section outlines the DID Messaging Enablement object. These fields and values make up the JSON response that gets returned when a request is successful.
Sample DID Messaging Enablement object
{
"campaign_sid": "fef13cdd-2f65-4ed8-8272-de2a940d0cb5",
"enabled": true,
"status": "enabled",
"type": "a2p"
}
Attribute | Data Type | Description |
---|---|---|
campaign_sid create | string | The secure ID of the partner’s 10DLC campaign that is used for SMS enablement on this phone number. This attribute applies only if the DID enablement type is a2p . |
enabled create | boolean | Whether SMS/MMS messaging is enabled or disabled for this DID. If set to true , messaging is enabled. The default value is false . |
status read only | string | Current status of SMS/MMS messaging for this DID. Values that returned in this field are:
disabled . |
type create | string | Sets the phone number enablement type, a2p or p2p. Values accepted in this field are a2p and p2p . If this value is not set, the phone number will use the partner/global default value. By default, partners are only enabled for a2p messaging. Please contact technical support at support@carrierx.com if you need the p2p messaging type to be enabled on your DIDs. |
To be able to send SMS/MMS from a rented DID, messaging must be enabled for that DID.
Enable or Disable SMS/MMS Messaging for DID
POST /phonenumber/dids/{did_sid}/messaging
Enables or disables SMS/MMS for the rented DID
curl -X POST \
'https://api.carrierx.com/core/v2/phonenumber/dids/f3125c23-29dd-41b7-5dbc-89edba59230d/messaging' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-binary '{"enabled": true, "type": "a2p"}' \
-H 'Authorization: Bearer 5ebe03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with information about the status of SMS/MMS enablement for the rented DID.
{
"campaign_sid": "fef13cdd-2f65-4ed8-8272-de2a940d0cb5",
"enabled": true,
"status": "in_progress",
"type": "a2p"
}
If no SMS/MMS
capabilities
are set for this DID, i.e. if this DID has only voicecapabilities
, the request will return the404
status code with theno item error
message .
{
"message": "no item error",
"errors": [
{
"field": null,
"message": "cannot find item by sid",
"reference_sid": null
}
]
}
This request enables or disables SMS/MMS messaging for a rented DID.
POST | /phonenumber/dids/{did_sid}/messaging |
Required Scopes
To enable SMS/MMS messaging for a rented DID, the partner must have the following scopes enabled:
phonenumber.create
phonenumber.manage
Path Arguments
Parameter | Data Type | Description |
---|---|---|
did_sid required | string | The DID secure ID. |
Body Arguments
Parameter | Data Type | Description |
---|---|---|
enabled | boolean | Determines whether SMS/MMS messaging must be enabled or disabled for the phone number. Values accepted in this field are true and false . |
Response
A successful response will be the 200 OK
code and the DID status will be one of the following:
in_progress
, meaning that the phone number is being processed for message enablement. Sometimes, this process may take up to several minutes. While the status isin_progress
, no further messaging update requests are accepted for this DID. If aPOST
request is sent to a DID with thein_progress
status, a409
error will be returned.enabled
, meaning that SMS/MMS messaging is enabled for this phone number.disabled
, meaning that SMS/MMS messaging is disabled for this phone number.failed
, meaning that some error has occurred in the process.
To be notified when the messaging status changes for a particular DID, you can set up the phonenumber_messaging_update callback.
Get SMS/MMS Messaging Information for DID
GET /phonenumber/dids/{did_sid}/messaging
Returns the status of SMS/MMS messaging for a rented DID, targeted by secure ID
curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/dids/f3115c13-29dd-41b7-5dbc-89edbc59230d/messaging' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with information about the status of SMS/MMS enablement for the rented DID.
{
"campaign_sid": "fef13cdd-2f65-4ed8-8272-de2a940d0cb5",
"enabled": true,
"status": "enabled"
"type": "a2p"
}
If no SMS/MMS
capabilities
are set for this DID, i.e. if this DID has only voicecapabilities
, the request will return the404
status code with theno item error
message .
{
"message": "no item error",
"errors": [
{
"field": null,
"message": "cannot find item by sid",
"reference_sid": null
}
]
}
This request returns the status of SMS/MMS messaging for a DID, targeted by secure ID.
GET | /phonenumber/dids/{did_sid}/messaging |
This request is enabled for Field Filtering.
Required Scopes
To get information about a DID object, the partner must have one of the following scopes enabled:
phonenumber.manage
phonenumber.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
did_sid required | string | The DID secure ID. |
DID Classification Object
Sample DID Classification object
{
"aging_policy": 86400,
"classification_sid": "17f4d954-d635-4cda-912b-c2a2fa3a6860",
"name": "Default"
}
This section goes over the parts of the DID Classification object. These fields and values make up the JSON response that gets returned when a request is successful.
Attribute | Data Type | Description |
---|---|---|
aging_policy read only | integer | The number of minutes after a DID is released, during which time the phone number status is aging and the number cannot be rented. |
classification_sid read only | string | The DID classification secure ID. |
name read only | string | An arbitrary, human readable DID classification name. |
Get DID Classifications
GET /phonenumber/classifications
Returns DID classifications matching the criteria in the request URL
curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/classifications' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a list of DID Classification objects
{
"count": 1,
"has_more": false,
"items": [
{
"aging_policy": 86400,
"classification_sid": "17f4d954-d635-4cda-912b-c2a2fa3a6860",
"name": "Default"
}
],
"limit": null,
"offset": null,
"pagination": {},
"total": 1
}
This request returns a list of DID classifications.
GET | /phonenumber/classifications |
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Required Scopes
To get information about DID Classification objects, the partner must have one of the following scopes enabled:
phonenumber.manage
phonenumber.read
Get DID Classification by SID
GET /phonenumber/classifications/{classification_sid}
Returns a DID classification, targeted by secure ID
curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/classifications/17f4d954-d635-4cda-912b-c2a2fa3a6860' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the DID Classification object
{
"aging_policy": 86400,
"classification_sid": "17f4d954-d635-4cda-912b-c2a2fa3a6860",
"name": "Default"
}
This request returns data for a DID classification, targeted by secure ID.
GET | /phonenumber/classifications/{classification_sid} |
This request is enabled for Field Filtering.
Required Scopes
To get information about a DID Classification object, the partner must have one of the following scopes enabled:
phonenumber.manage
phonenumber.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
classification_sid required | string | The DID classification secure ID. |
DID Emergency Object
This section goes over the parts of the DID Emergency object. These fields and values make up the JSON response that gets returned when a request is successful.
Sample DID Emergency object
{
"caller_name": "J Smith",
"enabled": true,
"locations": [
{
"address_1": "8104 E Nora Ave",
"address_2": "",
"city": "Spokane Valley",
"country_code": "USA",
"state": "WA",
"zip": "99212"
}
]
}
Attribute | Data Type | Description |
---|---|---|
caller_name update | string | The name that will appear on receiving party phones. |
enabled update | boolean | If this field is set to false , no record is stored in the central CNAM registry. Fields can still be updated when the value is false . |
locations update | array of objects | The list of locations that will be used for emergency. Refer to the table below for the description of the location object parameters. |
Location Object
Attribute | Data Type | Description |
---|---|---|
address_1 update | string | The emergency location address line 1. |
address_2 update | string | The emergency location address line 2. |
city update | string | The emergency location city. |
country_code update | string | The ISO 3166-1 alpha-3 code of this emergency location country. |
state update | string | The emergency location state in a two-letter abbreviation format. |
zip update | string | The emergency location zip code. |
Get DID Emergency
GET /phonenumber/dids/{did_sid}/emergency
Returns DID Emergency object for the DID, targeted by secure ID
curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/dids/0493d917-e23c-41db-8067-0c986df71007/emergency' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the DID Emergency object
{
"caller_name": "John Smith",
"enabled": true,
"locations": [
{
"address_1": "8104 E Nora Ave",
"address_2": "",
"city": "Spokane Valley",
"country_code": "USA",
"state": "WA",
"zip": "99212"
},
{
"address_1": "600 Boll Weevil Cir",
"address_2": "",
"city": "Enterprise",
"country_code": "USA",
"state": "AL",
"zip": "36330"
}
]
}
This request returns data for DID emergency, targeted by the DID secure ID.
GET | /phonenumber/dids/{did_sid}/emergency |
This request is enabled for Field Filtering.
Required Scopes
To get information about DID Emergency objects, the partner must have one of the following scopes enabled:
phonenumber.emergency.manage
phonenumber.emergency.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
did_sid required | string | The DID secure ID. |
Update DID Emergency
PATCH /phonenumber/dids/{did_sid}/emergency
Updates the DID Emergency object, targeted by the DID secure ID, with the values in the request body
curl -X PATCH \
'https://api.carrierx.com/core/v2/phonenumber/dids/0493d917-e23c-41db-8067-0c986df71007/emergency' \
-H 'Content-Type: application/json' \
--data-binary '{"caller_name": "J Smith"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the updated DID Emergency object
{
"caller_name": "J Smith",
"enabled": true,
"locations": [
{
"address_1": "8104 E Nora Ave",
"address_2": "",
"city": "Spokane Valley",
"country_code": "USA",
"state": "WA",
"zip": "99212"
},
{
"address_1": "600 Boll Weevil Cir",
"address_2": "",
"city": "Enterprise",
"country_code": "USA",
"state": "AL",
"zip": "36330"
}
]
}
This request updates a DID emergency, targeted by the DID secure ID.
PATCH | /phonenumber/dids/{did_sid}/emergency |
PUT | /phonenumber/dids/{did_sid}/emergency |
A DID Emergency object can be updated using either a PATCH
or PUT
request.
-
A
PATCH
request can be used to update one or more attribute values. When using aPATCH
request, only the attributes specified in the request payload will be updated, all other attributes and values will remain the same. The DID emergency secure ID is passed in the query URL, and the values to be modified are passed in the request body. -
A
PUT
request can be used to update an entire DID Emergency object. The DID emergency secure ID is passed in the query URL, and the entire DID Emergency object is passed in the request body.
Required Scopes
To update a DID Emergency object, the partner must have the following scope enabled:
phonenumber.emergency.manage
Path Arguments
Parameter | Data Type | Description |
---|---|---|
did_sid required | string | The DID secure ID. |
Body Arguments
JSON representation of the fields and values to be updated.
All fields can be updated.
Refer to this table to view all fields that appear in the DID Emergency object.
Delete DID Emergency
DELETE /phonenumber/dids/{did_sid}/emergency
Deletes a DID emergency, targeted by the DID secure ID
curl -X DELETE \
'https://api.carrierx.com/core/v2/phonenumber/dids/0493d917-e23c-41db-8067-0c986df71007/emergency' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
204
status code with an empty body
This request deletes DID Emergency from a specific DID.
DELETE | /phonenumber/dids/{did_sid}/emergency |
Required Scopes
To delete a DID Emergency object, the partner must have the following scope enabled:
phonenumber.emergency.manage
Path Arguments
Parameter | Data Type | Description |
---|---|---|
did_sid required | string | The secure ID of the DID with the emergency that is to be deleted. |
DID Line Information Object
This section goes over the parts of the Line Information object. These fields and values make up the JSON response that gets returned when a request is successful.
Sample DID Line Information object
{
"caller_name": "John Smith",
"class_of_service": "business",
"enabled": true,
"extended_business_name": "J Smith Carpenter",
"extended_first_name": "John",
"extended_last_name": "Smith",
"privacy": "public",
"screening": "allow_all"
}
Attribute | Data Type | Description |
---|---|---|
caller_name update | string | The name that will appear on receiving party phones. |
class_of_service update | string | The type of establishment that the service is for. Values accepted in this field are:
none . |
enabled update | boolean | If this field is set to false , no record is stored in the central CNAM registry. Fields can still be updated when the value is false . |
extended_business_name update | string | The business name associated with the caller. This extended information is given according to the provider and phone device. |
extended_first_name update | string | The first name of the caller. This extended information is given according to the provider and phone device. |
extended_last_name update | string | The last name of the caller. This extended information is given according to the provider and phone device. |
privacy update | string | Either public or private . This is whether or not the caller name will be displayed. The default is public . |
screening update | string | Determines what types of calls are accepted. Values accepted in this field are:
block_third_number_collect . |
Get DID Line Information
GET /phonenumber/dids/{did_sid}/line_information
Returns DID Line Information object for the DID, targeted by secure ID
curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/dids/0493d917-e23c-41db-8067-0c986df71007/line_information' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the DID Line Information object
{
"caller_name": "John Smith",
"class_of_service": "business",
"enabled": true,
"extended_business_name": "J Smith Carpenter",
"extended_first_name": "John",
"extended_last_name": "Smith",
"privacy": "public",
"screening": "allow_all"
}
This request returns data for DID line information.
GET | /phonenumber/dids/{did_sid}/line_information |
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Required Scopes
To get information about DID Line Information objects, the partner must have one of the following scopes enabled:
phonenumber.line_information.manage
phonenumber.line_information.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
did_sid required | string | The DID secure ID. |
Update DID Line Information
PATCH /phonenumber/dids/{did_sid}/line_information
Updates the DID Line Information object, targeted by the DID secure ID, with the values in the request body
curl -X PATCH \
'https://api.carrierx.com/core/v2/phonenumber/dids/0493d917-e23c-41db-8067-0c986df71007/line_information' \
-H 'Content-Type: application/json' \
--data-binary '{"caller_name": "J Smith"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the updated DID Line Information object
{
"caller_name": "J Smith",
"class_of_service": "business",
"enabled": true,
"extended_business_name": "J Smith Carpenter",
"extended_first_name": "John",
"extended_last_name": "Smith",
"privacy": "public",
"screening": "allow_all"
}
This request updates a DID line information, targeted by the DID secure ID.
PATCH | /phonenumber/dids/{did_sid}/line_information |
PUT | /phonenumber/dids/{did_sid}/line_information |
A DID Line Information object can be updated using either a PATCH
or PUT
request.
-
A
PATCH
request can be used to update one or more attribute values. When using aPATCH
request, only the attributes specified in the request payload will be updated, all other attributes and values will remain the same. The DID line information secure ID is passed in the query URL, and the values to be modified are passed in the request body. -
A
PUT
request can be used to update an entire DID Line Information object. The DID line information secure ID is passed in the query URL, and the entire DID Line Information object is passed in the request body.
Required Scopes
To update a DID Line Information object, the partner must have the following scope enabled:
phonenumber.line_information.manage
Path Arguments
Parameter | Data Type | Description |
---|---|---|
did_sid required | string | The DID secure ID. |
Body Arguments
JSON representation of the fields and values to be updated.
All fields can be updated.
Refer to this table to view all fields that appear in the DID Line Information object.
Delete DID Line Information
DELETE /phonenumber/dids/{did_sid}/line_information
Deletes a DID line information, targeted by the DID secure ID
curl -X DELETE \
'https://api.carrierx.com/core/v2/phonenumber/dids/0493d917-e23c-41db-8067-0c986df71007/line_information' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
204
status code with an empty body
This request deletes DID line information from a specific DID.
DELETE | /phonenumber/dids/{did_sid}/line_information |
Required Scopes
To delete a DID Line Information object, the partner must have the following scope enabled:
phonenumber.line_information.manage
Path Arguments
Parameter | Data Type | Description |
---|---|---|
did_sid required | string | The secure ID of the DID with the line information that is to be deleted. |
DID Group Object
This section goes over the parts of the DID Group object. These fields and values make up the JSON response that gets returned when a request is successful.
The following fields appear in an items
object.
Sample DID Group object
{
"callback_url": null,
"did_group_sid": "41e21049-e5eb-433c-a93d-d57417b1863c",
"name": "N/A",
"partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f"
}
Attribute | Data Type | Description |
---|---|---|
callback_url create update | string | The callback URL to receive events for SMS. |
did_group_sid read only | string | The DID group secure ID. |
name create update | string | The name of the DID group. |
partner read only | object | The Partner object associated with the DID group. This field is displayed if with_related is set to true when performing the GET queries. |
partner_sid read only | string | The secure ID of the partner associated with the DID group. |
Create DID Group
POST /phonenumber/did_groups
Creates a DID Group
curl -X POST \
'https://api.carrierx.com/core/v2/phonenumber/did_groups' \
-H 'Content-Type: application/json' \
--data-binary '{}'
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the DID Group object
{
"callback_url": null,
"did_group_sid": "41e21049-e5eb-433c-a93d-d57417b1863c",
"name": "N/A",
"partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f"
}
This request creates a DID group.
POST | /phonenumber/did_groups |
Required Scopes
To create a DID Group object, the partner must have one of the following scopes enabled:
phonenumber.manage
phonenumber.create
Body Arguments
JSON representation of the fields and values of the DID Group object to be created.
No fields are required to create a DID group, an empty object can be passed.
Refer to this table to view all fields that appear in the DID Group object.
Get DID Groups
GET /phonenumber/did_groups
Returns DID groups matching the criteria in the request URL
curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/did_groups?limit=1' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a list of DID Group objects
{
"count": 1,
"has_more": true,
"items": [
{
"callback_url": null,
"did_group_sid": "41e21049-e5eb-433c-a93d-d57417b1863c",
"name": "N/A",
"partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f"
}
],
"limit": 1,
"offset": 0,
"pagination": {
"next": "https://api.carrierx.com/core/v2/phonenumber/did_groups?limit=1&offset=1"
},
"total": 2
}
This request returns a list of DID groups.
GET | /phonenumber/did_groups |
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Required Scopes
To get information about DID Group objects, the partner must have one of the following scopes enabled:
phonenumber.manage
phonenumber.read
Query Arguments
Parameter | Data Type | Description |
---|---|---|
with_related | boolean | Determines if the partner information related to the DID group should be shown. Values accepted in this field are true and false . The default value is false . |
Get DID Group by SID
GET /phonenumber/did_groups/{did_group_sid}
Returns a DID Group, targeted by secure ID
curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/did_groups/41e21049-e5eb-433c-a93d-d57417b1863c' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the DID Group object
{
"callback_url": null,
"did_group_sid": "41e21049-e5eb-433c-a93d-d57417b1863c",
"name": "N/A",
"partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f"
}
This request returns data for a DID group, targeted by secure ID.
GET | /phonenumber/did_groups/{did_group_sid} |
This request is enabled for Field Filtering.
Required Scopes
To get information about a DID Group object, the partner must have one of the following scopes enabled:
phonenumber.manage
phonenumber.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
did_group_sid required | string | The secure ID of the DID group. |
Query Arguments
Parameter | Data Type | Description |
---|---|---|
with_related | boolean | Determines if the partner information related to the DID group should be shown. Values accepted in this field are true and false . The default value is false . |
Update DID Group
PATCH /phonenumber/did_groups/{did_group_sid}
Updates the DID Group object, targeted by secure ID, with the values in the request body
curl -X PATCH \
'https://api.carrierx.com/core/v2/phonenumber/did_groups/41e21049-e5eb-433c-a93d-d57417b1863c' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"my_did_group"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the updated DID Group object
{
"callback_url": null,
"did_group_sid": "41e21049-e5eb-433c-a93d-d57417b1863c",
"name": "my_did_group",
"partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f"
}
This request updates a DID group, targeted by secure ID.
PATCH | /phonenumber/did_groups/{did_group_sid} |
PUT | /phonenumber/did_groups/{did_group_sid} |
A DID group object can be updated using either a PATCH
or PUT
request.
-
A
PATCH
request can be used to update one or more attribute values. When using aPATCH
request, only the attributes specified in the request payload will be updated, all other attributes and values will remain the same. The DID group secure ID is passed in the query URL, and the values to be modified are passed in the request body. -
A
PUT
request can be used to update an entire DID group object. The DID group secure ID is passed in the query URL, and the entire DID group object is passed in the request body.
Required Scopes
To update a DID group object, the partner must have one of the following scopes enabled:
phonenumber.manage
phonenumber.update
Path Arguments
Parameter | Data Type | Description |
---|---|---|
did_group_sid required | string | The DID group secure ID. |
Body Arguments
JSON representation of the fields and values to be updated.
Fields that can be modified are:
callback_url
name
Refer to this table to view all fields that appear in the DID group object.
Delete DID Group
DELETE /phonenumber/did_groups/{did_group_sid}
Deletes a DID group, targeted by secure ID
curl -X DELETE \
'https://api.carrierx.com/core/v2/phonenumber/did_groups/41e21049-e5eb-433c-a93d-d57417b1863c' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
204
status code with an empty body
This request deletes a DID group, targeted by secure ID.
DELETE | /phonenumber/did_groups/{did_group_sid} |
Required Scopes
To delete a DID Group object, the partner must have one of the following scopes enabled:
phonenumber.manage
phonenumber.delete
Path Arguments
Parameter | Data Type | Description |
---|---|---|
did_group_sid required | string | The secure ID of the DID group to be deleted. |
Prefix Object
This section outlines the Prefix object. The fields listed in the table below will be returned in a JSON object when a successful request has been made.
Sample Prefix object
{
"attributes": {},
"callback_url": null,
"lrn_sid": null,
"name": "N/A",
"partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
"prefix": "51625",
"prefix_sid": "cc367acb-94c8-418f-b247-85dce5806ef4",
"source_trunk_group_sid": null,
"string_key_1": null,
"string_key_2": null,
"transformations": [],
"trunk_group_sid": null
}
Attribute | Data Type | Description |
---|---|---|
attributes create update | object | The prefix attributes. |
callback_url create update | string | The callback URL. |
lrn_sid read only | string | The secure ID of the Location Routing Number assigned to this prefix. |
name create update | string | The prefix name. The default value is N/A . |
partner_sid create update | string | The secure ID of the partner associated with the prefix. |
prefix create update | string | The prefix that will enable the routing logic. |
prefix_sid read only | string | The prefix secure ID. |
source_trunk_group_sid create update | string | The prefix source trunk group secure ID. |
string_key_1 create update | string | A user-defined string key. |
string_key_2 create update | string | A user-defined string key. |
transformations create update | array | The prefix transformations. |
trunk_group_sid create update | string | The trunk group secure ID. |
Create Prefix
POST /phonenumber/prefixes
Creates a prefix
curl -X POST \
'https://api.carrierx.com/core/v2/phonenumber/prefixes' \
-H 'Content-Type: application/json' \
--data-binary '{"prefix":"51625"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the Prefix object
{
"attributes": {},
"callback_url": null,
"lrn_sid": null,
"name": "N/A",
"partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
"prefix": "51625",
"prefix_sid": "cc367acb-94c8-418f-b247-85dce5806ef4",
"source_trunk_group_sid": null,
"string_key_1": null,
"string_key_2": null,
"transformations": [],
"trunk_group_sid": null
}
This request creates a Prefix object.
POST | /phonenumber/prefixes |
Required Scopes
To create a Prefix object, the partner must have one of the following scopes enabled:
phonenumber.manage
phonenumber.create
Body Arguments
JSON representation of the fields and values of the Prefix object to be created.
A required field to create a prefix is prefix
.
Refer to this table to view all fields that appear in the prefix object.
Get Prefixes
GET /phonenumber/prefixes
Returns prefixes matching the criteria in the request URL
curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/prefixes' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a list of Prefix objects
{
"count": 1,
"has_more": false,
"items": [
{
"attributes": {},
"callback_url": null,
"lrn_sid": null,
"name": "N/A",
"partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
"prefix": "51625",
"prefix_sid": "cc367acb-94c8-418f-b247-85dce5806ef4",
"string_key_1": null,
"string_key_2": null,
"source_trunk_group_sid": null,
"transformations": [],
"trunk_group_sid": null
}
],
"limit": 10,
"offset": 0,
"pagination": {},
"total": 1
}
This request returns a list of Prefix objects.
GET | /phonenumber/prefixes |
This request is enabled for Pagination, Result Filtering, and Field Filtering.
Required Scopes
To get information about Prefix objects, the partner must have one of the following scopes enabled:
phonenumber.manage
phonenumber.read
Query Arguments
Parameter | Data Type | Description |
---|---|---|
with_related | boolean | Determines if the partner information related to the prefix should be shown. Values accepted in this field are true and false . The default value is false . |
Get Prefix by SID
GET /phonenumber/prefixes/{prefix_sid}
Returns a prefix, targeted by a secure ID
curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/prefixes/cc367acb-94c8-418f-b247-85dce5806ef4' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the Prefix object
{
"attributes": {},
"callback_url": null,
"lrn_sid": null,
"name": "N/A",
"partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
"prefix": "51625",
"prefix_sid": "cc367acb-94c8-418f-b247-85dce5806ef4",
"source_trunk_group_sid": null,
"string_key_1": null,
"string_key_2": null,
"transformations": [],
"trunk_group_sid": null
}
This request returns data for a prefix, targeted by a secure ID.
GET | /phonenumber/prefixes/{prefix_sid} |
This request is enabled for Field Filtering.
Required Scopes
To get information about a Prefix object, the partner must have one of the following scopes enabled:
phonenumber.manage
phonenumber.read
Path Arguments
Parameter | Data Type | Description |
---|---|---|
prefix_sid required | string | The prefix secure ID. |
Query Arguments
Parameter | Data Type | Description |
---|---|---|
with_related | boolean | Determines if the partner information related to the prefix should be shown. Values accepted in this field are true and false . The default value is false . |
Update Prefix
PATCH /phonenumber/prefixes/{prefix_sid}
Updates the Prefix object, targeted by a secure ID, with the values in the request body
curl -X PATCH \
'https://api.carrierx.com/core/v2/phonenumber/prefixes/cc367acb-94c8-418f-b247-85dce5806ef4' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"main prefix"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
200
status code with a serialized copy of the updated Prefix object
{
"attributes": {},
"callback_url": null,
"lrn_sid": null,
"name": "main prefix",
"partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
"prefix": "51625",
"prefix_sid": "cc367acb-94c8-418f-b247-85dce5806ef4",
"source_trunk_group_sid": null,
"string_key_1": null,
"string_key_2": null,
"transformations": [],
"trunk_group_sid": null
}
This request updates a prefix, targeted by a secure ID.
PATCH | /phonenumber/prefixes/{prefix_sid} |
PUT | /phonenumber/prefixes/{prefix_sid} |
A Prefix object can be updated using either a PATCH
or PUT
request.
-
A
PATCH
request can be used to update one or more attribute values. When using aPATCH
request, only the attributes specified in the request payload will be updated, all other attributes and values will remain the same. The prefix secure ID is passed in the query URL, and the values to be modified are passed in the request body.The Prefix object also contains nested Attributes and Transformations objects. Refer to this section to learn how nested objects can be updated using the
PATCH
request. -
A
PUT
request can be used to update an entire Prefix object. The prefix secure ID is passed in the query URL, and the entire Prefix object is passed in the request body.
Required Scopes
To update a Prefix object, the partner must have one of the following scopes enabled:
phonenumber.manage
phonenumber.update
Path Arguments
Parameter | Data Type | Description |
---|---|---|
prefix_sid required | string | The prefix secure ID. |
Query Arguments
Parameter | Data Type | Description |
---|---|---|
nested_objects | string | Determines if the nested objects fields and values should be replaced. Value accepted in this field is replace . |
Body Arguments
JSON representation of the fields and values to be updated.
Fields that can be modified are:
attributes
callback_url
name
prefix
source_trunk_group_sid
string_key_1
string_key_2
transformations
Refer to this table to view all fields that appear in the Prefix object.
Delete Prefix
DELETE /phonenumber/prefixes/{prefix_sid}
Deletes a prefix, targeted by a secure ID
curl -X DELETE \
'https://api.carrierx.com/core/v2/phonenumber/prefixes/cc367acb-94c8-418f-b247-85dce5806ef4' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Response
204
status code with an empty body
This request deletes a prefix, targeted by a secure ID.
DELETE | /phonenumber/prefixes/{prefix_sid} |
Required Scopes
To delete a Prefix object, the partner must have one of the following scopes enabled:
phonenumber.manage
phonenumber.delete
Path Arguments
Parameter | Data Type | Description |
---|---|---|
prefix_sid required | string | The secure ID of the prefix. |
LRN Prefix Object
This section outlines the LRN Prefix object. The fields listed in the table below will be returned in a JSON object when a successful request has been made.
Sample LRN Prefix object
{
"attributes": {},
"callback_url": null,
"lrn_prefix_sid": "cea69d91-8db6-27b5-a3b2-d6a4d8b62573",
"lrn_sid": null,
"name": "lrn_prefix_name",
"partner_sid": " e00430c3-a7d0-4666-ab5c-f7202448382f ",
"prefix": "1520",
"source_trunk_group_sid": null,
"string_key_1": "",
"string_key_2": "",
"transformations": [],
"trunk_group_sid": null,
}
Attribute | Data Type | Description |
---|---|---|
attributes create update |