Version 1 of VoIP API

API and Control Panel URLs

We advise you to have those URLs as variables in your code so you can easily switch test and production environments.

Have in mind that everything you do on the sandbox API will be visible on the sandbox Control Panel and the same for the live API.
Both environments are currently not connected in any way, so you have to get a new X-API-KEY, add your IP addresses, create Accounts, Custom Packages, Billing Profiles, etc.
Let us know if we can help you migrating something form the sandbox to the production environment.


http://sandbox.chainsolutions.net/voip/v1 - address of the sandbox API

http://cptest.chainsolutions.net/ - address of the sandbox Control Panel


https://vapi.chainsolutions.net/voip/v1 - address of the live API

https://cp.chainsolutions.net/ - address of the live Control Panel

Please note - you need to manually request an API key from the Control Panel (unless we sent it to you via email). After that you can get API keys for your clients using the API Key POST method

Also note that the production API only accepts requests over https.

URL Formatting

This is how the URL formatting is done for all API functions. You can try it directly in your browser for GET methods

Lets look at this function for example: System Package GET

http://sandbox.chainsolutions.net/voip/v1/system_package/X-API-KEY/##########/sys_package_id/10/format/json

http://sandbox.chainsolutions.net/voip/v1 - address of the sandbox API

system_package - function name

X-API-KEY, sys_package_id - parameter names (note X-API-KEY is ALWAYS a required parameter for all API functions)

##########, 10 - values of the parameters above, meaning X-API-KEY = ########## and sys_package_id = 10

format/json - the default (meaning you can omit it form the URL) and preferable response format we advise you to use with our API

Supported Response Formats

format/json - the default (if you omit the 'format' variable) and preferable response format. We advise you to use it with our API

format/html - used when using a browser to display API results. Not suitable for all functions as it displays properly only two dimensional arrays

format/xml - we advice you to NOT USE XML format as json is much better and universal. Please note we won't support any requests you make giving us XML request/response examples

Function Signature

All functions have the same response signature. Some may have additional elements, but those below are consistent.

{
  "status":"success",
  "message":"Custom response message depending on function",
  "data":{},
  "request_id":"int(11)"
}
                  
status - can be either "success" when the function executed correctly or "error" when there was a problem

message - custom response message giving you more details about how the method executed, and if not - why

data - it can either be null (with successful POST, PUT and DELETE methods) or array depending on the method. All GET methods entries will be in this array. Also if there is an error you can find the "error_code" in this array

request_id - this is the ID of the current API Request you are making. Please provide this 'request_id' to our Support or Development departments

You can have a look at this method for example: Call History GET

Input and Output Parameter Types

Throughout the documentation you will see purple characters like varchar(255), int(11), datetime, link and more.

Those types with little exceptions come directly from MySQL, so if you are familiar with it you will get it straight away. The idea is for you to easily design your local database with the proper fields and their lengths.

Example Variable Type Description
varchar(20) string string with a certain max length - in this case 20
int(11) integer, a whole number integer with a certain max length - in this case 11
decimal(10,5) decimal, float, double decimal with a certain max length before the decimal point - 10, and a max length after the decimal point - 5
datetime DateTime A textual representation of a date and time, in this API the format is PHP - date(Y-m-d H:i:s) or in general (YYYY-MM-DD HH:MM:SS)
date Date A textual representation of a date, in this API the format is PHP - date(Y-m-d) or in general (YYYY-MM-DD)
text long string (generally more than 255 characters) This means that you should expect a large string to be returned. This is not always the case, of course, but should be expected
link a string that contains a link to API resource A standard link, example: http://sandbox.chainsolutions.net/voip/v1/timezones/timezone_id/10

Pagination

Most of our GET methods support pagination (you don't need it on POST, PUT and DELETE as there is no "data" to return). This helps you get and render results faster in your own application - you can imagine that loading 10000 elements at once is not a good idea.

To use it you should pass those two optional parameters:

offset - which element you want to start the pagination after

limit - (always optional - default is 50) how many records do you want to display per page.


Example response:

{
  "status":"success",
  "message":"Pagination retrieved successfully!",
  "data":{
    // data for 50 elements
  },
  "pagination":{
    "offset":"50",
    "limit":"50",
    "total_records":"345",
    "total_pages":"7"
  }
}
                  

You can have a look at this method for example: Call History GET

User Messages

If you intend to display the messages returned form our API directly to users it is a good idea to ask us to enable this feature for you.

Once enabled you will receive an additional parameter 'user_message' with a user friendly message you can display directly to your customers.


Example response:

{
  "status":"success",
  "message":"\'did_id\' not present in DB!",
  "user_message":"There was a problem with the DID number passed",
  "data":null
}
                  

Response HTTP status codes

If our servers respond successfully to your request (even if there is any kind of validation, permission or other error) it will be with a 200 OK HTTP response.

The idea behind that is instead of using HTTP as a 'state' protocol we use the response body for this - in every response there are a "status", "message" and "data" fields you need to look for and "error_code" field if there is an error.

This means you don't need to worry about the HTTP response - just build your application based on the concept of parsing our JSON responses.


Error Codes

When the "status" filed in a response has a value of "error", you will also receive an additional field called "error_code". Please also note, that on all errors there still is a "data" element, but it always equals null

Here is an example error response:

{
  "status":"error",
  "error_code":"400",
  "message":"An elaborate message telling you exactly why this error occurred",
  "data":null
}
Here is a table of our error codes and their general meaning.

Error Code Meaning Description
400 Bad Request This error generally means that a parameter was not passed or it has a value that is not expected (the function cannot work with such a value)
401 Unauthorized You don't have sufficient permissions to execute this request with the parameters passed. Generally associated with 'accountcode' parameters and resellers trying to modify client accounts without permission
403 Forbidden The request was a valid request, but the server is refusing to respond to it. Unlike a 401 Unauthorized response, authenticating will make no difference.
404 Not Found A parameter you passed does not match our database records. This means that the parameters are the right type and names, but not the right values (example - you are passing and 'id' of '4' where you don't own it or it does not exists)
405 Method Not Allowed When an HTTP method is being requested that isn't allowed for the authenticated user.
410 Gone Indicates that the resource at this end point is no longer available. Useful as a blanket response for old API versions.
415 Unsupported Media Type If incorrect content type was provided as part of the request.
422 Unprocessable Entity Used for validation errors
429 Too Many Requests When a request is rejected due to rate limiting
500 Internal Server Error Error message meaning the problem is on our side. Please contact us if this problem persists!

API Glossary (beta)

Here you can find links and references to the terms and concepts used in our API.

Term Related API methods Description
Account Account DELETE, Account GET, Account POST, Account PUT Every API User, it being a Client or Reseller has an Account with us. Without an account they cannot use any of our services. Accounts are identified throughout the API with a unique 10 digit 'accountcode', returned on account creation
Account Status Account Statuses GET, , Account GET, Account POST, Account PUT Accounts can have different 'status'-es in our system. You can assign a new status on an account when they have not paid their monthly tax, when they have to confirm their email, etc
API Key (X-API-KEY) Every method in this API Every Account can have an API Key (X-API-KEY) assoiciated with it. The API key itself is a random string of 40 characters and numbers and can be generated trough our Control Panel or with API Key POST for your clients. Every API method expects you to pass this parameter and if you don't - an error with error code '401' will be presented. In most methods if you don't pass an accountcode variable this means the action this method makes will be made on the account that is associated with this X-API-KEY.
Dial Prefix User Extension POST, User Extension PUT, User Extension GET, User Extension DELETE You can add a Dial Prefix to a User Extension so you don't have to dial a country code (for example) every time you dial manually from your phone. Just add '0044' as a Dial Prefix and reduce your work when dialing a UK numbers campaign!
Pin Code User Extension POST, User Extension PUT, User Extension GET, User Extension DELETE A Pin Code is a 1-4 digit number that you use to log into a SIP Device with your User Extension. This way you can use any SIP Phone on our network with a particular User Extension.
Recording Enabled User Extension POST, User Extension PUT, User Extension GET, User Extension DELETE If you have enabled this on an User Extension or a Click to Call, every inbound or outbound call will create a Recording, that you can download or just listen to from the Control Panel
Reseller This is an Account that has 'child' accounts associated with it. Resellers make commision on every action their 'child' Accounts make. Every Account you create using the Account POST is considered a 'child' account to your own Account. However in order to become a Reseller you may need to sign an additional Contract with us.
SIP Device SIP Device POST, SIP Device GET, SIP Device PUT, SIP Device DELETE Those are devices that use the Session Initiation Protocol for voice an video communication. You can currently add SIP phones, cameras and softphones.
User Extension User Extension POST, User Extension PUT, User Extension GET, User Extension DELETE A User Extension is a number internal to our network that you use to map to a SIP Device. Once mapped whenever you ring this Extension from our network this SIP phone will ring. You can configure a lot of options for an Extension: Pin Code, Dial Prefix, Recording Enabled or Present Caller ID
copyright 2014 Chain Solutions
namespace VoIP
link Public Website
link API Documentation
version 1.0

 Methods

API Key DELETE

API

Delete yours or your client's API Key. Please note that if you delete yours (not passing accountcode) you will have to get a new one from our Control Panel as you won't be able to make any requests to our API

api curl -k -i -H "Accept: application/json" -X DELETE -d "X-API-KEY=########&accountcode=########&x_api_key_id=###" http://sandbox.chainsolutions.net/voip/v1/api_key

Parameters

$accountcode

string

varchar(20) (optional) Your client's accountcode for whom you want to edit an X-API-KEY

$x_api_key_id

int

int(11)

Exceptions

array {"status":"error","error_code":"400","message":"accountcode must be set","data":null}
array {"status":"error","error_code":"400","message":"x_api_key_id must be set","data":null}
array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"The x_api_key_id you provided does not belong to this accountcode!","data":null}
array {"status":"error","error_code":"500","message":"Could not delete X-API-KEY at this moment!","data":null}

Returns

array{"status":"success","message":"API Key deleted successfully","data":null}

API Key GET

API

Get the X-API-KEY for a client of yours. Your client should have let you modify their account settings.

api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=########&accountcode=########" http://sandbox.chainsolutions.net/voip/v1/api_key

Parameters

$accountcode

string

varchar(20) Your client's accountcode for whom you want to get the X-API-KEY

Exceptions

array {"status":"error","error_code":"400","message":"accountcode must be set","data":null}
array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"Your client does not have an X-API-KEY yet!","data":null}

Returns

array{"status":"success","message":"API Key retrieved successfully","data":{"x_api_key":"varchar(40)","x_api_key_id":"int(11)"}}

API Key POST

API

Request an API key for a client of yours. This way they can make API calls. Your client should have let you modify their account settings.

api curl -k -i -H "Accept: application/json" -X POST -d "X-API-KEY=########&accountcode=########" http://sandbox.chainsolutions.net/voip/v1/api_key

Parameters

$accountcode

string

varchar(20) Your client's accountcode for whom you want to create an X-API-KEY

Exceptions

array {"status":"error","error_code":"400","message":"accountcode must be set","data":null}
array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"Selected client already has an X-API-KEY! Please delete the old one first!","data":null}
array {"status":"error","error_code":"500","message":"Could not generate X-API-KEY at this moment!","data":null}

Returns

array{"status":"success","message":"API key created successfully","data":{"x_api_key":"varchar(40)","x_api_key_id":"int(11)"}}

Billing Invoice GET

API

Get all or a single invoice related to an account

api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=##########&accountcode=########&invoice_no=########" http://sandbox.chainsolutions.net/voip/v1/billing_invoice

Parameters

$accountcode

string

varchar(20)

$invoice_no

string

varchar(20) (optional) get the details of a single invoice

$start_date

string

varchar(20) (optional) Parameter should be passes in one of those formats: 'YYYY-MM-DD hh:mm:ss', example: '2012-02-28 12:12:12' OR 'YYYY-MM-DD', example: '2012-02-28'

$end_date

string

varchar(20) (optional) Parameter should be passes in one of those formats: 'YYYY-MM-DD hh:mm:ss', example: '2012-02-28 12:12:12' OR 'YYYY-MM-DD', example: '2012-02-28'

Exceptions

array {"status":"error","error_code":"400","message":"accountcode must be set","data":null}
array {"status":"error","error_code":"400","message":"invoice_no you passed is not valid!","data":null}
array {"status":"error","error_code":"403","message":"User deleted/inactive or insufficient permissions!","data":null}

Returns

array{"status":"success","message":"Billing Invoices retrieved successfully","data":[{"invoice_no":"varchar(20)","date":"datetime","paid_status":"int(2)","title":"varchar(100)","description":"varchar(255)","vat":"decimal(3,2)","price":"decimal(10,5)","price_eur":"decimal(10,5)","total":"decimal(10,5)","currency":"varchar(3)","exchange_rate":"decimal(10,5)","items":[{"price":"decimal(10,5)","description":"varchar(255)"}]}]}
array{"status":"success","message":"No Billing Invoices found for selected Account","data":null}

Billing Payment POST

API

Create a Billing Payment for a specific reason. Successful Billing Payment creates an Invoice
From this method you can also add Call Credit to your account

api curl -k -i -H "Accept: application/json" -X POST -d "X-API-KEY=##########&accountcode=#######&amount=10.00&reference=payment&description=billing" http://sandbox.chainsolutions.net/voip/v1/billing_payment

Parameters

$accountcode

string

varchar(20) (optional)

$amount

float

decimal(10,4) This is in the current Account Currency. The total amount of the transaction, including tax, shipping and everything else

$currency

float

varchar(3) (optional) (default is the currency of the Account) Set the currency of passed 'amount' and items 'price' values. Get a full Currency list from Currencies GET method

$card_code

int

int(4) (optional) the bank card CVV code - 3 to 4 digits, applicable for some card types only (like VISA Electron)

$reference

string

varchar(30) the title of the transaction

$description

string

varchar(100) detailed transaction description

$items

array

array(decimal(10,4) 'price', varchar(100) 'description') (optional) if the transaction consists of more than one item pass them with this signature

$call_credit

int

int(1) (optional) if $call_credit equals '1' the invoice amount will be added as Call Credit

Exceptions

array {"status":"error","error_code":"400","message":"accountcode must be set","data":null}
array {"status":"error","error_code":"400","message":"amount must be set","data":null}
array {"status":"error","error_code":"422","message":"amount must be a numeric value","data":null}
array {"status":"error","error_code":"400","message":"Please pass an amount larger than zero","data":null}
array {"status":"error","error_code":"400","message":"reference must be set","data":null}
array {"status":"error","error_code":"400","message":"description must be set","data":null}
array {"status":"error","error_code":"400","message":"items should be an array!","data":null}
array {"status":"error","error_code":"400","message":"items array does not have the right signature! Every 'item' should have 'price' and 'description' fields","data":null}
array {"status":"error","error_code":"422","message":"the 'price' of all your 'items' added together does not equal the 'amount' field value!","data":null}
array {"status":"error","error_code":"400","message":"You don't have enough Credit in your Reseller Account to cover this transaction! Please add more credit to your Reseller Account using Billing Payment POST and passing call_credit=1","data":{"current_credit":"decimal(10,5)","payment_amount":"decimal(10,5)","currency":"varchar(3)"}}
array {"status":"error","error_code":"403","message":"You don't have permissions to charge this account!","data":null}
array {"status":"error","error_code":"400","message":"User doesn't have a Billing Profile created yet! Please create one using the 'Billing Profile POST' method","data":null}
array {"status":"error","error_code":"500","message":"We could not successfully submit your transaction. Please try again","data":null}
array {"status":"error","error_code":"500","message":"There was a problem creating the invoice for your payment!","data":null}
array {"status":"error","error_code":"400","message":"The transaction was declined! Reason: ","data":null}
array {"status":"error","error_code":"403","message":"The transaction resulted in an error! Reason: ","data":null}
array {"status":"error","error_code":"500","message":"There was a problem connecting to the Billing Server! Please try again","data":null}

Returns

array{"status":"success","message":"Billing Payment created successfully","data":{"invoice_no":"varchar(20)","reseller_invoice_no":"varchar(20) return only when an additional invoice was issued on the Reseller Account"}}

Billing Profile DELETE

API

Delete user's Billing Profile(s) and all associated data.
This method will delete only the Billing Profile(s) of the Account in their Current Currency. If they have Billing Profile(s) in another currency they will not be deleted.

api curl -k -i -H "Accept: application/json" -X DELETE -d "X-API-KEY=############&accountcode=########" http://sandbox.chainsolutions.net/voip/v1/billing_profile

Parameters

$accountcode

string

varchar(20) (optional)

Exceptions

array {"status":"error","error_code":"400","message":"accountcode must be set","data":null}
array {"status":"error","error_code":"400","message":"Account doesn't have a Billing Profile in 'X'","data":null}
array {"status":"error","error_code":"403","message":"You don't have permissions to change this Accounts' details","data":null}
array {"status":"error","error_code":"500","message":"There was a problem deleting this Account's Billing Profile 'X'","data":null}
array {"status":"error","error_code":"500","message":"Error deleting Billing Profile data from database","data":null}

Returns

array{"status":"success","message":"Billing Profile deleted successfully","data":null}

Billing Profile GET

API

Get the Billing Profile (if it exists) related to an Account.
This method will retrieve only the Billing Profile in the current Account Currency.

api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=############&accountcode=########" http://sandbox.chainsolutions.net/voip/v1/billing_profile

Parameters

$accountcode

string

varchar(20) (optional)

Exceptions

array {"status":"error","error_code":"400","message":"accountcode must be set","data":null}
array {"status":"error","error_code":"400","message":"Account doesn't have a Billing Profile in 'X'!","data":null}
array {"status":"error","error_code":"400","message":"Account doesn't have a Billing Profile on the InFocus payment gateway. Please re-create their Billing Profile!","data":null}
array {"status":"error","error_code":"403","message":"You don't have permissions to view this Accounts' details","data":null}
array {"status":"error","error_code":"500","message":"There was a problem retrieving Billing Profile! 'X'","data":null}

Returns

array{"status":"success","message":"Billing Profile retrieved successfully","data":{"card_number":"varchar(8)","expiration_date":"varchar(20)","email":"varchar(70)","first_name":"varchar(100)","last_name":"varchar(100)","company_name":"varchar(100)","address":"varchar(255)","city":"varchar(100)","state":"varchar(100)","zip":"varchar(12)","country":"varchar(100)","phone_number":"varchar(20)"}}

Billing Profile POST

API

Create new Billing Profile for an Account in the current Account Currency. If currency is different than GBP, USD and EUR the profile will be crated in EUR and all payments will be converted to EUR
If the Account has a Billing Profile in another currency it will not be deleted, if they have one in the same Currency the old one will be replaced
If you don't provide some of the optional parameters (email, name, etc) those stored in user's Account will be used

api curl -k -i -H "Accept: application/json" -X POST -d "X-API-KEY=########&accountcode=########&address=some_address&city=City&state=State&zip=3231&country=USA&company_name=some_company&phone_number=123432423423&card_number=4111111111111111&expiration_date=2020-11&card_code=312" http://sandbox.chainsolutions.net/voip/v1/billing_profile

Parameters

$accountcode

string

varchar(20) (optional)

$address

string

varchar(255) (required for VISA payments)

$zip

string

varchar(12) (optional) (required for VISA payments) you can omit this if value is already set via the Account POST/PUT functions

$card_number

string

varchar(20) on the development environment you can use the following test cards:
American Express: 370000000000002
Discover: 6011000000000012
Visa: 4007000000027
Second Visa: 4012888818888
JCB: 3088000000000017
Diners Club/ Carte Blanche: 38000000000006
Master Card: 5555555555554444 or 5105105105105100

$expiration_date

string

varchar(20) (YYYY-MM format) on the development environment this just needs to be a valid date not in the past

$card_code

string

varchar(20) on the development environment you can pass any number here

$first_name

string

varchar(100) (optional) you can omit this if value is already set via the Account POST/PUT functions

$last_name

string

varchar(100) (optional) you can omit this if value is already set via the Account POST/PUT functions

$email

string

varchar(70) (optional) you can omit this if value is already set via the Account POST/PUT functions

$company_name

string

varchar(100) (optional) you can omit this if value is already set via the Account POST/PUT functions

$city

string

varchar(100) (optional) you can omit this if value is already set via the Account POST/PUT functions

$state

string

varchar(100) (optional) you can omit this if value is already set via the Account POST/PUT functions

$country

string

varchar(100) (optional) you can omit this if value is already set via the Account POST/PUT functions

$phone_number

string

varchar(20) (optional) you can omit this if value is already set via the Account POST/PUT functions

Exceptions

array {"status":"error","error_code":"400","message":"accountcode must be set","data":null}
array {"status":"error","error_code":"400","message":"card_number must be set","data":null}
array {"status":"error","error_code":"400","message":"expiration_date must be set","data":null}
array {"status":"error","error_code":"403","message":"You don't have permissions to change this Accounts' details","data":null}
array {"status":"error","error_code":"400","message":"There was a problem creating Customer Profile! 'X'","data":null}
array {"status":"error","error_code":"400","message":"There was a problem creating Customer Payment Profile! 'X'","data":null}
array {"status":"error","error_code":"500","message":"There was a problem deleting this Account's Billing Profile 'X'","data":null}
array {"status":"error","error_code":"500","message":"Error adding Billing Profile data to database","data":null}

Returns

array{"status":"error","message":"Billing Profile created successfully. Test transaction(s) will be issued on this Credit Card to verify it's validity","data":null}

Billing Profile PUT

API

Change the details stored in the Billing Profile. They are displayed when email notifications are received. You can pass only the variables you need changed - the rest will remain as you see them in Billing Profile GET

api curl -k -i -H "Accept: application/json" -X PUT -d "X-API-KEY=########&accountcode=########&address=some_address&city=City&state=State&zip=3231&country=USA&company_name=some_company&phone_number=123432423423&card_number=4111111111111111&expiration_date=2020-11&card_code=312" http://sandbox.chainsolutions.net/voip/v1/billing_profile

Parameters

$accountcode

string

varchar(20) (optional)

$address

string

varchar(255) (optional) (required for VISA payments) you can choose not to pass this variable if it is already set in the Billing Profile and does not need to be changed

$zip

string

varchar(12) (optional) (required for VISA payments) you can choose not to pass this variable if it is already set in the Billing Profile and does not need to be changed

$card_number

string

varchar(20) (optional) you can choose not to pass this variable if it is already set in the Billing Profile and does not need to be changed.
On the development environment you can use the following test cards:
American Express: 370000000000002
Discover: 6011000000000012
Visa: 4007000000027
Second Visa: 4012888818888
JCB: 3088000000000017
Diners Club/ Carte Blanche: 38000000000006
Master Card: 5555555555554444 or 5105105105105100

$expiration_date

string

varchar(20) (YYYY-MM format) (optional) on the development environment this just needs to be a valid date not in the past. You can choose not to pass this variable if it is already set in the Billing Profile and does not need to be changed

$card_code

string

varchar(20) (optional) on the development environment you can pass any number here

$first_name

string

varchar(100) (optional) you can choose not to pass this variable if it is already set in the Billing Profile and does not need to be changed

$last_name

string

varchar(100) (optional) you can choose not to pass this variable if it is already set in the Billing Profile and does not need to be changed

$email

string

varchar(70) (optional) you can choose not to pass this variable if it is already set in the Billing Profile and does not need to be changed

$company_name

string

varchar(100) (optional) you can choose not to pass this variable if it is already set in the Billing Profile and does not need to be changed

$city

string

varchar(100) (optional) you can choose not to pass this variable if it is already set in the Billing Profile and does not need to be changed

$state

string

varchar(100) (optional) you can choose not to pass this variable if it is already set in the Billing Profile and does not need to be changed

$country

string

varchar(100) (optional) you can choose not to pass this variable if it is already set in the Billing Profile and does not need to be changed

$phone_number

string

varchar(20) (optional) you can omit this if value is already in the Billing Profile and you don't want to change it

Exceptions

array {"status":"error","error_code":"403","message":"You don't have permissions to change this Accounts' details","data":null}
array {"status":"error","error_code":"400","message":"Please pass any parameters to this method","data":null}
array {"status":"error","error_code":"400","message":"There was a problem updating Customer Profile! X","data":null}
array {"status":"error","error_code":"400","message":"There was a problem updating Customer Payment Profile! X","data":null}

Returns

array{"status":"success","message":"Billing Profile updated successfully","data":null}

Billing Subscription DELETE

API

This will delete the Billing Subscription and all tokens associated with it. It will also make inactive all related services. This will also delete any DIDs associated with this Billing Subscription

api curl -k -i -H "Accept: application/json" -X DELETE -d "X-API-KEY=##############&billing_subscription_id=7" http://sandbox.chainsolutions.net/voip/v1/billing_subscription

Parameters

$billing_subscription_id

int

int(11)

$accountcode

string

varchar(20) (optional)

Exceptions

array {"status":"error","error_code":"400","message":"Wrong billing_subscription_id or it does not belong to selected Account!","data":null}
array {"status":"error","error_code":"400","message":"Your DID's Billing Subscription must be at least 3 months old! You cannot delete the Billing Subscription before that","data":null}

Returns

array{"status":"success","message":"Billing Subscription deleted successfully","data":null}

Billing Subscription GET

API

Get all Billing Subscriptions related to an Account.
The returned 'months' index indicates how often a Billing Subscription based on a Custom Package is being paid for. If 'months' = 1 than the Subscription is monthly. If it is '12' than the Subscription is yearly.
If you want to change the 'months' period for a particular System Package please contact us directly.

api http://sandbox.chainsolutions.net/voip/v1/billing_subscription/accountcode/########
api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=#########" http://sandbox.chainsolutions.net/voip/v1/billing_subscription

Parameters

$accountcode

string

varchar(20) (optional) get Billing Subscriptions for a client. If not passed your Reseller Account's Subscriptions will be retrieved

$billing_subscription_id

int

(optional) if you want to get info about a particular Billing Subscription

$offset

int

int(10) (optional) default is '0', which element to start the pagination from.

$limit

int

int(2) (optional) default and max is 20, how many records you want to display on a page.

Exceptions

array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"The 'billing_subscription_id' passed does not exist or belong to selected account","data":null}

Returns

array{"status":"success","message":"Billing Subscriptions retrieved successfully","data":{"billing_subscription_id":"int(11)","name":"varchar(45)","description":"varchar(200)","price":"decimal(10,5)","buy_eur":"decimal(10,5)","buy_reseller_currency":"decimal(10,5)","price_client_currency":"decimal(10,5) price in Reseller Currency, not coverted from EUR price","start_date":"datetime","active":"int(1)","last_modified":"datetime","last_payment":"datetime","months":"int(2)","extension_id":"int(11) returned only when 'billing_subscription_id' is passed and for Billing Subscriptions that have related User Extensions"}}
array{"status":"success","message":"No Billing Subscriptions found!","data":null}

Billing Subscription POST

API

Add new Billing Subscription to an Account

api curl -k -i -H "Accept: application/json" -X POST -d "X-API-KEY=############&accountcode=##########&custom_package_id=19&name=foo&description=bar&payment_type=2&sip_address=557203765@infocus.net" http://sandbox.chainsolutions.net/voip/v1/billing_subscription

Parameters

$custom_package_id

int

int(11) you can get this from Custom Package GET method

$accountcode

string

varchar(20) (optional)

$name

string

varchar(45) (optional) if not set the name of the related Custom Package will be used

$description

string

varchar(200) (optional) if not set the description of the related Custom Package will be used

$payment_type

int

int(1) (optional) default is '1' - pay for Billing Subscription with Call Credit, '2' - pay with Credit Card already registered and approved, client needs to have a Billing Profile

$sip_address

string

varchar(255) (optional) when creating a Billing Subscription that has included free minutes and needs to be connected to a SIP address, example: '557203765@infocus.net'

Exceptions

array {"status":"error","error_code":"400","message":"custom_package_id must be set","data":null}
array {"status":"error","error_code":"400","message":"accountcode must be set","data":null}
array {"status":"error","error_code":"400","message":"Please pay your Reseller Account's Billing Subscriptions with Call Credit, pass 'payment_type'='1' or don't pass it at all (this is the default value)","data":{"custom_package_id":"int(11)"}}
array {"status":"error","error_code":"400","message":"You don't have enough Credit in your Reseller Account to cover this transaction! Please add more credit to your Reseller Account using Billing Payment POST and passing call_credit=1","data":{"current_credit":"decimal(10,5)","payment_amount":"decimal(10,5)","currency":"varchar(3)"}}
array {"status":"error","error_code":"400","message":"Selected Account is InFocus client and cannot add Billing Subscriptions with Call Credit","data":null}}
array {"status":"error","error_code":"403","message":"Wrong custom_package_id or insufficient permissions!","data":null}
array {"status":"error","error_code":"403","message":"The corresponding System Package was deleted! Please contact us","data":null}
array {"status":"error","error_code":"500","message":"There was a problem creating an invoice for your subscription!","data":null}
array {"status":"error","error_code":"500","message":"There was a problem creating a Billing Subscription. Please try again later","data":null}

Returns

array{"status":"success","message":"Billing Subscription created successfully","data":{"billing_subscription_id":"int(11)","invoice_no":"varchar(20)","reseller_invoice_no":"varchar(20) return only when an additional invoice was issued on the Reseller Account","extension_id":"int(11) returned only when Custom Package needs to crate an User Extension"}}

Billing Subscription PUT

API

Edit existing Billing Subscription details

api curl -k -i -H "Accept: application/json" -X PUT -d "X-API-KEY=##############&billing_subscription_id=7&name=foooo&description=baaar" http://sandbox.chainsolutions.net/voip/v1/billing_subscription

Parameters

$billing_subscription_id

int

int(11)

$accountcode

string

varchar(20) (optional)

$name

string

varchar(45) (optional) new name for the Billing Subscription

$description

string

varchar(200) (optional) new description for the Billing Subscription

$update_price

string

int(1) (optional) if 'update_price' equals '1' the buy and sell prices of the subscription will be updated with the latest values coming from the related Custom and System Package

$sip_address

string

varchar(255) (optional) if the Billing Subscription has included free minutes and needs to be connected to a SIP address, example: '557203765@infocus.net'

$payment_type

int

int(1) '1' - pay for Billing Subscription with Call Credit, '2' - pay with Credit Card already registered and approved, client needs to have a Billing Profile

Exceptions

array {"status":"error","error_code":"400","message":"billing_subscription_id must be set","data":null}
array {"status":"error","error_code":"400","message":"Wrong billing_subscription_id or it does not belong to selected Account!","data":null}
array {"status":"error","error_code":"400","message":"We could not find an User Extension that is linked to this Billing Subscription! Maybe you are passing 'sip_address' for a Billing Subscription that is not linked to an Extension","data":null}
array {"status":"error","error_code":"400","message":"Selected Account does not have a Billing Profile created","data":null}
array {"status":"error","error_code":"500","message":"The corresponding Custom Package is no longer available. Please contact us directly to resolve this","data":null}
array {"status":"error","error_code":"500","message":"The corresponding System Package is no longer available. Please contact us directly to resolve this","data":null}
array {"status":"error","error_code":"400","message":"Please pass some parameters to update Billing Subscription","data":null}

Returns

array{"status":"success","message":"Billing Subscription updated successfully","data":null}

Call History Archive GET

API

Get inbound or outbound call details for a specific month for your account or that of a client.
The 'month' passed should be at least 2 months before the current month (basically all Call History before the beginning of the data returned from Call History GET method)
For example if today is 2014-04-04 the latest month you can get the Call History Archives for is 2014-02

api http://sandbox.chainsolutions.net/voip/v1/call_history_archive/month/2013-12
api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=########&direction=inbound&month=2013-12" http://sandbox.chainsolutions.net/voip/v1/call_history_archive

Parameters

$accountcode

string

varchar(20) (optional) If you want to view the Call History for a client of yours.

$direction

string

varchar(10) default is 'outbound'. Supported values are 'inbound', 'outbound', 'inbound_stats', 'outbound_stats' and 'stats'

$call_type

int

int(1) (optional) if not passed all Calls will be retrieved, pass '1' to retrieve only Calls paid for with Call Credit, pass '2' to retrieve only free Calls (that are part of a Subscription)

$month

string

varchar(20) (optional) default is two months ago. Which month do you want to get the Archive for. Parameter should be passes in this format: 'YYYY-MM', example: '2013-12'

$offset

int

int(10) (optional) default is 0, which element to start the pagination from. Does not apply for direction = 'outbound_stats/inbound_stats/stats' - there is no pagination in those cases

$limit

int

int(10) (optional) default is 200, how many records you want to display on a page. Does not apply for direction = 'outbound_stats/inbound_stats/stats' - there is no pagination in those cases

Exceptions

array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"here is no such 'X' offset! There are a total of 'X' records","data":null}
array {"status":"error","error_code":"400","message":"The maximum 'limit' you can pass to this method is '200'!","data":null}
array {"status":"error","error_code":"422","message":"The month you passed is not archived yet! The latest month you can get archives for is 'X'","data":null}
array {"status":"error","error_code":"422","message":"We don't keep archives before 2013-06. Please pass a month between 2013-06 and 'X'","data":null}

Returns

array{"status":"success","message":"Call History Archive retrieved successfully","data":[{"time":"datetime","call_status":"varchar(20)","duration":"int(11)","extension":"int(20)","extension_id":"int(11)","destination":"varchar(20)","call_cost_eur":"decimal(10,5)","clid":"varchar(20)","call_cost":"decimal(10,5) returned only if client currency is not EUR","exchange_rate":"decimal(10,5) returned only if client currency is not EUR"}],"pagination":{"page":"int(10)","per_page":"int(10)","total_records":"int(10)","total_pages":"int(10)"}}
array{"status":"success","message":"Call History Archive retrieved successfully","data":{"stats":{"extension_id":{"total_call_cost_eur":"decimal(10,5)","total_calls":"int(11)","duration":"int(11)","call_status":{"Answered":"int(11)","No Answer":"int(11)","Number Disconnected":"int(11)"},"total_call_cost_currency":"decimal(10,5) returned only if client currency is not EUR","exchange_rate":"decimal(10,5) returned only if client currency is not EUR"}},"call_statuses":["Answered","No Answer","Number Disconnected"]}}
array{"status":"success","message":"No Call History Archive found for month 'X' for accountcode 'X' and direction 'inbound/outbound/outbound_stats/inbound_stats/stats'!","user_message":"No Call History found for this period","data":null}

Call History GET

API

Get inbound or outbound call details for a specific time interval for your account or that of a client.
'start_date' cannot be before the first day of last month. Example - if it is 2014-04-04 today the minimum 'start_date' is 2014-03-01. This will be the minimum 'start_date' for the whole month of April 2014.

api http://sandbox.chainsolutions.net/voip/v1/call_history/start_date/2013-10-01/end_date/2013-10-10
api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=########&direction=inbound&start_date=2013-10-01&end_date=2013-10-10" http://sandbox.chainsolutions.net/voip/v1/call_history

Parameters

$accountcode

string

varchar(20) (optional) If you want to view the Call History for a client of yours.

$direction

string

varchar(10) (optional) default is 'outbound'. Supported values are 'inbound', 'outbound', 'inbound_stats', 'outbound_stats' and 'stats'

$extension_id

int

int(11) (optional) pass if you want to get inbound or outbound calls for a single Extension only. To get all your Extensions see the User Extension GET method

$call_type

int

int(1) (optional) if not passed all Calls will be retrieved, pass '1' to retrieve only Calls paid for with Call Credit, pass '2' to retrieve only free Calls (that are part of a Subscription)

$start_date

string

varchar(20) (optional) default is the first day of last month. Parameter should be passes in one of those formats: 'YYYY-MM-DD hh:mm:ss', example: '2012-02-28 12:12:12' OR 'YYYY-MM-DD', example: '2012-02-28'

$end_date

string

varchar(20) (optional) default is the current time. Parameter should be passes in one of those formats: 'YYYY-MM-DD hh:mm:ss', example: '2012-02-28 12:12:12' OR 'YYYY-MM-DD', example: '2012-02-28'

$offset

int

int(10) (optional) default is 0, which element to start the pagination from. Does not apply for direction = 'outbound_stats/inbound_stats/stats' - there is no pagination in those cases

$limit

int

int(10) (optional) default is 200, how many records you want to display on a page. Does not apply for direction = 'outbound_stats/inbound_stats/stats' - there is no pagination in those cases

Exceptions

array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"422","message":"You can't get Call History before the first day of last month using this method'","data":"date"}
array {"status":"error","error_code":"422","message":"Time between start_date and end_date (X days) is more than 61 days! Please select a smaller time range!","data":null}
array {"status":"error","error_code":"422","message":"start_date should be before end_date! Please select a proper time range!","data":null}
array {"status":"error","error_code":"400","message":"here is no such 'X' offset! There are a total of 'X' records","data":null}
array {"status":"error","error_code":"400","message":"The maximum 'limit' you can pass to this method is '200'!","data":null}

Returns

array{"status":"success","message":"Call History retrieved successfully","data":[{"time":"datetime","call_status":"varchar(20)","duration":"int(11)","extension":"int(20)","extension_id":"int(11)","destination":"varchar(20)","call_cost_eur":"decimal(10,5)","clid":"varchar(20)","call_cost":"decimal(10,5) returned only if client currency is not EUR","exchange_rate":"decimal(10,5) returned only if client currency is not EUR"}],"pagination":{"page":"int(10)","per_page":"int(10)","total_records":"int(10)","total_pages":"int(10)"}}
array{"status":"success","message":"Call History retrieved successfully","data":{"stats":{"extension_id":{"total_call_cost_eur":"decimal(10,5)","total_calls":"int(11)","duration":"int(11)","call_status":{"Answered":"int(11)","No Answer":"int(11)","Number Disconnected":"int(11)"},"total_call_cost_currency":"decimal(10,5) returned only if client currency is not EUR","exchange_rate":"decimal(10,5) returned only if client currency is not EUR"}},"call_statuses":["Answered","No Answer","Number Disconnected"]}}
array{"status":"success","message":"No Call History found from 'start_date' to 'end_date' for accountcode 'X' and direction 'inbound/outbound/outbound_stats/inbound_stats/stats'!","user_message":"No Call History found for this period","data":null}

Call History Summary GET

API

Get summarized Call History for a specific period of time.
The returned results are a daily sum of 'duration' and 'call_cost_eur' and are based on the calls' 'direction' and the 'prefix' dialled (if calls are outbound)

api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=########" http://sandbox.chainsolutions.net/voip/v1/call_history_summary

Parameters

$accountcode

string

varchar(20) (optional) pass if you want to get the summary for a client of yours. If not passed you will get results for your Reseller Account

$prefix

string

varchar(20) (optional) pass if you want to get a summary for a specific prefix only

$direction

string

varchar(3) (optional) Values are 'inbound' and 'outbound'. Pass one of those to get a summary for a specific direction only

$start_date

string

varchar(20) (optional) default is one month before the current day. The start of the time period for which you want to get a summary.

$end_date

string

varchar(20) (optional) default is the current date (today). The end of the time period for which you want to get a summary.

$offset

int

int(10) (optional) if it is not passed the default is '0'. Which element to start the pagination from.

$limit

int

int(10) (optional) default and max is 200, how many records you want to display on a page.

Exceptions

array {"status":"error","error_code":"400","message":"The maximum 'limit' you can pass to this method is '200'!","data":null}
array {"status":"error","error_code":"400","message":"'start_date' should be before 'end_date'! Please select a proper time range!","data":null}
array {"status":"error","error_code":"400","message":"There is no such 'X' offset! There are a total of 'X' records","data":null}

Returns

array{"status":"success","message":"Call History Summary retrieved successfully","data":[{"date":"date","prefix":"varchar(20)","direction":"varchar(3)","duration":"int(11)","call_cost_eur":"decimal(10,5)","number_of_calls":"int(11)","call_cost":"decimal(10,5) returned only if client currency is not EUR","exchange_rate": "decimal(10,5) returned only if client currency is not EUR","country":"varchar(100)","network_type":"varchar(100)","network_provider":"varchar(100)"}],"pagination":{"offset":"int(10)","limit":"int(10)","total_records":"int(10)","total_pages":"int(10)"}}
array{"status":"success","message":"No Call History Summary found from 'start_date' to 'end_date' for accountcode 'X' and direction 'inbound/outbound'!","user_message":"No Call History found for this period","data":null}

Call Rates GET

API

Returns the rate per minute for calling a certain Country and dial code.
The closest match between the dialled number and the dial code displayed here will be the price you pay - for example dialling 004493213212321 will be billed for the rate of '449' and not '44'.
Have in mind rates change constantly and without notice.

api http://sandbox.chainsolutions.net/voip/v1/call_rates
api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=########&country_code=USA" http://sandbox.chainsolutions.net/voip/v1/call_rates

Parameters

$country_code

string

varchar(3) the Country you want to get the rates for. You can get a full list of Countries from the Countries GET method

$dial_code

int

int(12) (optional) if you want to retrieve the rate for a single destination. Pass the 'dial_code' without leading zeros

Exceptions

array {"status":"error","error_code":"400","message":"The 'dial_code' passed does not exist in our Call Rates","data":null}
array {"status":"error","error_code":"400","message":"Country is not properly set! Please use a country from the 'Countries GET' function, using the 'country_code' index!","data":null}
array {"status":"error","error_code":"500","message":"There was a problem retrieving Call Rates","data":null}

Returns

array{"status":"success","message":"Call Rates retrieved successfully","data":[{"dial_code":"int(12)","rate_eur":"decimal(10,5)","rate_reseller_currency":"decimal(10,5) returned only if your Reseller account is not in EUR","network_type":"varchar(50)"}]}
array{"status":"success","message":"No Call Rates found for selected country_code X","user_message":"No Call Rates found for selected Country","data":null}

Call Recording GET

API

Get call recordings for a specific time interval for your account or that of a client. Time interval between dates cannot be more than 60 days. You can also get the details for a specific Recording (passing 'recording_id' variable)

api http://sandbox.chainsolutions.net/voip/v1/call_recording/recording_id/#####
api http://sandbox.chainsolutions.net/voip/v1/call_recording/start_date/2013-10-01/end_date/2013-10-10
api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=########&direction=inbound&start_date=2013-10-01&end_date=2013-10-10" http://sandbox.chainsolutions.net/voip/v1/call_recording

Parameters

$accountcode

string

varchar(20) (optional) If you want to view the Call Recordings for a client of yours.

$recording_id

int

int(11) (optional) if you want to get the details for a specific Recording

$direction

string

varchar(10) (optional) default is 'none', meaning you get all of them. Supported values are 'inbound' and 'outbound'

$start_date

string

varchar(20) (optional) default is 7 days (one week) before the current time. Parameter should be passes in one of those formats: 'YYYY-MM-DD hh:mm:ss', example :'2012-02-28 12:12:12' OR 'YYYY-MM-DD', example :'2012-02-28'

$end_date

string

varchar(20) (optional) default is the current time. Parameter should be passes in one of those formats: 'YYYY-MM-DD hh:mm:ss', example :'2012-02-28 12:12:12' OR 'YYYY-MM-DD', example :'2012-02-28'

$offset

int

int(10) (optional) if 'accountcode' is not passed the default is '0'. Which element to start the pagination from. Does not return pagination information when 'accountcode' is passed, as a single record is returned

$limit

int

int(2) (optional) default and max is 20, how many records you want to display on a page. Does not return pagination information when 'accountcode' is passed, as a single record is returned

Exceptions

array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"422","message":"Time between start_date and end_date (X days) is more than 60 days! Please select a smaller time range!","data":null}
array {"status":"error","error_code":"422","message":"start_date should be before end_date! Please select a proper time range!","data":null}
array {"status":"error","error_code":"403","message":"Wrong recording_id or insufficient permissions to view recording details!","data":null}

Returns

array{"status":"success","message":"Call Recordings retrieved successfully","data":[{"recording_id":"int(11)","extension":"int(20)","direction":"varchar(20) (inbound or outbound)","date_stamp":"datetime","file_size":"int(11) in bytes","number_dialed":"varchar(20)","download_link":"varchar(150)"}]}
array{"status":"success","message":"No Call Recordings found from $start_date to $end_date!","data":null}

Click to Call DELETE

API

Delete a Click to Call record for you or a client of yours. Your client should have let you modify their account settings to do that.

api curl -k -i -H "Accept: application/json" -X DELETE -d "X-API-KEY=########&click_to_call_id=1" http://sandbox.chainsolutions.net/voip/v1/click_to_call

Parameters

$accountcode

string

varchar(20) (optional) If you want to delete a Click to Call for a client of yours

$click_to_call_id

int

int(11)

Exceptions

array {"status":"error","error_code":"400","message":"click_to_call_id must be set","data":null}
array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"click_to_call_id does not exist or you don't have privileges to modify it!","data":null}
array {"status":"error","error_code":"500","message":"Could not delete Click to Call record at this time!","data":null}

Returns

array{"status":"success","message":"Click to Call deleted successfully","data":null}

Click to Call GET

API

Get all or a single Click to Call record for you or a client of yours. Your client should have let you modify their account settings to do that.

api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=########" http://sandbox.chainsolutions.net/voip/v1/click_to_call

Parameters

$accountcode

string

varchar(20) (optional) If you want to get a Click to Call record for a client of yours

$click_to_call_id

int

int(11) (optional) If you want to get a single Click to Call record

Exceptions

array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"click_to_call_id does not exist or you don't have privileges to modify it!","data":null}

Returns

array{"status":"success","message":"Click to Call records retrieved successfully","data":[{"click_to_call_id":"int(11)","route":"varchar(50)","route_type":"varchar(30)","code":"varchar(20)","wait_for_key":"int(1)","active":"int(1)","recording_enabled":"int(1)","spam_filter_minutes":"int(2)"}]}
array{"status":"success","message":"You don't have Click to Call records yet","data":null}

Click to Call POST

API

Create a Click to Call record for you or a client of yours. Your client should have let you modify their account settings to do that. You can route the Click to Call to one of those - an External Number (passing 'phone_number'), an Extension of yours (passing 'extension'), a Queue (passing 'queue_id') or an IVR (passing 'ivr_id'). Be careful to pass only one of those routing options as we won't know which one you would like to use

api curl -k -i -H "Accept: application/json" -X POST -d "X-API-KEY=########&phone_number=003124323423" http://sandbox.chainsolutions.net/voip/v1/click_to_call

Parameters

$accountcode

string

varchar(20) (optional) If you want to create a Click to Call for a client of yours

$sip

string

varchar(255) Route the Click to Call to a SIP address

$phone_number

string

varchar(20) Route Click to Call to an external Phone Number. It will be 'normalized' to international standards with leading zeroes (example: 00448445025003)

$extension

string

varchar(30) Pass the extension number here, example '5541000'. You can get the 'extension' from the User Extension GET method

$extension_id

int

int(11) Do not pass when passing 'extension'. You can get the 'extension_id' from the User Extension GET method

$queue_id

int

int(11) Pass the ID of the Queue you want to route the Click to Call to

$ivr_id

int

int(11) Pass the ID of the IVR you want to route the Click to Call to

$recording_id

int

int(11) Route DID to a pre-recorded Recording.

$wait_for_key

int

int(1) (optional) default is '1', meaning that you will have to press a key to let the system you know you are ready before the system calls the client

$active

int

int(1) (optional) default is '1', meaning the Click to Call is active, set to '0' for inactive

$recording_enabled

int

int(1) (optional) default is '0', meaning calls done will not be recorded. Pass '1' to enable call recording

$spam_filter_minutes

int

int(2) (optional) default is '0', if different than '0' users with the same IP address won't be able to use the Click to Call for this minute amount. This is in place to avoid malicious scripts and people trying to manually intervene with the service

Exceptions

array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"You need to have Hosted PBX functionality enabled for this Account in order to route to a Phone Number, Queue or IVR. You can change this from the Account PUT method","data":null}
array {"status":"error","error_code":"400","message":"Please pass a routing option! You should pass ONE of those: sip', 'phone_number', 'extension', 'queue_id', 'ivr_id', 'time_profile_id', 'recording_id'!","data":null}
array {"status":"error","error_code":"400","message":"Please pass only one routing option! You should pass ONE of those: 'sip', 'phone_number', 'extension', 'queue_id', 'ivr_id', 'time_profile_id', 'recording_id'!","data":null}
array {"status":"error","error_code":"400","message":"The 'extension' you passed 'X' is not valid or does not belong to selected user","data":null}
array {"status":"error","error_code":"400","message":"The 'extension_id' you passed 'X' is not valid or does not belong to selected user","data":null}
array {"status":"error","error_code":"400","message":"The 'queue_id' you passed 'X' is not valid or does not belong to selected user","data":null}
array {"status":"error","error_code":"400","message":"The 'ivr_id' you passed 'X' is not valid or does not belong to selected user","data":null}
array {"status":"error","error_code":"400","message":"The 'recording_id' you passed 'X' is not valid or does not belong to selected user","data":null}
array {"status":"error","error_code":"500","message":"Could not create a Click to Call record at this time!","data":null}

Returns

array{"status":"success","message":"Click to Call created successfully","data":{"click_to_call_id":"int(11)","code":"varchar(20)"}}

Click to Call PUT

API

Edit a Click to Call record for you or a client of yours. Your client should have let you modify their account settings to do that.

api curl -k -i -H "Accept: application/json" -X PUT -d "X-API-KEY=########&click_to_call_id=1&phone_number=003124323423" http://sandbox.chainsolutions.net/voip/v1/click_to_call

Parameters

$accountcode

string

varchar(20) (optional) If you want to edit a Click to Call for a client of yours

$click_to_call_id

int

int(11)

$phone_number

string

varchar(30) Number will be 'normalized' to international standards with leading zeroes (example: 00448445025003) no matter how entered

$extension

string

varchar(30) Pass the extension number here, example '5541000'

$queue_id

int

int(11) Pass the ID of the Queue you want to route the Click to Call to

$ivr_id

int

int(11) Pass the ID of the IVR you want to route the Click to Call to

$recording_id

int

int(11) Route DID to a pre-recorded Recording.

$wait_for_key

int

int(1) (optional) default is '1', meaning that you will have to press a key to let the system you know you are ready before the system calls the client

$active

int

int(1) (optional) '1' - the Click to Call is active, set to '0' for inactive

$recording_enabled

int

int(1) (optional) '0' - calls done will not be recorded, '1' - enable call recording

$spam_filter_minutes

int

int(2) (optional) if different than '0' users with the same IP address won't be able to use the Click to Call for this minute amount. This is in place to avoid malicious scripts and people trying to manually intervene with the service

Exceptions

array {"status":"error","error_code":"400","message":"click_to_call_id must be set","data":null}
array {"status":"error","error_code":"400","message":"Please pass any parameters to change! You should pass either 'phone_number', 'active' or 'wait_for_key' or any combination of those","data":null}
array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"You need to have Hosted PBX functionality enabled for this Account in order to route to a Phone Number, Queue or IVR. You can change this from the Account PUT method","data":null}
array {"status":"error","error_code":"400","message":"Please pass only one routing option! You should pass ONE of those: 'sip', 'phone_number', 'extension', 'queue_id', 'ivr_id', 'recording_id'!","data":null}
array {"status":"error","error_code":"400","message":"The 'extension' you passed 'X' is not valid or does not belong to selected user","data":null}
array {"status":"error","error_code":"400","message":"The 'extension_id' you passed 'X' is not valid or does not belong to selected user","data":null}
array {"status":"error","error_code":"400","message":"The 'queue_id' you passed 'X' is not valid or does not belong to selected user","data":null}
array {"status":"error","error_code":"400","message":"The 'ivr_id' you passed 'X' is not valid or does not belong to selected user","data":null}
array {"status":"error","error_code":"400","message":"The 'recording_id' you passed 'X' is not valid or does not belong to selected user","data":null}
array {"status":"error","error_code":"400","message":"click_to_call_id does not exist or you don't have privileges to modify it!","data":null}
array {"status":"error","error_code":"500","message":"Could not edit Click to Call record at this time!","data":null}
array {"status":"error","error_code":"500","message":"Please change some parameters to edit Click to Call","data":null}

Returns

array{"status":"success","message":"Click to Call updated successfully","data":null}

Countries GET

API

Returns a list of country codes, names and dial prefixes.

api http://sandbox.chainsolutions.net/voip/v1/countries
api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=##########" http://sandbox.chainsolutions.net/voip/v1/countries

Exceptions

array {"status":"error","error_code":"500","message":"Cannot retrieve countries list now. Please try again later","data":null}

Returns

array{"status":"success","message":"Countries retrieved successfully","data":[{"country_code":"varchar(3)","prefix":"varchar(10) same as dial_prefix, kept for backward compatibility","dial_prefix":"varchar(10) without leading 00","name":"varchar(50)"}]}

Currencies GET

API

Get a list of currencies with conversion rates. Used when creating (Account GET) or modifying (Account PUT) accounts

api http://sandbox.chainsolutions.net/voip/v1/currencies
api http://sandbox.chainsolutions.net/voip/v1/currencies/currency/USD
api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=################" http://sandbox.chainsolutions.net/voip/v1/currencies

Parameters

$currency

string

varchar(3) if you want to retrieve a single currency

Exceptions

array {"status":"error","error_code":"500","message":"Couldn't retrieve Currencies right now! Please try again later","data":null}

Returns

array{"status":"success","message":"Currencies retrieved successfully","data":[{"currency":"varchar(3)","currency_name":"varchar(40)","exchange_to_eur":"decimal(10,5)","last_update":"datetime"}]}

Custom Package DELETE

API

Delete an existing Custom Package.
If you have Billing Subscriptions related to this Custom Package you won't be able to delete it.

api curl -k -i -H "Accept: application/json" -X DELETE -d "X-API-KEY=##########&custom_package_id=5" http://sandbox.chainsolutions.net/voip/v1/custom_package

Parameters

$custom_package_id

int

int(11)

Exceptions

array {"status":"error","error_code":"400","message":"custom_package_id must be set","data":null}
array {"status":"error","error_code":"422","message":"custom_package_id must be a numeric value","data":null}
array {"status":"error","error_code":"400","message":"Wrong custom_package_id or it does not belong to your Account!","data":null}
array {"status":"error","error_code":"400","message":"There are Billing Subscriptions associated with this custom_package_id! Please delete all associated subscriptions or EDIT the Custom Package instead of deleting it!","data":null}
array {"status":"error","error_code":"500","message":"There was a problem deleting this Custom Package. Please try again","data":null}

Returns

array{"status":"success","message":"Custom Package deleted successfully","data":null}

Custom Package GET

API

Get all Custom Packages related to your Account. You will also get their prices in your own currency. The returned 'months' index indicates how often a Billing Subscription based on this Package is being paid for. If 'months' = 1 than the Subscription is monthly. If it is '12' than the Subscription is yearly. If you want to change the 'months' period for a particular System Package please contact us directly.

api http://sandbox.chainsolutions.net/voip/v1/custom_package
api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=###########" http://sandbox.chainsolutions.net/voip/v1/custom_package

Parameters

$custom_package_id

int

int(11) (optional) if you want to get the information for a particular Custom Package only

$did_package_only

int

boolean (optional) pass '1' if you want to get Custom Packages for DIDs only. This can be useful when using Porting Number POST and DID Order POST methods that require you pass a DID Custom Package

Exceptions

array {"status":"error","error_code":"400","message":"The 'custom_package_id' you passed does not correspond to an existing Custom Package","data":null}

Returns

array{"status":"success","message":"Custom Packages retrieved successfully","data":[{"custom_package_id":"int(11)","system_package_id":"int(11)","system_package_name":"varchar(45)","system_package_description":"varchar(1000)","name":"varchar(45)","description":"text","buy_eur":"decimal(10,5)","buy_reseller_currency":"decimal(10,5) if different from 0 your clients that are in the same currency will be billed on this price","sell_eur":"decimal(10,5)","sell_price_reseller_currency":"decimal(10,5)","buy_price_reseller_currency":"decimal(10,5)","active":"int(1)","buy_price_converted_from_eur":"decimal(10,5)","sell_price_converted_from_eur":"decimal(10,5)","reseller_currency":"varchar(3)","exchange_rate":"decimal(10,5)","months":"int(2)"}]}
array{"status":"success","message":"No Custom Packages available for this Account","data":null}

Custom Package POST

API

Create new Custom Package based on a System Package

api curl -k -i -H "Accept: application/json" -X POST -d "X-API-KEY=##########&system_package_id=1&sell_eur=10&active=1" http://sandbox.chainsolutions.net/voip/v1/custom_package

Parameters

$system_package_id

int

int(11) see System Package GET method to get this value

$sell_eur

float

decimal(10,5) The price in EUR for which you are going to sell this Custom Package to your End Users.

$sell_price_reseller_currency

float

(optional) decimal(10,5) The price in your own Account Currency for which you are going to sell this Custom Package to your End Users.
We suggest you use this column if you want to always charge your End Users a fixed amount in your own Currency. If you don't pass this price the 'sell_eur' price will be used, which may result in your clients paying different prices each month due to currency conversion (our base Currency is EUR)

$active

int

int(1) (optional) default is '1' => active, '0' => inactive

$name

string

varchar(45) (optional) if not passed the System Package's name will be used. This value will appear on client's invoices

$description

string

text (optional) if not passed the System Package's description will be used. This value will appear on client's invoices

Exceptions

array {"status":"error","error_code":"400","message":"system_package_id must be set","data":null}
array {"status":"error","error_code":"400","message":"sell_eur must be set","data":null}
array {"status":"error","error_code":"422","message":"sell_eur must be a numeric value","data":null}
array {"status":"error","error_code":"400","message":"You have selected a system_package_id that does not exist or does not belong to your Account!","data":null}
array {"status":"error","error_code":"500","message":"Could not create Custom Package right now. Please try again later","data":null}

Returns

array{"status":"success","message":"Custom Package created successfully","data":{"custom_package_id":"int(11)"}}

Custom Package PUT

API

Edit existing Custom Package's details

api curl -k -i -H "Accept: application/json" -X PUT -d "X-API-KEY=##########&custom_package_id=5&sell_eur=6&active=0&name=foo&description=bar" http://sandbox.chainsolutions.net/voip/v1/custom_package

Parameters

$custom_package_id

int

int(11) you can get this from Custom Package GET

$sell_eur

float

decimal(10,5) (optional) The price in EUR for which you are going to sell this Custom Package to your End Users.

$sell_price_reseller_currency

float

(optional) decimal(10,5) The price in your own Account Currency for which you are going to sell this Custom Package to your End Users
We suggest you use this column if you want to always charge your End Users a fixed amount in your own Currency. If you don't pass this price the 'sell_eur' price will be used, which may result in your clients paying different prices each month due to currency conversion (our base Currency is EUR)

$active

int

int(1) (optional) '0' => inactive, '1' => active

$name

string

varchar(45) (optional) This value will appear on client's invoices

$description

string

text (optional) This value will appear on client's invoices

$update_related_subscriptions

int

int(1) (optional) if you pass '1' all Billing Subscriptions with this 'custom_package_id' will be updated with the new prices you set for this Custom Package. If 'sell_eur' or 'sell_client_currency' are not passed the Billing Subscriptions will still be updated

Exceptions

array {"status":"error","error_code":"400","message":"custom_package_id must be set","data":null}
array {"status":"error","error_code":"400","message":"You should pass some parameters to change the custom package!","data":null}
array {"status":"error","error_code":"422","message":"custom_package_id must be a numeric value","data":null}
array {"status":"error","error_code":"400","message":"The underlying system_package_id was either deleted or marked as inactive. Please contact us to fix this","data":null}
array {"status":"error","error_code":"422","message":"sell_eur must be greater or equal to 'X' - the price in EUR you pay us for the System Package","data":null}
array {"status":"error","error_code":"400","message":"Wrong custom_package_id or it does not belong to your Account!","data":null}
array {"status":"error","error_code":"500","message":"There was a problem updating this Custom Package. Please try again","data":null}

Returns

array{"status":"success","message":"Custom Package updated successfully","data":null}

DID Countries List GET

API

Get list of countries you can order DIDs from

api http://sandbox.chainsolutions.net/voip/v1/did_countries_list
api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=##########" http://sandbox.chainsolutions.net/voip/v1/did_countries_list

Exceptions

array {"status":"error","error_code":"504","message":"A timeout error occurred. We could not retrieve the requested data. Please try again later","data":{"seconds_elapsed":"decimal(2,10)"}}
array {"status":"error","error_code":"500","message":"Cannot retrieve countries list now. Please try again later","data":null}

Returns

array{"status":"success","message":"DID Countries retrieved successfully","data":[{"country_name":"varchar(40)","country_code":"varchar(3)","has_states":"boolean","has_regulation_requirement":"boolean"}]}

DID DELETE

API

Remove a DID from Account's Billing. All related services will stop working. If you are doing this on the production environment the DID's Billing Subscription should be at least 3 months old.

api curl -k -i -H "Accept: application/json" -X DELETE -d "X-API-KEY=########&accountcode=########&did_id=###" http://sandbox.chainsolutions.net/voip/v1/did

Parameters

$did_id

int

you can get this using DID GET method

$accountcode

string

(optional) If you want to delete a DID that belongs to a client of yours

Exceptions

array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"Wrong 'did_id' or DID does not belong to selected account!","data":null}
array {"status":"error","error_code":"500","message":"There was error trying to access the Billing Subscription of your DID. Please try again","data":null}
array {"status":"error","error_code":"400","message":"Your DID's Billing Subscription must be at least 3 months old! You cannot delete the DID before that","data":null}
array {"status":"error","error_code":"500","message":"Unable to delete DID on our supplier's end. Please try again","data":null}
array {"status":"error","error_code":"500","message":"Unable to delete related Billing Subscription. Please try again","data":null}
array {"status":"error","error_code":"500","message":"An error occurred while deleting your DID. Please try again","data":null}
array {"status":"error","error_code":"500","message":"There was a problem deleting this DID. We are missing a record in our DataBase","user_message":"Please contact us to remove this DID manually.","data":null}

Returns

array{"status":"success","message":"DID deleted successfully","user_message":"DID 'did' was successfully deleted!","data":null}

DID E911 CAN Provinces GET

API

Get a list of Provinces in Canada and their Province Abbreviations. Used in DID E911 Request POST

api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=########" http://sandbox.chainsolutions.net/voip/v1/did_e911_can_provinces

Exceptions

array {"status":"error","error_code":"500","message":"There was a problem retrieving E911 CAN Provinces information. Please try again","data":null}

Returns

array{"status":"success","message":"E911 CAN Provinces retrieved successfully","data":[{"province_name":"varchar(30)","postal_abbreviation":"varchar(2)"}]}

DID E911 Request DELETE

API

Remove E911 Service from a DID in the US or Canada. The E911 Service should already be active on the DID.

api curl -k -i -H "Accept: application/json" -X DELETE -d "X-API-KEY=########&did_id=417" http://sandbox.chainsolutions.net/voip/v1/did_e911_request

Parameters

$did_id

int

int(11) The ID of the DID for which you want to cancel the E911 Service. Get it from DID GET method

Exceptions

array {"status":"error","error_code":"400","message":"Selected 'did_id' does not have E911 services enabled. You cannot disable something that is not enabled","data":null}
array {"status":"error","error_code":"400","message":"Selected 'did_id' doest not exist","user_message":"Selected DID does not exist in our database","data":null}
array {"status":"error","error_code":"400","message":"Selected 'did_id' is not one in the US or Canada. Country code: 'XXX'","data":null}
array {"status":"error","error_code":"400","message":"Your DID is not active. Please pay your Billing Subscription","data":null}
array {"status":"error","error_code":"400","message":"The 'did_id' you passed does not belong to you or any of your customers!","data":null}
array {"status":"error","error_code":"400","message":"You have already submitted a Request for canceling E911 Service for this 'did_id'. The Request is being processed so please be patient","data":null}
array {"status":"error","error_code":"500","message":"Could not create provisioning file. Please try again","data":null}
array {"status":"error","error_code":"500","message":"Could not upload file to database","data":null}
array {"status":"error","error_code":"500","message":"Unable to update the status of your request","data":null}
array {"status":"error","error_code":"500","message":"Unable to send your Request for Delete of E911 service. Please try again","data":null}

Returns

array{"status":"success","message":"Your E911 Delete Request was successfully created and is waiting for processing and approval","data":{"did_e911_request_id":"int(11)"}}

DID E911 Request GET

API

Get a list of your DID E911 Service Requests.
You need to check the status of requests to confirm they have been processed successfully.
You can also check the 'has_e911' flag in the DID GET method - it shows if the E911 Service is enabled or not on a DID

The 'request_status' possible values are:
'Not Sent' - we have not yet send your request to our provider.
'Waiting for approval' - request is at our provider's end.
'Approved' - all went well and the E911 service is enabled on the DID.
'Invalid Request' - there was a problem with the request and DID E911 Request POST needs to be passed again.

api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=########&did_e911_request_id=1" http://sandbox.chainsolutions.net/voip/v1/did_e911_request

Parameters

$did_e911_request_id

int

int(11) (optional) Returned from DID E911 Request POST

$offset

int

int(10) (optional) default is '0', which element to start the pagination from.

$limit

int

int(2) (optional) default and max is 20, how many records you want to display on a page.

Exceptions

array {"status":"error","error_code":"500","message":"There was a problem retrieving E911 Service Requests. Please try again","data":null}

Returns

array{"status":"success","message":"You haven't made any E911 Service Requests or the selected Request does not belong to you","data":null}
array{"status":"success","message":"DID E911 Service Requests retrieved successfully","data":[{"did_e911_request_id":"int(11)","did_id":"int(11)","accountcode":"varchar(20)","request_status":"varchar(20)","status_note":"varchar(1000) if the 'request_status' is 'Invalid Request' it will hold text information why","did_E164":"varchar(15)","transaction_type":"varchar(6)","service":"varchar(2)","service_type":"varchar(3)","customer_type":"varchar(3)","first_name":"varchar(20)","last_name":"varchar(50)","company_name":"varchar(100)","house_number":"varchar(10)","house_number_suffix":"varchar(10)","street_name":"varchar(20)","street_name_suffix":"varchar(10)","locality":"varchar(25)","county_id":"int(3)","state_abbreviation":"varchar(2)","province_abbreviation":"varchar(2)","zip":"varchar(20)","additional_info":"varchar(20)"}]}

DID E911 Request POST

API

Add E911 service to a DID in the United States or Canada.
The DID needs to be active (it's related Billing Subscription should be paid for).
E911 Service for DIDs is free of charge as it is included in the Subscription price.

api curl -k -i -H "Accept: application/json" -X POST -d "X-API-KEY=########&did_id=417&customer_type=BUS&company_name=ChainSolutions&house_number=12&house_number_suffix=2&street_name=street_name&street_name_suffix=ave&county_id=225&state_abbreviation=TX&locality=Houston&zip=77298&additional_info=TestRequest" http://sandbox.chainsolutions.net/voip/v1/did_e911_request

Parameters

$did_id

int

int(11) get from DID GET method

$customer_type

string

varchar(3) Identifier of the customer types. Pass 'RES' for Residential customer and 'BUS' for Business.

$first_name

string

varchar(20) First Name of customer. Optional for Business customers.

$last_name

string

varchar(50) Last Name of customer. Do not pass if you want to provide 'company_name' for Business Customers.

$title

string

varchar(3) Allowed values are 'Mr', 'Mrs', 'Ms'. Not allowed if 'company_name' filled out.

$company_name

string

varchar(100) Company name of business customer ('BUS'). Do not pass if you want to provide 'last_name' for Business customer OR when 'customer_type' is 'RES'.

$house_number

int

int(10) Identifies the house on a street

$house_number_suffix

int

varchar(10) (optional) Flat number/floor

$street_name

string

varchar(20) Identifies the house on a street

$street_name_suffix

string

varchar(10) (optional) Street abbreviation, as defined by the U.S. Postal Service Publication 28 or Canadian Postal Service Publication (e.g., AVE).

$locality

string

varchar(25) Town or city name.

$county_id

int

int(11) (required for US DIDs) Get from DID E911 US Counties GET

$state_abbreviation

string

varchar(2) (required for US DIDs) Get from DID E911 US States GET

$province_abbreviation

string

varchar(2) (required for Canada DIDs) Get from DID E911 CAN Provinces GET

$zip

string

varchar(20) The full current postcode for the address as recognized by the US or Canadian post office.

$additional_info

string

varchar(20) (optional) Pass any additional address or client information here

Exceptions

array {"status":"error","error_code":"400","message":"There was a problem retrieving E911 US States information. Please try again","data":null}
array {"status":"error","error_code":"400","message":"Selected 'did_id' already has E911 service enabled","data":null}
array {"status":"error","error_code":"400","message":"Selected 'did_id' is not one in the US or Canada. Country code: 'XXX'","data":null}
array {"status":"error","error_code":"400","message":"The 'did_id' you passed does not belong to you or a client of yours","data":null}
array {"status":"error","error_code":"400","message":"The 'state_abbreviation' you passed is invalid","data":null}
array {"status":"error","error_code":"400","message":"The 'county_id' you passed is invalid","data":null}
array {"status":"error","error_code":"400","message":"The 'province_abbreviation' you passed is not one of a Canada Province","user_message":"The Canada Province you chose is not valid","data":null}
array {"status":"error","error_code":"400","message":"E911 Request already created for this DID. Please wait for the previous request to get Approved","data":null}
array {"status":"error","error_code":"400","message":"Your DID is not active. Please pay your Billing Subscription","data":null}
array {"status":"error","error_code":"400","message":"The 'did_id' you passed does not belong to you or any of your customers!","data":null}
array {"status":"error","error_code":"400","message":"Please provide only 'company_name' or 'last_name' for business clients","data":null}
array {"status":"error","error_code":"500","message":"Could not create provisioning file. Please try again","data":null}
array {"status":"error","error_code":"500","message":"Could not upload file to database","data":null}
array {"status":"error","error_code":"500","message":"Unable to update the status of your request","data":null}
array {"status":"error","error_code":"500","message":"Unable to send your request for E911 service. Please try again","data":null}

Returns

array{"status":"success","message":"Your request was successfully created and is waiting for processing and approval","data":{"did_e911_request_id":"int(11)"}}

DID E911 Request PUT

API

Edit the information provided for a DID's E911 Service in the US or Canada.
E911 Service should already be active on this DID.

api curl -k -i -H "Accept: application/json" -X POST -d "X-API-KEY=########&customer_type=BUS&company_name=ChainSolutions&house_number=12&house_number_suffix=2&street_name=street_name&street_name_suffix=ave&county_id=225&state_abbreviation=TX&locality=Houston&zip=77298&additional_info=TestRequest" http://sandbox.chainsolutions.net/voip/v1/did_e911_request

Parameters

$did_id

int

int(11) The ID of the DID for which you want to update the E911 Service Information. Get from DID GET method

$customer_type

string

varchar(3) Identifier of the customer types. Pass 'RES' for Residential customer and 'BUS' for Business.

$first_name

string

varchar(20) First name of customer. Optional for Business customers.

$last_name

string

varchar(50) Last name of customer. Do not pass if you want to provide 'company_name' for Business Customers.

$title

string

varchar(3) Allowed values are 'Mr', 'Mrs', 'Ms'

$company_name

string

varchar(100) Company name of business customer ('BUS'). Do not pass if you want to provide 'last_name' for Business customer OR when 'customer_type' is 'RES'.

$house_number

int

int(10) Identifies the house on a street

$house_number_suffix

int

varchar(10) (optional) Flat number/floor

$street_name

string

varchar(20) Identifies the house on a street

$street_name_suffix

string

varchar(10) (optional) Street abbreviation, as defined by the U.S. Postal Service Publication 28 or Canadian Postal Service Publication (e.g., AVE).

$locality

string

varchar(25) Town or city name.

$county_id

int

int(11) (required for US DIDs) Get from DID E911 US Counties GET

$state_abbreviation

string

varchar(2) (required for US DIDs) Get from DID E911 US States GET

$province_abbreviation

string

varchar(2) (required for Canada DIDs) Get from DID E911 CAN Provinces GET

$zip

string

varchar(20) The full current postcode for the address as recognized by the US or Canadian post office.

$additional_info

string

varchar(20) (optional) Pass any additional address or client information here

Exceptions

array {"status":"error","error_code":"400","message":"Selected 'did_id' does not have E911 services enabled. You cannot edit the information before it is enabled","data":null}
array {"status":"error","error_code":"400","message":"Selected 'did_id' doest not exist","user_message":"Selected DID does not exist in our database","data":null}
array {"status":"error","error_code":"400","message":"Selected 'did_id' is not one in the US or Canada. Country code: 'XXX'","data":null}
array {"status":"error","error_code":"400","message":"Selected DID does not have an E911 Service Request","data":null}
array {"status":"error","error_code":"400","message":"The 'state_abbreviation' you passed is invalid","data":null}
array {"status":"error","error_code":"400","message":"The 'county_id' you passed is invalid","data":null}
array {"status":"error","error_code":"400","message":"Selected 'did_id' does not have an 'Approved' Request for E911 services. Please wait for the request to be 'Approved'","user_message":"E911 Service address approval is pending for verification","data":null}
array {"status":"error","error_code":"400","message":"There was a problem retrieving E911 US States information. Please try again","data":null}
array {"status":"error","error_code":"400","message":"The 'did_id' you passed does not belong to you or a client of yours","data":null}
array {"status":"error","error_code":"400","message":"Please provide only 'company_name' or 'last_name' for business clients","data":null}
array {"status":"error","error_code":"500","message":"Could not create provisioning file. Please try again","data":null}
array {"status":"error","error_code":"500","message":"Could not upload file to database","data":null}
array {"status":"error","error_code":"500","message":"Unable to update the status of your request","data":null}
array {"status":"error","error_code":"500","message":"Unable to send your Request for Update of E911 service. Please try again","data":null}

Returns

array{"status":"success","message":"Your E911 Update Request was successfully created and is waiting for processing and approval","data":{"did_e911_request_id":"int(11)"}}

DID E911 US Counties GET

API

Get a list of the Counties in the USA and their IDs. Used in DID E911 US Request POST

api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=########&state_id=1" http://sandbox.chainsolutions.net/voip/v1/did_e911_us_counties
api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=########&state_abbreviation=OH" http://sandbox.chainsolutions.net/voip/v1/did_e911_us_counties

Parameters

$state_id

int

int(2) (optional) Pass if you want to retrieve the counties in a specific state get from DID E911 States GET

$state_abbreviation

string

varchar(2) (optional) Pass if you want to retrieve the counties in a specific state get from DID E911 States GET

Exceptions

array {"status":"error","error_code":"500","message":"There was a problem retrieving E911 US Counties information. Please try again","data":null}

Returns

array{"status":"success","message":"E911 US Counties retrieved successfully","data":[{"county_id":"int(11)","state_id":"int(2)","state_abbreviation":"varchar(2)","county_name":"varchar(50)"}]}

DID E911 US Request DELETE

API

Remove E911 Service from a DID in the US. The E911 Service should already be active on the DID.

api curl -k -i -H "Accept: application/json" -X DELETE -d "X-API-KEY=########&did_id=417" http://sandbox.chainsolutions.net/voip/v1/did_e911_us_request

Parameters

$did_id

int

int(11) The ID of the DID for which you want to cancel the E911 US Service. Get it from DID GET method

Exceptions

array {"status":"error","error_code":"400","message":"Selected 'did_id' does not have E911 services enabled. You cannot disable something that is not enabled","data":null}
array {"status":"error","error_code":"400","message":"Selected 'did_id' doest not exist","user_message":"Selected DID does not exist in our database","data":null}
array {"status":"error","error_code":"400","message":"Your DID is not active. Please pay your Billing Subscription","data":null}
array {"status":"error","error_code":"400","message":"The 'did_id' you passed does not belong to you or any of your customers!","data":null}
array {"status":"error","error_code":"400","message":"The 'did_id' you passed is not one of a US number! All US DIDs should start with 001","data":null}
array {"status":"error","error_code":"400","message":"You have already submitted a Request for canceling E911 Service for this 'did_id'. The Request is being processed so please be patient","data":null}
array {"status":"error","error_code":"500","message":"Could not create provisioning file. Please try again","data":null}
array {"status":"error","error_code":"500","message":"Could not upload file to database","data":null}
array {"status":"error","error_code":"500","message":"Unable to update the status of your request","data":null}
array {"status":"error","error_code":"500","message":"Unable to send your Request for Delete of E911 service. Please try again","data":null}

Returns

array{"status":"success","message":"Your E911 US Delete Request was successfully created and is waiting for processing and approval","data":{"did_e911_request_id":"int(11)"}}

DID E911 US Request GET

API

Get a list of your US DID E911 Service Requests.
You need to check the status of requests to confirm they have been processed successfully.
You can also check the 'has_e911' flag in the DID GET method - it shows if the E911 Service is enabled or not on a DID

The 'request_status' possible values are:
'Not Sent' - we have not yet send your request to our provider.
'Waiting for approval' - request is at our provider's end.
'Approved' - all went well and the E911 service is enabled on the DID.
'Invalid Request' - there was a problem with the request and DID E911 US Request PUT needs to be passed again.

api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=########&did_e911_request_id=1" http://sandbox.chainsolutions.net/voip/v1/did_e911_us_request

Parameters

$did_e911_request_id

int

int(11) Returned from DID E911 US Request POST

$offset

int

int(10) (optional) default is '0', which element to start the pagination from.

$limit

int

int(2) (optional) default and max is 20, how many records you want to display on a page.

Exceptions

array {"status":"error","error_code":"500","message":"There was a problem retrieving E911 Service Requests. Please try again","data":null}

Returns

array{"status":"success","message":"You haven't made any E911 Service Requests or the selected Request does not belong to you","data":null}
array{"status":"success","message":"DID E911 Service Requests retrieved successfully","data":[{"did_e911_request_id":"int(11)","did_id":"int(11)","accountcode":"varchar(20)","request_status":"varchar(20)","status_note":"varchar(1000) if the 'request_status' is 'Invalid Request' it will hold text information why","did_E164":"varchar(15)","transaction_type":"varchar(6)","service":"varchar(2)","service_type":"varchar(3)","customer_type":"varchar(3)","first_name":"varchar(20)","last_name":"varchar(50)","company_name":"varchar(100)","house_number":"varchar(10)","house_number_suffix":"varchar(10)","street_name":"varchar(20)","street_name_suffix":"varchar(10)","locality":"varchar(25)","county_id":"int(3)","state_abbreviation":"varchar(2)","zip":"varchar(20)","additional_info":"varchar(20)"}]}

DID E911 US Request POST

API

Add E911 service to a DID in the United States.
The DID needs to be active (it's related Billing Subscription should be paid for).
E911 Service for US DIDs is free of charge as it is included in the Subscription price.

api curl -k -i -H "Accept: application/json" -X POST -d "X-API-KEY=########&did_id=417&customer_type=BUS&company_name=ChainSolutions&house_number=12&house_number_suffix=2&street_name=street_name&street_name_suffix=ave&county_id=225&state_abbreviation=TX&locality=Houston&zip=77298&additional_info=TestRequest" http://sandbox.chainsolutions.net/voip/v1/did_e911_us_request

Parameters

$did_id

int

int(11) get from DID GET method

$customer_type

string

varchar(3) Identifier of the customer types. Pass 'RES' for Residential customer and 'BUS' for Business.

$first_name

string

varchar(20) First Name of customer. Optional for Business customers.

$last_name

string

varchar(50) Last Name of customer. Do not pass if you want to provide 'company_name' for Business Customers.

$title

string

varchar(3) Allowed values are 'Mr', 'Mrs', 'Ms'

$company_name

string

varchar(100) Company name of business customer ('BUS'). Do not pass if you want to provide 'last_name' for Business customer OR when 'customer_type' is 'RES'.

$house_number

int

int(10) Identifies the house on a street

$house_number_suffix

int

varchar(10) (optional) Flat number/floor

$street_name

string

varchar(20) Identifies the house on a street

$street_name_suffix

string

varchar(10) (optional) Street abbreviation, as defined by the U.S. Postal Service Publication 28 (e.g., AVE).

$locality

string

varchar(25) Town or city name.

$county_id

int

int(11) Get from DID E911 US Counties GET

$state_abbreviation

string

varchar(2) Get from DID E911 US States GET

$zip

string

varchar(20) The postal code (ZIP) for your area.

$additional_info

string

varchar(20) (optional) Pass any additional address or client information here

Exceptions

array {"status":"error","error_code":"400","message":"There was a problem retrieving E911 US States information. Please try again","data":null}
array {"status":"error","error_code":"400","message":"Selected 'did_id' already has E911 service enabled","data":null}
array {"status":"error","error_code":"400","message":"The 'did_id' you passed does not belong to you or a client of yours","data":null}
array {"status":"error","error_code":"400","message":"The 'state_abbreviation' you passed is invalid","data":null}
array {"status":"error","error_code":"400","message":"The 'county_id' you passed is invalid","data":null}
array {"status":"error","error_code":"400","message":"E911 US Request already created for this DID. Please wait for the previous request to get Approved","data":null}
array {"status":"error","error_code":"400","message":"Your DID is not active. Please pay your Billing Subscription","data":null}
array {"status":"error","error_code":"400","message":"The 'did_id' you passed does not belong to you or any of your customers!","data":null}
array {"status":"error","error_code":"400","message":"The 'did_id' you passed is not one of a US number! All US DIDs should start with 001","data":null}
array {"status":"error","error_code":"400","message":"Please provide only 'company_name' or 'last_name' for business clients","data":null}
array {"status":"error","error_code":"500","message":"Could not create provisioning file. Please try again","data":null}
array {"status":"error","error_code":"500","message":"Could not upload file to database","data":null}
array {"status":"error","error_code":"500","message":"Unable to update the status of your request","data":null}
array {"status":"error","error_code":"500","message":"Unable to send your request for E911 service. Please try again","data":null}

Returns

array{"status":"success","message":"Your request was successfully created and is waiting for processing and approval","data":{"did_e911_request_id":"int(11)"}}

DID E911 US Request PUT

API

Edit the information provided for a DID's E911 Service in the US.
E911 Service should already be active on this DID.

api curl -k -i -H "Accept: application/json" -X POST -d "X-API-KEY=########&customer_type=BUS&company_name=ChainSolutions&house_number=12&house_number_suffix=2&street_name=street_name&street_name_suffix=ave&county_id=225&state_abbreviation=TX&locality=Houston&zip=77298&additional_info=TestRequest" http://sandbox.chainsolutions.net/voip/v1/did_e911_us_request

Parameters

$did_id

int

int(11) The ID of the DID for which you want to update the E911 US Service Information. Get from DID GET method

$customer_type

string

varchar(3) Identifier of the customer types. Pass 'RES' for Residential customer and 'BUS' for Business.

$first_name

string

varchar(20) First name of customer. Optional for Business customers.

$last_name

string

varchar(50) Last name of customer. Do not pass if you want to provide 'company_name' for Business Customers.

$title

string

varchar(3) Allowed values are 'Mr', 'Mrs', 'Ms'

$company_name

string

varchar(100) Company name of business customer ('BUS'). Do not pass if you want to provide 'last_name' for Business customer OR when 'customer_type' is 'RES'.

$house_number

int

int(10) Identifies the house on a street

$house_number_suffix

int

varchar(10) (optional) Flat number/floor

$street_name

string

varchar(20) Identifies the house on a street

$street_name_suffix

string

varchar(10) (optional) Street abbreviation, as defined by the U.S. Postal Service Publication 28 (e.g., AVE).

$locality

string

varchar(25) Town or city name.

$county_id

int

int(11) Get from DID E911 US Counties GET

$state_abbreviation

string

varchar(2) Get from DID E911 US States GET

$zip

string

varchar(20) The postal code (ZIP) for your area.

$additional_info

string

varchar(20) (optional) Pass any additional address or client information here

Exceptions

array {"status":"error","error_code":"400","message":"Selected 'did_id' does not have E911 services enabled. You cannot edit the information before it is enabled","data":null}
array {"status":"error","error_code":"400","message":"Selected 'did_id' doest not exist","user_message":"Selected DID does not exist in our database","data":null}
array {"status":"error","error_code":"400","message":"The 'state_abbreviation' you passed is invalid","data":null}
array {"status":"error","error_code":"400","message":"The 'county_id' you passed is invalid","data":null}
array {"status":"error","error_code":"400","message":"Selected 'did_id' does not have an 'Approved' Request for E911 services. Please wait for the request to be 'Approved'","user_message":"E911 Service address approval is pending for verification","data":null}
array {"status":"error","error_code":"400","message":"There was a problem retrieving E911 US States information. Please try again","data":null}
array {"status":"error","error_code":"400","message":"The 'did_id' you passed does not belong to you or a client of yours","data":null}
array {"status":"error","error_code":"400","message":"Please provide only 'company_name' or 'last_name' for business clients","data":null}
array {"status":"error","error_code":"500","message":"Could not create provisioning file. Please try again","data":null}
array {"status":"error","error_code":"500","message":"Could not upload file to database","data":null}
array {"status":"error","error_code":"500","message":"Unable to update the status of your request","data":null}
array {"status":"error","error_code":"500","message":"Unable to send your Request for Update of E911 service. Please try again","data":null}

Returns

array{"status":"success","message":"Your E911 US Update Request was successfully created and is waiting for processing and approval","data":{"did_e911_request_id":"int(11)"}}

DID E911 US States GET

API

Get a list of the states in the USA. Used in DID E911 US Request POST

api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=########" http://sandbox.chainsolutions.net/voip/v1/did_e911_us_states

Exceptions

array {"status":"error","error_code":"400","message":"There was a problem retrieving E911 US States information. Please try again","data":null}

Returns

array{"status":"success","message":"E911 US States retrieved successfully","data":[{"state_id":"int(2)","state_abbreviation":"varchar(2)","state_name":"varchar(50)","state_code":"varchar(2)"}]}

DID GET

API

Get all DIDs for an Account. You will also get information about their Billing Subscription details.
Billing Subscription's Price is returned in the current currency of the account.
If 'did_id' is passed you will also receive information about DID's E911 Requests - then returned 'did_e911_requests' index.

api http://sandbox.chainsolutions.net/voip/v1/did
api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=########&accountcode=########" http://sandbox.chainsolutions.net/voip/v1/did

Parameters

$accountcode

string

varchar(20) (optional) If you want to get the DIDs of a client of yours

$did_id

int

int(11) (optional) If you want to get a particular DID only

$offset

int

int(10) (optional) default is '0', which element to start the pagination from.

$limit

int

int(2) (optional) default and max is 20, how many records you want to display on a page.

$hk_dids

int

int(1) (optional) if '1' is passed only Honk Kong DIDs will be retrieved. This will soon be replaced with a more scalable alternative

Exceptions

array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"The 'did_id' passed does not exist or belong to selected account","data":null}

Returns

array{"status":"success","message":"DIDs retrieved successfully","data":[{"did_id":"int(11)","did_number":"varchar(20)","prefix":"varchar(20)","inbound_call_recording":"int(1)","billing_subscription_id":"int(11)","billing_subscription_description":"varchar(200)","billing_subscription_price":"decimal(10,5) the price end users pay","billing_subscription_buy_price":"decimal(10,5) the price Reseller pays back to Chain Solutions","has_e911":"int(1)","country_code":"varchar(3)","dial_prefix":"varchar(10)","route":"varchar(50)","route_type":"varchar(30)","extension_id":"int(11) returned only when 'route_type' is 'extension'","sip_address":"varchar(255) returned only when 'route_type' is 'extension'","did_e911_requests":[{"did_e911_request_id":"int(11)","transaction_type":"NEW|CHANGE|CANCEL","status":"varchar(20)"}]}]}
array{"status":"success","message":"No DIDs found for selected account!","data":null}

DID Order POST

API

Order DID based on input from DID Search GET. If your client has not prepaid (with a Billing Subscription) for the DID they will he billed on their Billing Profile. If they don't have a Billing Subscription or Billing Profile they won't be able to buy the DID.
If you don't get a proper 'did_number' at the end of this method's execution (one staring with '1205406' no matter what 'city_id' you passed) on the sandbox environment, this means we did not get a proper response from our DID provider's API. Contact us directly if you want to test this method without this constraint as we might have to do some manual steps.

api curl -k -i -H "Accept: application/json" -X POST -d "X-API-KEY=##########&accountcode=###########&country_code=USA&state_id=10&city_id=10979&custom_package_id=19&payment_type=2" http://sandbox.chainsolutions.net/voip/v1/did_order

Parameters

$accountcode

string

varchar(20) (optional) if not passed you will buy a DID with your own Account

$custom_package_id

int

int(11) returned from the Custom Package GET method, the user will be subscribed to this Custom Package

$did_type_id

int

int(2) (optional) default is '1', returned from the DID Search GET method

$country_code

string

varchar(3) (optional) (required if $did_type_id equals '1') returned from the DID Countries List GET method

$state_id

int

int(11) (optional) (required if $did_type_id equals '1' and selected Country has States) returned from the DID States List GET method

$city_id

int

int(11) (optional) (required if $did_type_id equals '1') returned from the DID Search GET method

$did

string

varchar(20) (optional) (required if $did_type_id equals '3') returned from the DID Search GET method

$payment_type

int

int(1) (optional) default is '1' - pay for DID with Call Credit, '2' - pay with Credit Card already registered and approved, client needs to have a Billing Profile

$sip_address

string

varchar(255) (optional) example: '557203765@infocus.net'. If this parameter is passed the DID bought will be linked to an User Extension with this sip_address. If such a User Extension already exists it will be used, if not a new one will be created. If DID Custom Package has included minutes we will not let you use the same sip_address more than once. Have in mind that if a Billing Subscription including a free DID in the selected Country is active on the account you don't need to pass the 'sip_address' as the Billing Subscription already has an User Extension associated

$present_caller_id

int

int(1) (optional) default is '0' - do not present a Caller Id, '1' - present Caller Id, if '1' is passed you need to pass 'sip_address' as well or we will not know on which Extension to enable the Caller ID. If '1' is passed we will also create the default Caller ID Mask of '00' (dialing all numbers) so you don't have to use User Extension Caller Id POST.

Exceptions

array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"sip_address must be set when present_caller_id=1","data":null}
array {"status":"error","error_code":"400","message":"The sip_address you passed already has a DID with free minutes subscription associated. Please use another sip_address.","user_message":"Sorry, you can't have more than one PSTN number on the same device!","data":null}
array {"status":"error","error_code":"400","message":"The 'custom_package_id' you passed is either invalid or does not belong to you!","data":null}
array {"status":"error","error_code":"400","message":"The 'custom_package_id' you passed is not one for buying DIDs! Please pass a proper 'custom_package_id'","data":null}
array {"status":"error","error_code":"400","message":"The 'custom_package_id' you passed is for purchasing US numbers only! Please pass 'country_code'=USA","data":null}
array {"status":"error","error_code":"400","message":"The 'custom_package_id' you passed is for purchasing Canada numbers only! Please pass 'country_code'=CAN","data":null}
array {"status":"error","error_code":"400","message":"country_code must be set","data":null}
array {"status":"error","error_code":"422","message":"country_code 'country_code' passed is not valid! Please check the DID Countries List GET method","data":null}
array {"status":"error","error_code":"422","message":"state_id 'X' passed is not associated to country_code 'X'! Please check the DID States List GET method","data":null}
array {"status":"error","error_code":"400","message":"state_id must be set for 'country_name' with country_code 'country_code'!","data":null}
array {"status":"error","error_code":"500","message":"Cannot retrieve countries list now. Please try again later","data":null}
array {"status":"error","error_code":"400","message":"city_id must be set when did_type_id equals '1'","user_message":"Please choose City","data":null}
array {"status":"error","error_code":"400","message":"did must be set when did_type_id equals '3'","user_message":"Please provide DID Number","data":null}
array {"status":"error","error_code":"422","message":"did_type_id should only be '1' or '3'!","data":null}
array {"status":"error","error_code":"422","message":"city_id 'X' passed is not associated to country_code 'X'! Please check the DID Search GET method","data":null}
array {"status":"error","error_code":"422","message":"city_id 'X' passed is not associated to country_code 'X' and state_id 'X'! Please check the DID Search GET method","data":null}
array {"status":"error","error_code":"400","message":"You have to create a custom package ID that uses system_package_id: 'X'","data":null}
array {"status":"error","error_code":"403","message":"There was a problem creating a billing subscription for your DID!","data":null}
array {"status":"error","error_code":"504","message":"A timeout error occurred. We could not retrieve the requested data. Please try again later","data":{"seconds_elapsed":"decimal(2,10)"}}
array {"status":"error","error_code":"500","message":"There was a problem ordering DID!","data":null}

Returns

array{"status":"success","message":"DID ordered successfully","data":{"did_id":"int(11)","did_number":"varchar(20)","country_code":"varchar(3)","dial_prefix":"varchar(10)","invoice_no":"varchar(20) will not return variable if Billing Subscription for free DID in this country was created previously","reseller_invoice_no":"varchar(20) return only when an additional invoice was issued on the Reseller Account","billing_subscription_id":"int(11)","extension_id":"int(11) will not return variable if Billing Subscription for free DID in this country was created previously
or if sip_address was passed","extension":"int(20) if sip_address was passed"}}

DID PUT

API

Change the details of a certain DID. You cannot change DIDs Billing Subscription details from here

api curl -k -i -H "Accept: application/json" -X PUT -d "X-API-KEY=########&accountcode=########$did_id=213" http://sandbox.chainsolutions.net/voip/v1/did

Parameters

$did_id

int

int(11)

$accountcode

string

varchar(20) (optional) If you want to edit a DID that belongs to a client of yours

$prefix

string

varchar(20) (optional)

$inbound_call_recording

int

varchar(20) (optional) Pass '1' if you want to enable Inbound recording of calls, pass '0' to disable. Storing and downloading Call Recordings are charged additionally

$sip_address

string

varchar(255) (optional) Route DID to a SIP address

$phone_number

string

varchar(20) (optional) Route DID to an external Phone Number. It will be 'normalized' to international standards with leading zeroes (example: 00448445025003)

$extension

string

varchar(30) (optional) Route DID to an Extension. Pass the extension number here, example '5541000'. You can get the 'extension' from the User Extension GET method

$extension_id

int

varchar(30) (optional) Do not pass together with 'extension'. Route DID to an Extension. You can get the 'extension_id' from the User Extension GET method

$queue_id

int

int(11) (optional) Route DID to a Queue. Pass the 'queue_id' returned from Queue GET method

$ivr_id

int

int(11) (optional) Route DID to an IVR. Pass the 'irv_id' returned from IVR GET method

$recording_id

int

int(11) (optional) Route DID to a pre-recorded Recording.

$remove_routing

int

int(1) (optional) Pass '1' if you want to remove routing from DID

$create_extension

int

int(1) (optional) pass '1' to create/update a User Extension and automatically route the DID to it. 'sip_address' parameter is required when this is passed, if Extension already exists it's SIP address will be overriden with the new one. You can use it in case you did not pass 'sip_address' to DID Order POST and want to achieve the same. Have in mind US DIDs with free minutes always have Extension created when DID is ordered

$present_caller_id

int

int(1) (optional) if '1' is passed you need to pass 'sip_address' as well or we will not know on which Extension to enable the Caller ID. If '1' is passed we will also create the default Caller ID Mask of '00' (dialing all numbers) so you don't have to use User Extension Caller Id POST.

Exceptions

array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"Wrong did_id or DID does not belong to selected account","user_message":"The DID does not belong to this account","data":null}
array {"status":"error","error_code":"400","message":"You need to have Hosted PBX functionality enabled for this Account in order to route to a Phone Number, Queue or IVR. You can change this from the Account PUT method","data":null}
array {"status":"error","error_code":"400","message":"Please pass only one routing option! You should pass ONE of those: 'sip_address', 'phone_number', 'extension', 'queue_id', 'ivr_id', 'recording_id'!","data":null}
array {"status":"error","error_code":"400","message":"sip_address and create_extension must be set when present_caller_id=1","data":null}
array {"status":"error","error_code":"400","message":"The sip_address you passed already has a DID with free minutes subscription associated. Please use another sip_address.","user_message":"Sorry, you can't have more than one PSTN number on the same device!","data":null}
array {"status":"error","error_code":"400","message":"The 'extension' you passed 'X' is not valid or does not belong to selected user","data":null}
array {"status":"error","error_code":"400","message":"The 'extension_id' you passed 'X' is not valid or does not belong to selected user","data":null}
array {"status":"error","error_code":"400","message":"The 'queue_id' you passed 'X' is not valid or does not belong to selected user","data":null}
array {"status":"error","error_code":"400","message":"The 'ivr_id' you passed 'X' is not valid or does not belong to selected user","data":null}
array {"status":"error","error_code":"400","message":"The 'recording_id' you passed 'X' is not valid or does not belong to selected user","data":null}
array {"status":"error","error_code":"400","message":"Please pass any parameters to update DID","data":null}
array {"status":"error","error_code":"400","message":"sip_address needs to be passed when create_extension=1","data":null}
array {"status":"error","error_code":"500","message":"Could not update DID right now! Please try again","data":null}

Returns

array{"status":"success","message":"DID updated successfully","data":null}

DID Search GET

API

Get list of available DIDs or list of cities for a particular country and state. For US and UK you will get a list of DIDs, for all other countries - list of cities, the ID of which you should pass to DID Order POST.

api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=##########&country_code=USA&state_id=10" http://sandbox.chainsolutions.net/voip/v1/did_search

Parameters

$country_code

string

varchar(3) returned from the DID Countries List GET method

$state_id

int

int(11) (optional) returned from the DID States List GET method

$area_code

string

varchar(6) (optional) (default is '01245') use this only if 'country_code' = 'GBR' (United Kingdom). Returned from DID UK Area Codes GET method. Use the returned 'area_code' index here.

Exceptions

array {"status":"error","error_code":"400","message":"country_code must be set","data":null}
array {"status":"error","error_code":"422","message":"country_code 'country_code' passed is not valid! Please check the DID Countries List GET method","data":null}
array {"status":"error","error_code":"422","message":"state_id 'X' passed is not associated to country_code 'X'! Please check the DID States List GET method","data":null}
array {"status":"error","error_code":"400","message":"state_id must be set for 'country_name' with country_code 'country_code'!","data":null}
array {"status":"error","error_code":"504","message":"A timeout error occurred. We could not retrieve the requested data. Please try again later","data":{"seconds_elapsed":"decimal(2,10)"}}
array {"status":"error","error_code":"500","message":"Cannot retrieve countries list now. Please try again later","data":null}

Returns

array{"status":"success","message":"Cities retrieved successfully","data":{"cities":{"city_id":"int(11)","city_name":"varchar(40)","area_code":"int(5)","available_dids":"int(10)","proof_required":"boolean","address_type":"boolean/string"},"did_type_id":"1"}}
array{"status":"success","message":"Available DIDs retrieved successfully","data":{"available_dids":["varchar(20)"],"did_type_id":"2 or 3"}}

DID States List GET

API

Get list of States for a particular Country (that has states)

api http://sandbox.chainsolutions.net/voip/v1/did_states_list/country_code/USA
api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=##########&country_code=USA" http://sandbox.chainsolutions.net/voip/v1/did_states_list

Parameters

$country_code

string

varchar(3) returned from the DID Countries List GET method

Exceptions

array {"status":"error","error_code":"400","message":"country_code must be set","data":null}
array {"status":"error","error_code":"400","message":"'country_name' with country_code 'country_code' has no states!","data":null}
array {"status":"error","error_code":"422","message":"country_code 'country_code' passed is not valid! Please check the DID Countries List GET method","data":null}
array {"status":"error","error_code":"504","message":"A timeout error occurred. We could not retrieve the requested data. Please try again later","data":{"seconds_elapsed":"decimal(2,10)"}}
array {"status":"error","error_code":"500","message":"Cannot retrieve countries list now. Please try again later","data":null}
array {"status":"error","error_code":"500","message":"Cannot retrieve states list now. Please try again later","data":null}

Returns

array{"status":"success","message":"DID States retrieved successfully","data":[{"state_id":"int(5)","state_name":"varchar(40)","state_code":"varchar(3)"}]}

DID Transfer POST

API

Transfer a DID from your Reseller Account to a client account.

When the transfer is completed the client gets charged on their Billing Profile the amount set in the DIDs Billing Subscription. You can get the related Billing Subscription by using the Billing Subscription GET method.
If the returned 'price_client_currency' index is not 0, then the client will be charged this amount in their own currency, otherwise they will be charged the 'price' amount (which is in EUR) converted to their own currency.

api curl -k -i -H "Accept: application/json" -X POST -d "X-API-KEY=##########&client_accountcode=###########&did_id=###" http://sandbox.chainsolutions.net/voip/v1/did_transfer

Parameters

$client_accountcode

string

varchar(20) the Account to transfer the DID to

$did_id

int

int(11) the DID you want to transfer to a client. You can get this value from DID GET method.

$payment_type

int

(optional) default is '1' - pay for DID with Call Credit from Client Account, '2' - pay with Credit Card already registered and approved, client needs to have a Billing Profile

$sip_address

string

varchar(255) (optional) example: '557203765@infocus.net'. If this parameter is passed the DID will be linked to an User Extension with this sip_address. If such a User Extension already exists it will be used, if not a new one will be created.

$present_caller_id

int

int(1) (optional) default is '0' - do not present a Caller Id, '1' - present Caller Id, if '1' is passed you need to pass 'sip_address' as well or we will not know on which Extension to enable the Caller ID. If '1' is passed we will also create the default Caller ID Mask of '00' (dialing all numbers) so you don't have to use User Extension Caller Id POST.

Exceptions

array {"status":"error","error_code":"400","message":"client_accountcode passed either does not exist or does not belong to your account","data":null}
array {"status":"error","error_code":"400","message":"client_accountcode passed either does not exist or does not belong to your account","user_message":"The Account you want to transfer this DID to does no exist or is under your Account","data":null}
array {"status":"error","error_code":"400","message":"client_accountcode is the same as your Reseller Account","user_message":"You cannot transfer DID to yourself","data":null}
array {"status":"error","error_code":"400","message":"sip_address must be set when present_caller_id=1","user_message":"Please enter SIP Address when Present Caller ID is checked","data":null}
array {"status":"error","error_code":"400","message":"The sip_address you passed already has a DID with free minutes subscription associated. Please use another sip_address.","user_message":"Sorry, you can't have more than one PSTN number on the same device!","data":null}
array {"status":"error","error_code":"400","message":"Wrong did_id or DID does not belong to selected account","user_message":"The DID does not belong to this account","data":null}
array {"status":"error","error_code":"400","message":"Selected DID is not active. Please pay for it first before it can be transferred","data":null}
array {"status":"error","error_code":"400","message":"We could not find your DID's Billing Subscription. Please let us know about this","data":null}

Returns

array{"status":"success","message":"DID transferred successfully","data":{"invoice_no":"varchar(20)","reseller_invoice_no":"varchar(20)","extension_id":"int(11) returned only when sip_address is passed","extension":"varchar(20) returned only when sip_address is passed"}}

DID UK Area Codes GET

API

Get a list of UK Area Codes. You will need the 'area_code' index in DID Search GET

api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY="########" http://sandbox.chainsolutions.net/voip/v1/did_uk_area_codes

Exceptions

array {"status":"error","error_code":"500","message":"There was a problem retrieving UK Area Codes. Please try again","data":null}

Returns

\array{"status":"success","message":"UKArea Codes retrieved successfully","data":[{"area_code":"varchar(6)","area_name":"varchar(50)"}]}

Domain Check GET

API

Check if domain is available for purchase and how much it costs for an year.

api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=########&keyword=domain_name" http://sandbox.chainsolutions.net/voip/v1/domain_check

Parameters

$keyword

string

varchar(60) the domain name you are looking for

$tlds

array

of Top Level Domain (tld) names ('com', 'net', etc) you want to search for. If omitted you will get results for the most popular tld-s

Exceptions

array {"status":"error","error_code":"500","message":"Couldn't check domain availability right now! Please try again!","data":null}

Returns

array{"status":"success","message":"Domain Check retrieved successfully","data":[{"keyword.tld":{"avail":"boolean","tld":"varchar(10)","price":"decimal(5,2)","premium":"boolean"}}]}

Domain Contacts PUT

API

Update Contact Information for a specific domain

api curl -k -i -H "Accept: application/json" -X PUT -d "X-API-KEY=########&accountocde=########&domain_name=test_domain.com" http://sandbox.chainsolutions.com/voip/v1/domain_contacts

Parameters

$domain_name

string

the name of the domain which contacts you want to update example: 'chainsolutions.net'

$first_name

string

varchar(100) Registrant Data - First Name

$last_name

string

varchar(100) Registrant Data - Last Name

$organization

string

varchar(50) Registrant Data - Organization

$address_1

string

varchar(100) Registrant Data - Address Line 1

$address_2

string

varchar(100) (optional) Registrant Data - Address Line 2

$city

string

varchar(50) Registrant Data - City

$state

string

varchar(50) Registrant Data - State

$zip

string

varchar(20) Registrant Data - ZIP

$country

string

varchar(30) Registrant Data - Country

$phone

string

varchar(20) Registrant Data - Phone

$fax

string

varchar(20) Registrant Data - Fax

$email

string

varchar(50) Registrant Data - Email

$accountcode

string

varchar(20) (optional) if not passed will add the domains to our own account

Exceptions

array {"status":"error","error_code":"500","message":"There was a problem connecting to the remote API! Please try again!","data":null}

Returns

\array{"status":"success","message":"Contactinformation updated successfully!","data":null}

Domain Details GET

API

Get information for a specific domain

api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=########&domain_name=test_domain.com&accountcode=########" http://sandbox.chainsolutions.com/voip/v1/domain_details

Parameters

$domain_name

string

the name of the domain tou want to get details for example: 'chainsolutions.net'

$accountcode

string

varchar(20) (optional) if not passed will get the details for domain from your own account

Exceptions

array {"status":"error","error_code":"500","message":"There was a problem retrieving this domain\'s information! Please try again!","data":null}

Returns

array{"status":"success","message":"Information for 'domain_name' retrieved successfully!","data":{"domain_name":"varchar(60)","create_date":"datetime","expire_date":"datetime","nameservers":["varchar(50)","varchar(50)","varchar(50)","varchar(50)"],"whois_privacy":{"enabled":"int(1)","expire_date":"datetime"},"contacts":{"first_name":"varchar(50)","last_name":"varchar(50)","organization":"varchar(50)","address_1":"varchar(50)","address_2":"varchar(50)","city":"varchar(40)","state":"varchar(40)","zip":"varchar(20)","country":"varchar(50)","phone":"varchar(20)","fax":"varchar(20)","email":"varchar(70)"},"addons":{"domain_renew":{"price":"decimal(5,2)"},"whois_privacy_renew":{"price":"decimal(5,2)"}}}}

Domain GET

API

Get all domains linked to an account.

api http://sandbox.chainsolutions.net/voip/v1/domain
api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=########&accountcode=########" http://sandbox.chainsolutions.net/voip/v1/domain

Parameters

$accountcode

string

varchar(20) (optional) if not passed will retrieve domains for your own account

Exceptions

array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}

Returns

array{"status":"success","message":"Domains retrieved successfully","data":[{"domain_id":"int(11)","domain_name":"varchar(60)","tld":"varchar(10)","locked":"int(1)","whois_privacy":"int(1)","whois_privacy_expire_date":"datetime","expire_date":"datetime"}]}
array{"status":"success","message":"You have no domains yet","data":null}

Domain POST

API

Register and buy a domain for a particular number of years. You can also add whois privacy to the domain. You can check if the domain is available for purchase and its yearly price form the Domain Check GET method. If the purchase is successfull an invoice will be generated.

api curl -k -i -H "Accept: application/json" -X POST -d "X-API-KEY=########&accountcode=########&domain_name=test_domain.com&period=1" http://sandbox.chainsolutions.net/voip/v1/domain

Parameters

$domain_name

string

the domain name you want to buy, including tlds, example: 'chainsolutions.net'

$first_name

string

varchar(100) Registrant Data - First Name

$last_name

string

varchar(100) Registrant Data - Last Name

$organization

string

varchar(50) Registrant Data - Organization

$address_1

string

varchar(100) Registrant Data - Address Line 1

$address_2

string

varchar(100) (optional) Registrant Data - Address Line 2

$city

string

varchar(50) Registrant Data - City

$state

string

varchar(50) Registrant Data - State

$zip

string

varchar(20) Registrant Data - ZIP

$country

string

varchar(30) Registrant Data - Country

$phone

string

varchar(20) Registrant Data - Phone

$fax

string

varchar(20) Registrant Data - Fax

$email

string

varchar(50) Registrant Data - Email

$period

int

(optional) default is '1', this is the number of years you want to buy the domain for

$whois_privacy

int

(optional) default is '0', meaning you don't want to buy whois privacy for the domain right now, pass '1' if you want to add whois privacy as well

$accountcode

string

varchar(20) (optional) if not passed will add the domains to our own account

Exceptions

array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"'domain_name' is already registered in our system!","data":null}
array {"status":"error","error_code":"500","message":"There was a problem registering 'domain_name'! Please try again!","data":null}

Returns

array{"status":"success","message":"'domain_name' registered successfully for 'X' years! You were billed 'X' 'currency' for this with invoice No ########.","data":{"invoice_no":"int(15)","domain_id":"int(11)"}}

Domain Renew POST

API

Renew a specific domain for a particular number of years

api curl -k -i -H "Accept: application/json" -X POST -d "X-API-KEY=########&accountcode=########&domain_name=test_domain.com&period=1" http://sandbox.chainsolutions.net/voip/v1/domain_renew

Parameters

$domain_name

string

the name of the domain you want to renew

$accountcode

string

varchar(20) (optional) if the domain belongs to a client of yours

$period

int

(optional) default is '1', this is the number of years you want to renew the domain for

Exceptions

array {"status":"error","error_code":"500","message":"There was a problem renewing 'domain_name'! Please try again!","data":null}

Returns

array{"status":"success","message":"'domain_name' renewed successfully for 'X' years! You were billed 'X' 'currency' for this with invoice No ########.","data":{"invoice_no":"int(15)"}}

Domain Whois POST

API

Add a Whois Privacy for a specific domain for a specific number of years

api curl -k -i -H "Accept: application/json" -X POST -d "X-API-KEY=#####&domain_name=test_domain.com&period=1" http://sandbox.chainsolutions.com/voip/v1/domain_whois

Parameters

$domain_name

string

the name of the domain you want to add Whois Privacy on

$accountcode

string

varchar(20) (optional) if the domain belongs to a client of yours

$period

int

(optional) default is '1', this is the number of years you want to add Whois Privacy for the domain

Exceptions

array {"status":"error","error_code":"400","message":"Your Whois Privacy has not expired yet. Please use Domain Whois Renew POST method instead","data":null}
array {"status":"error","error_code":"500","message":"There was a problem adding Whois Privacy on 'domain_name'! Please try again!","data":null}

Returns

array{"status":"success","message":"Whois Privacy added successfully on 'domain_name' for 'X' years! You were billed 'X' 'currency' for this with invoice No ########.","data":{"invoice_no":"int(15)"}}

Domain Whois Renew POST

API

Renew Whois Privacy for a specific domain

api curl -k -i -H "Accept: application/json" -X POST -d "X-API-KEY=########&accountcode=#######&domain_name=test_domain.com&period=1" http://sandbox.chainsolutions.com/voip/v1/domain_whois_renew

Parameters

$domain_name

string

the name of the domain you want to renew Whois Privacy on

$accountcode

string

varchar(20) (optional) if the domain belongs to a client of yours

$period

int

(optional) default is '1', this is the number of years you want to renew Whois Privacy for the domain

Exceptions

array {"status":"error","error_code":"400","message":"You haven\'t added Whois Privacy to 'domain_name' Please use Domain Whois POST method instead","data":null}
array {"status":"error","error_code":"400","message":"Domain 'domain_name' expires on 'datetime'. Please renew your domain first","data":null}
array {"status":"error","error_code":"500","message":"There was a problem adding Whois Privacy on 'domain_name'! Please try again!","data":null}

Returns

array{"status":"success","message":"Whois Privacy renewed successfully on 'domain_name' for 'X' years! You were billed 'X' 'currency' for this with invoice No ########.","data":{"invoice_no":"int(15)"}}

IP Address White List DELETE

API

Delete IP address and associated details from the API White List

api curl -k -i -H "Accept: application/json" -X DELETE -d "X-API-KEY=########&ip_address_id=11" http://sandbox.chainsolutions.net/voip/v1/ip_address_white_list

Parameters

$accountcode

string

varchar(20) (optional) If you want to delete an IP address that belongs to a client of yours

$ip_address_id

int

int(11)

Exceptions

array {"status":"error","error_code":"400","message":"ip_address_id must be set","data":null}
array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"Wrong ip_address_id! You are trying to modify a record that does not exist or does not belong to you","data":null}
array {"status":"error","error_code":"500","message":"Could not delete IP address at this time","data":null}

Returns

array{"status":"success","message":"IP Address deleted successfully","data":null}

IP Address White List GET

API

Get a list of all IP addresses from the API White List

api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=########" http://sandbox.chainsolutions.net/voip/v1/ip_address_white_list

Parameters

$accountcode

string

varchar(20) (optional) If you want to view all IP addresses that belongs to a client of yours

$ip_address_id

int

int(11) (optional) return a single IP Address

Exceptions

array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"Selected client does not have X-API-KEY yet! Please request one for them first!","data":null}
array {"status":"error","error_code":"500","message":"Could not retrieve IP addresses related to this account! Please try again","data":null}

Returns

array{"status":"success","message":"White Listed IP Addresses retrieved successfully","data":{"ip":"varchar(20)","description":"varchar(50)"}}
array{"status":"success","message":"No White Listed IP Addresses found for this account","data":null}

IP Address White List POST

API

Add an IP address to the white list. You can access the API only from the white listed IP addresses

api curl -k -i -H "Accept: application/json" -X POST -d "X-API-KEY=########&ip=10.10.10.10" http://sandbox.chainsolutions.net/voip/v1/ip_address_white_list

Parameters

$accountcode

string

varchar(20) (optional) If you want to add an IP address to the white list for a client of yours

$ip

string

varchar(20)

$description

string

varchar(50) (optional)

Exceptions

array {"status":"error","error_code":"400","message":"ip must be set","data":null}
array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"Selected client does not have X-API-KEY yet! Please request one for them first!","data":null}
array {"status":"error","error_code":"400","message":"Invalid IP address. Please enter a valid IPv4 IP address!","data":null}
array {"status":"error","error_code":"400","message":"You have already added this IP address to the white list for this account!","data":null}
array {"status":"error","error_code":"500","message":"Could not add IP address at this time","data":null}

Returns

array{"status":"success","message":"IP Address added successfully","data"{"ip_address_id":"int(11)"}}

IP Address White List PUT

API

Change IP address or its details in the API White List

api curl -k -i -H "Accept: application/json" -X PUT -d "X-API-KEY=########&ip_address_id=12&ip=11.11.11.11&description=some_text" http://sandbox.chainsolutions.net/voip/v1/ip_address_white_list

Parameters

$accountcode

string

varchar(20) (optional) If you want to edit an IP address that belongs to a client of yours

$ip_address_id

int

int(11)

$ip

string

varchar(20) (optional)

$description

string

varchar(50) (optional)

Exceptions

array {"status":"error","error_code":"400","message":"ip_address_id must be set","data":null}
array {"status":"error","error_code":"400","message":"You must pass a 'description' or 'ip' to change!","data":null}
array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"403","message":"Selected client does not have X-API-KEY yet! Please request one for them first!","data":null}
array {"status":"error","error_code":"400","message":"Invalid IP address. Please enter a valid IPv4 IP address!","data":null}
array {"status":"error","error_code":"400","message":"You have already added this IP address to the white list for this account!","data":null}
array {"status":"error","error_code":"400","message":"Wrong ip_address_id! You are trying to modify a record that does not exist!","data":null}
array {"status":"error","error_code":"500","message":"Could not update IP address at this time","data":null}

Returns

array{"status":"success","message":"IP Address updated successfully","data":null}

IP Shield Check Address GET

API

Check to see if an IPv4 IP Address is in our IP Address Black List (IP Shield). This should be used in case a Device of yours was accidentally added to the IP Shield because it tried to connect to our network in a wrong way. If the IP Address exists in our IP Shield you will get 'true' in the 'data' part of the response, otherwise 'data' will be 'false'

api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=########&ip=10.10.10.10" http://sandbox.chainsolutions.net/voip/v1/ip_shield_check_address

Parameters

$ip

string

varchar(20) example format: 10.10.10.10

Exceptions

array {"status":"error","error_code":"422","message":"'ip' is invalid. Please enter a valid IPv4 IP Address!","user_message":"Please enter a valid IPv4 IP Address!","data":null}

Returns

array{"status":"success","message":"'X' IPv4 Address you passed is not part of our IP Shield","user_message":"'X' IPv4 Address is not in our IP Shield. This means it is not Blacklisted.","data":false}
array{"status":"success","message":"'X' IPv4 Address you passed exists in our IP Shield. You can temporarily remove it using IP Address Black List Remove POST method","user_message":"'X' IPv4 Address you passed exists in our IP Shield so it is Blacklisted","data":true}

IP Shield Blacklist GET

API

Returns a full list of IP addresses blacklisted by our system, the server that blacklisted them ('source_ip' parameter) and the reason for the blacklisting. Have in mind older blacklisted IP addresses will hold no additional information except for the IP address itself.

api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=########" http://sandbox.chainsolutions.net/voip/v1/ip_shield_blacklist

Parameters

$ip

string

varchar(20) example format: 10.10.10.10

$offset

int

int(10) (optional) default is '0', which element to start the pagination from.

$limit

int

int(2) (optional) default and max is 20, how many records you want to display on a page.

Exceptions

array {"status":"error","error_code":"422","message":"'ip' is invalid. Please enter a valid IPv4 IP Address!","user_message":"Please enter a valid IPv4 IP Address!","data":null}
array {"status":"error","error_code":"400","message":"The maximum 'limit' you can pass to this method is '50'!","data":null}

Returns

array{"status":"success","message":"'X' IPv4 Address you passed is not part of our IP Shield","user_message":"'X' IPv4 Address is not in our IP Shield. This means it is not Blacklisted.","data":false}
array{"status":"success","message":"Blacklisted IP addresses retrieved successfully","data":[{"banned_ip":"varchar(20)","source_ip":"varchar(20)","reason":"varchar(255)","last_modified":"timestamp"}]}

IP Shield Whitelist GET

API

Returns a full list of IP addresses whitelisted in our system and if the whitelisting is permanent (if 'permanent' flag is '1'). If the whitelisted address is not 'permanent' it will be deleted after one hour.

api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=########" http://sandbox.chainsolutions.net/voip/v1/ip_shield_whitelist

Parameters

$ip

string

varchar(20) example format: 10.10.10.10

$offset

int

int(10) (optional) default is '0', which element to start the pagination from.

$limit

int

int(2) (optional) default and max is 20, how many records you want to display on a page.

Exceptions

array {"status":"error","error_code":"422","message":"'ip' is invalid. Please enter a valid IPv4 IP Address!","user_message":"Please enter a valid IPv4 IP Address!","data":null}
array {"status":"error","error_code":"400","message":"The maximum 'limit' you can pass to this method is '50'!","data":null}

Returns

array{"status":"success","message":"'X' IPv4 Address you passed is not whitelisted","data":false}
array{"status":"success","message":"Witelisted IP addresses retrieved successfully","data":[{"ip":"varchar(20)","permanent":"int(1)","last_modified":"timestamp"}]}

IP Shield Remove Address POST

API

If an IP Address is part of our IP Shield you can temporarily remove it form there.

api curl -k -i -H "Accept: application/json" -X POST -d "X-API-KEY=########&ip=10.10.10.10" http://sandbox.chainsolutions.net/voip/v1/ip_shield_remove_address

Parameters

$ip

string

varchar(20) example format: 10.10.10.10

Exceptions

array {"status":"error","error_code":"422","message":"'ip' is invalid. Please enter a valid IPv4 IP Address!","user_message":"Please enter a valid IPv4 IP Address!","data":null}
array {"status":"error","error_code":"400","message":"'X' IPv4 Address you passed is not part of our IP Shield. Please pass an IP Address that is in the IP Shield","data":null}
array {"status":"error","error_code":"400","message":"IP address 'X' was already removed from IP Shield 3 times in the past 48 hours. This is now reported to our Support System. If you believe this is an error please contact us directly","data":null}

Returns

array{"status":"success","message":"IPv4 Address successfully removed from IP Shield for one hour. If the reason for being blacklisted is not fixed your IP address will be banned again automatically","message":"IPv4 Address 'X' successfully removed from IP Shield for one hour. If the reason for being blacklisted is not fixed your IP address will be banned again automatically","data":null}

Porting Countries GET

API

Get a list of all Countries you can port numbers to and the approximate time (in business days) that porting takes. All prices are in the returned 'currency'. The 'currency' is the current Currency of your Reseller Account. If price index (geographic_price, national_price, toll_free_price) is set to '0' Porting is unavailable for the corresponding Porting Country and 'porting_number_type'

api http://sandbox.chainsolutions.net/voip/v1/porting_countries/X-API-KEY/########
api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=###############" http://sandbox.chainsolutions.net/voip/v1/porting_countries

Parameters

$country_code

string

varchar(3) (optional) Pass if you want to get Porting Prices for a specific Porting Country.

$porting_number_type

int

int(3) (optional) Pass if you want to get the Porting Countries and related prices for a specific number type:
'1' - Geographic
'2' - Toll Free
'3' - National

Exceptions

array {"status":"error","error_code":"422","message":"country is not properly set! Please use a country from the 'Countries GET' function, using the 'country_code' index","data":null}
array {"status":"error","error_code":"400","message":"Wrong 'country_code' or porting not available for this 'porting_number_type'","data":null}
array {"status":"error","error_code":"500","message":"Could not retrieve Porting Countries right now! Please try again later","data":null}

Returns

array{"status":"success","message":"Porting countries retrieved successfully!","data":{"currency":"varchar(3)","exchange_rate":"decimal(10,5) Exchange rate to EUR","countries":[{"country_code":"varchar(3)","country_name":"varchar(50)","geographic_days":"int(2)","geographic_price":"decimal(10,5)","national_days":"int(2)","national_price":"decimal(10,5)","toll_free_days":"int(2)","toll_free_price":"decimal(10,5)"}]}}

Porting Number DELETE

API

Delete a Porting Number Request. Have in mind that we may not be able to cancel this request if we have already filed it.

api curl -k -i -H "Accept: application/json" -X DELETE -d "X-API-KEY=##########&porting_number_id=2" http://sandbox.chainsolutions.net/voip/v1/porting_number

Parameters

$porting_number_id

int

int(11) returned from Porting Number POST method

Exceptions

array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"The 'porting_number_id' you passed is wrong or does not belong to you","data":null}
array {"status":"error","error_code":"400","message":"Your Porting Number request has a status 'X'. This means you cannot set it for deletion. Only requests with status '0' can be set for deletion","data":{"status":"varchar(10)"}}
array {"status":"error","error_code":"500","message":"There was a problem setting your Porting Number request for deletion","data":null}

Returns

array{"status":"success","message":"Porting Number successfully set for deletion","data":null}

Porting Number GET

API

Get the status and details about all Porting Number Requests created by your Reseller Account.

The possible values of the 'status' variable are:

'Submitted' - request submitted, this is the default status when you have successfully received a 'porting_number_id' from returned from Porting Number POST method
'Sent' - we have already filed your request. If this is the status of your Porting Request then you cannot delete or edit the Request
'Done' - your Porting Number request was successfully fulfilled. The selected Account should already have the DID under their Account. You can get the 'did_id' from this method's response
'Unsuccessful' - your Porting Number request was rejected. Use Porting Number PUT method to edit your request according to the provided reason for rejection. Using the method will resubmit your request with the new values provided
'Cancelled' - you have successfully deleted the Porting Request before we filed it. Porting Number fees are added as Call Credit to your customer's Account.

api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=#########&porting_number_id=2" http://sandbox.chainsolutions.net/voip/v1/porting_number

Parameters

$porting_number_id

int

int(11) (optional) returned from Porting Number POST method. If not passed all Porting Numbers will be retrieved

$offset

int

int(10) (optional) default is '0', which element to start the pagination from.

$limit

int

int(2) (optional) default and max is 20, how many records you want to display on a page.

Exceptions

array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"porting_number_id must be set","data":null}
array {"status":"error","error_code":"400","message":"The 'porting_number_id' you passed is either invalid or does not belong to you","data":null}

Returns

array{"status":"success","message":"Porting Number Requests retrieved successfully!","data":[{"porting_number_id":"int(11)","accountcode":"varchar(20)","payment_type":"int(1)","custom_package_id":"int(11)","sip_address":"varchar(255)","date_submitted":"datetime","date_updated":"datetime","country_code":"varchar(3)","porting_number_type":"int(1)","status":"varchar(10)","reason_for_rejection":"varchar(300) not blank only when status is 'Unsuccessful'","current_provider":"varchar(50)","company_name":"varchar(100)","title":"varchar(10)","first_name":"varchar(100)","last_name":"varchar(100)","street_name":"varchar(50)","building_number":"varchar(10)","city":"varchar(18)","zip":"varchar(20)","country":"varchar(50)","ported_number":"varchar(20)","porting_date":"date","porting_price":"decimal(10,5)","our_porting_price":"decimal(10,5)","invoice_no":"varchar(20)","did_id":"int(11) value will be integer if Porting is completed","extension_id":"int(11) value will be integer if Porting is completed","billing_subscription_id":"int(11) value will be integer if Porting is completed"}]}
array{"status":"success","message":"You don't have Porting Number Requests yet!","data":null}

Porting Number POST

API

Request a Phone Number (DID) to be ported to our System. This request takes a lot of time (up to 45 working days) and requires manual processing, so please be patient. You also need to pass a scanned copy of your Last Invoice with your current provider. Users will be billed on their Billing Profile right away and if for some reason the request cannot be fulfilled (either wrong data was submitted OR request was canceled) the price for the Porting will be refunded as Call Credit.

api curl -k -i -H "Accept: application/json" -X POST -d "X-API-KEY=############&accountcode=8445612299&country_id=30&porting_number_type=1&first_name=Foo&last_name=Bar&address=some_address&contact_name=John&contact_number=18031243242&ported_number=18031243242&pin_code=54798" http://sandbox.chainsolutions.net/voip/v1/porting_number

Parameters

$accountcode

string

varchar(20) (optional) if not passed you will do the request on your own Account, pass it if you want the request to be related to a Client of yours

$custom_package_id

int

int(11) returned from the Custom Package GET method, the Ported Number will be subscribed to this Custom Package

$payment_type

int

int(1) (optional) default is '1' - pay for Porting of Number with Call Credit, '2' - pay with Credit Card already registered and approved, client needs to have an active Billing Profile, '3' - Reseller pays for Porting of number with their own Call Credit (VIP Porting)

$sip_address

string

varchar(255) (optional) if the Porting is successful the DID will be connected to a SIP address, example: '557203765@infocus.net'.

$porting_price

float

decimal(10,5) default is '0' - no money are added on top of our price. The Porting Price in the Currency of your client. Pass this if you want us to charge Your Client on top of our price, returned from Porting Countries GET method

$country_code

string

varchar(3) comes from Porting Countries GET method

$porting_number_type

int

int(1) '1' - geographic, '2' - toll free, '3' - national

$current_provider

string

varchar(50) The name of your current DID provider

$title

string

varchar(10) one of those values - 'Mr', 'Ms', 'Company'

$first_name

string

varchar(100) (optional) First Name as in contract with your current provider. Required if You've passed 'Mr' or 'Ms' for 'title'

$last_name

string

varchar(100) (optional) Last Name as in contract with your current provider. Required if You've passed 'Mr' or 'Ms' for 'title'

$company_name

string

varchar(100) (optional) The name of the Company of the end user. Required if You've passed 'Company' for 'title'

$street_name

string

varchar(50) Street Name as in contract with your current provider

$building_number

string

varchar(10) The number of the building as in contract with your current provider

$city

string

varchar(18) The name of the city in which the end user resides

$zip

string

varchar(20) ZIP of the end user

$country

string

varchar(50) The name of the country in which the end user resides

$ported_number

string

varchar(20) Phone Number to be ported

$porting_date

string

date (optional) The desired porting date, pass in YYYY-MM-DD format

$last_invoice_file

string

A copy of the Last Invoice from the current DID provider

Exceptions

array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"You have already made a Porting Request for this number!","data":{"porting_number_id":"int(11)"}}
array {"status":"error","error_code":"400","message":"The 'custom_package_id' you passed is either invalid or does not belong to you!","data":null}
array {"status":"error","error_code":"400","message":"The 'custom_package_id' you passed is not one for buying DIDs! Please pass a proper 'custom_package_id'","data":null}
array {"status":"error","error_code":"400","message":"The 'country_code' you passed is wrong. Please pass one returned from Porting Countries GET method","data":null}
array {"status":"error","error_code":"400","message":"There is no such service for this Country! Please try another porting_number_type for the same Country!","data":null}
array {"status":"error","error_code":"400","message":"User does not have enough Call Credit to pay for Porting of number","data":{"payment_amount":"decimal(10,5)","currency":"varchar(3)","current_credit":"decimal(10,5)"}}
array {"status":"error","error_code":"400","message":"Reseller Account does not have enough Call Credit to pay for Porting of number","data":{"payment_amount":"decimal(10,5)","currency":"varchar(3)","current_credit":"decimal(10,5)"}}
array {"status":"error","error_code":"400","message":"User doesn't have a Billing Profile created yet! Please create one using the 'Billing Profile POST' method","data":null}
array {"status":"error","error_code":"400","message":"You don't have enough Credit in your Reseller Account to cover this transaction! Please add more credit to your Reseller Account using Billing Payment POST and passing call_credit=1","data":{"current_credit":"decimal(10,5)","payment_amount":"decimal(10,5)","currency":"varchar(3)"}}
array {"status":"error","error_code":"500","message":"Could not move your uploaded file! There may be a problem with it! Please double check what you are uploading.","data":null}
array {"status":"error","error_code":"500","message":"Could not create a file entry for the Last Invoice","data":null}
array {"status":"error","error_code":"500","message":"A problem occurred during your Porting Number request!","data":null}

Returns

array{"status":"success","message":"Porting Number Request created successfully","data":{"porting_number_id":"int(11)","invoice_no":"varchar(20)","reseller_invoice_no":"varchar(20) willl return null when payment_type=3"}}

Porting Number PUT

API

Edit Ported Number request details. Have in mind that we may not be able to update this request if we have already filed it.

api curl -k -i -H "Accept: application/json" -X PUT -d "X-API-KEY=##########&porting_number_id=2&country_id=30&porting_number_type=2&first_name=Bar&last_name=Foo&address=another_address&contact_name=Bam&contact_number=112&ported_number=3223&pin_code=111" http://sandbox.chainsolutions.net/voip/v1/porting_number

Parameters

$porting_number_id

int

int(11) returned from Porting Number POST method

$custom_package_id

int

int(11) (optional) returned from the Custom Package GET method, the Ported Number will be subscribed to this Custom Package

$sip_address

string

varchar(255) (optional) if the Porting is successful the DID will be connected to a SIP address, example: '557203765@infocus.net'.

$current_provider

string

varchar(50) (optional) The name of your current DID provider

$title

string

varchar(10) (optional) one of those values - 'Mr', 'Ms', 'Company'

$first_name

string

varchar(100) (optional) First Name as in contract with your current provider. Required if You've passed 'Mr' or 'Ms' for 'title'

$last_name

string

varchar(100) (optional) Last Name as in contract with your current provider. Required if You've passed 'Mr' or 'Ms' for 'title'

$company_name

string

varchar(100) (optional) The name of the Company of the end user. Required if You've passed 'Company' for 'title'

$street_name

string

varchar(100) (optional) Street Name as in contract with your current provider

$building_number

string

varchar(10) (optional) The number of the building as in contract with your current provider

$city

string

varchar(18) (optional) The name of the city in which the end user resides

$zip

string

varchar(20) (optional) ZIP of the end user

$country

string

varchar(50) (optional) The name of the country in which the end user resides

$ported_number

string

varchar(20) (optional) Phone Number to be ported

$porting_date

string

(optional) (optional) The desired porting date, pass in YYYY-MM-DD format

Exceptions

array {"status":"error","error_code":"400","message":"Invalid porting_number_id!","user_message":"The Porting Request that you have selected does not belong to you or to a client of yours!","data":null}
array {"status":"error","error_code":"400","message":"You must pass some parameters for update to this method!","user_message":"You must change at least one parameter to update your Porting Request!","data":null}
array {"status":"error","error_code":"400","message":"The 'custom_package_id' you passed is either invalid or does not belong to you!","data":null}
array {"status":"error","error_code":"400","message":"The 'custom_package_id' you passed is not one for buying DIDs! Please pass a proper 'custom_package_id'","data":null}
array {"status":"error","error_code":"400","message":"Your Porting Number request has a status 'Sent'. This means you cannot update it. Only requests with status 'Submitted' can be updated","data":null}
array {"status":"error","error_code":"400","message":"Your Porting Number request has a status 'Done'. This means you cannot update it. Only requests with status 'Submitted' can be updated","data":null}
array {"status":"error","error_code":"400","message":"Your Porting Number request has a status 'Cancelled'. This means you cannot update it. Only requests with status 'Submitted' can be updated","data":null}
array {"status":"error","error_code":"500","message":"There was a problem updating your Porting Number request","data":null}

Returns

array{"status":"success","message":"Porting Number updated successfully","data":null}

Queue DELETE

API

Delete existing Queue and its members

api curl -k -i -H "Accept: application/json" -X DELETE -d "X-API-KEY=########&accountcode=########&queue_id=104" http://sandbox.chainsolutions.net/voip/v1/queue

Parameters

$accountcode

string

(optional) if not passed you will do the request on your own account, pass it if you want the request to be related to a client of yours

$queue_id

int

int(11) the ID of the queue you want to delete

Exceptions

array {"status":"error","error_code":"404","message":"There was a problem deleting this Queue. Please try again","data":null}

Returns

array{"status":"status","message":"Queue deleted successfully","data":null}

Queue GET

API

Get all queues and members related to account

api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=4########&accountcode=########" http://sandbox.chainsolutions.net/voip/v1/queue

Exceptions

array {"status":"error","error_code":"404","message":"No queues found for this user!","data":null}

Returns

array{"status":"success","message":"Queues retrieved successfully","data":[{"queue_id":"int(11)","name":"varchar(20)","items":[{"penalty":"int(11)","extension":"int(20)"}]}]

Queue POST

API

Post a new Queue and its members and overflow extensions

api curl -k -i -H "Accept: application/json" -X POST -d "X-API-KEY=########&accountcode=########&name=some_queue&members[0]=5541000&members[1]=5541001&overflow[0]=5541002" http://sandbox.chainsolutions.net/voip/v1/queue

Parameters

$members

array

array of User Extensions, get from User Extension GET method with index 'extension'

$overflow

array

array of User Extensions, get from User Extension GET method with index 'extension'

$name

string

varchar(70) the name of the queue you want to create

$accountcode

string

(optional) if not passed you will do the request on your own account, pass it if you want the request to be related to a client of yours

Exceptions

array {"status":"error","error_code":"400","message":"Please pass members in array format!","data":null}
array {"status":"error","error_code":"400","message":"You have a non-existing extension in parameters list: 'extension'","data":null}
array {"status":"error","error_code":"500","message":"Duplicated Extension record: 'extension',"data":null}

Returns

array{"status":"success","message":"Queue created successfully","data":{"queue_id":"int(11)"}}

Queue PUT

API

Edit existing Queue and its members and overflow extensions

api curl -k -i -H "Accept: application/json" -X PUT -d "X-API-KEY=#########&accountcode=#########&queue_id=104&name=some_other_queue&members[0]=5541001&members[1]=5541004&overflow[0]=5541005" http://sandbox.chainsolutions.net/voip/v1/queue

Parameters

$accountcode

string

(optional) if not passed you will do the request on your own account, pass it if you want the request to be related to a client of yours

$queue_id

int

int(11) the ID of the Queue you want to edit

$members

array

array of User Extensions, get from User Extension GET method with index 'extension'

$name

string

varchar(70) (optional) the name of the queue you want to edit

$overflow

array

(optional) array of User Extensions, get from User Extension GET method with index 'extension'

Exceptions

array {"status":"error","error_code":"400","message":"Please pass extensions in array format!","data":null}
array {"status":"error","error_code":"400","message":"You passed wrong parameters!","data":null}
array {"status":"error","error_code":"400","message":"Duplicated Extension record: 'extension'","data":null}
array {"status":"error","error_code":"400","message":"You have a non-existing extension in parameters list: 'extension'","data":null}

Returns

array{"status":"status","message":"Update successful!","data":null}

Recording File GET

API

Download the file corresponding to a particular recording_id. You can get the direct link for the download form the "Call Recording GET" method (the "download_link" index), you need to only replace the X-API-KEY variable

api http://sandbox.chainsolutions.net/voip/v1/recording_file/recording_id/#####/
api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=########&recording_id=######" http://sandbox.chainsolutions.net/voip/v1/recording_file

Parameters

$accountcode

string

varchar(20) (optional) If the recording belongs to a client of yours you should pass the accountcode as well

$recording_id

int

int(11) the recording you want to download the file for

Exceptions

array {"status":"error","error_code":"400","message":"recording_id must be set","data":null}
array {"status":"error","error_code":"403","message":"Wrong recording_id or you have no permission to download this file!","data":null}

SIP Device DELETE

API

Remove a SIP Device from our system

api curl -k -i -H "Accept: application/json" -X DELETE -d "X-API-KEY=########&physical_id=########" http://sandbox.chainsolutions.net/voip/v1/sip_device

Parameters

$physical_id

int

int(20)

$accountcode

string

varchar(20) (optional) If the SIP Device belongs to a client of yours

Exceptions

array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"The 'physical_id' you passed is not valid or does not belong to the selected account","data":null}
array {"status":"error","error_code":"500","message":"There was a problem deleting this SIP Device","data":null}

Returns

array{"status":"success","message":"SIP Device deleted successfully","data":null}

SIP Device GET

API

Retrieve all SIP devices for selected account. If 'accountcode' is not passed, then the SIP Devices for for your own account will be retrieved.

api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=########&accountcode=########" http://sandbox.chainsolutions.net/voip/v1/sip_device

Parameters

$accountcode

string

varchar(20) (optional) If you want to get the SIP Devices of a client of yours

$physical_id

int

int(20) (optional) If you want to get a particular SIP Device only

Exceptions

array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}

Returns

array{"status":"success","message":"SIP Devices retrieved successfully","data":[{"physical_id":"int(20)","mac_address":"varchar(20)","provision":"int(1)","last_registered":"datetime","password":"varchar(20)","extension":"int(20)"}]}
array{"status":"success","message":"No SIP Devices found for account","data":null}

SIP Device POST

API

Add new SIP device to our network

api curl -k -i -H "Accept: application/json" -X POST -d "X-API-KEY=########&accountcode=########" http://sandbox.chainsolutions.net/voip/v1/sip_device

Parameters

$accountcode

string

varchar(20) (optional) If you want to get the SIP Devices of a client of yours

$mac_address

string

varchar(20) (optional) Example format: '00:11:63:1D:B6:10'. Add the MAC address of the device. Device cannot work in our network if they don't have a MAC address set. You can add this later using SIP Device PUT

Exceptions

array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"422","message":"MAC address is not valid! Please pass a valid MAC address in 'mac_address'. Example: '00:11:63:1D:B6:10'","data":null}
array {"status":"error","error_code":"400","message":"A device with this MAC address already exists in our network! Are you entering it twice?","data":null}
array {"status":"error","error_code":"500","message":"Unable to create SIP Device right now. Please try again!","data":null}

Returns

array{"status":"success","message":"SIP Device added successfully","data":{"physical_id":"int(12)","password":"varchar(20)"}}

SIP Device PUT

API

This method lets you change the MAC address of a SIP device or to manually set it for provisioning. You can also use it to transfer the selected device to another account in our system

api curl -k -i -H "Accept: application/json" -X PUT -d "X-API-KEY=########&physical_id=########" http://sandbox.chainsolutions.net/voip/v1/sip_device

Parameters

$physical_id

int

int(20)

$provision

int

int(1) (optional) If you pass this parameter with a value of '1' the SIP Device will be manually set for provisioning

$accountcode

string

varchar(20) (optional) If the SIP Device belongs to a client of yours

$mac_address

string

varchar(20) (optional) Example format: '00:11:63:1D:B6:10'. Add/change the MAC address of the device

$transfer_to_accountcode

string

varchar(20) (optional) If you want to transfer the physical device to another account into our system just pass its accountcode here

Exceptions

array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"The 'physical_id' you passed is not valid or does not belong to the selected account","data":null}
array {"status":"error","error_code":"400","message":"The accountcode you passed to transfer the device to is not valid!","data":null}
array {"status":"error","error_code":"400","message":"This SIP Device already belongs to the accountcode you want to transfer it to!","data":null}
array {"status":"error","error_code":"422","message":"MAC address is not valid! Please pass a valid MAC address in 'mac_address'. Example: '00:11:63:1D:B6:10'","data":null}
array {"status":"error","error_code":"400","message":"A device with this MAC address already exists in our network! Are you entering it twice?","data":null}
array {"status":"error","error_code":"400","message":"Please pass any parameters to update","data":null}
array {"status":"error","error_code":"500","message":"Could not create a new User Extension for transferred SIP device!","data":null}
array {"status":"error","error_code":"500","message":"There was a problem updating this SIP Device","data":null}

Returns

array{"status":"success","message":"SIP Device updated successfully","data":null}

System Package GET

API

Get all System Packages related to your Account. If you want other System Packages created for you please contact us directly. You will also get the System Package's prices in your own currency as well as our exchange rate at this moment. The returned 'months' index indicates how often a Billing Subscription based on this Package is being paid for. If 'months' = 1 than the Subscription is monthly. If it is '12' than the Subscription is yearly. If you want to change the 'months' period for a particular System Package please contact us directly.

api http://sandbox.chainsolutions.net/voip/v1/system_package/system_package_id/###
api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=##########" http://sandbox.chainsolutions.net/voip/v1/system_package

Parameters

$system_package_id

int

int(11) (optional) get a particular System Package

Exceptions

array {"status":"error","error_code":"400","message":"The 'system_package_id' you passed does not correspond to an existing System Package","data":null}

Returns

array{"status":"success","message":"System Packages retrieved successfully","data":[{"system_package_id":"int(11)","name":"varchar(45)","description":"text","price_eur":"decimal(10,5)","price_reseller_currency":"decimal(10,5) if different from 0 your clients that are in the same currency will be billed on this price","price_converted_from_eur":"decimal(10,5) the price of the System Package converted from EUR to your currency","reseller_currency":"varchar(3) Your current Reseller Currecny","exchange_rate":"decimal(10,5) exchange rate to EUR","months":"int(2) the number of months between each client payment"}]}
array{"status":"success","message":"No system packages available for this Account","data":null}

Timezones GET

API

Get a list of timezones we support. They are all standard but you need to get their ID. Used when creating (Account GET) or modifying (Account PUT) accounts

api http://sandbox.chainsolutions.net/voip/v1/timezones
api http://sandbox.chainsolutions.net/voip/v1/timezones/timezone_id/10
api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=################" http://sandbox.chainsolutions.net/voip/v1/timezones

Parameters

$timezone_id

int

int(11) retrieve a single timezone

Exceptions

array {"status":"error","error_code":"500","message":"Couldn't retrieve Timezones right now! Please try again later","data":null}

Returns

array{"status":"success","message":"Timezones retrieved successfully","data":[{"timezone_id":"int(5)","GMT_zone":"varchar(20)","GMT_time":"varchar(20)"}]}

User Extension Caller Id DELETE

Delete an existing User Extension Caller Id entry

Parameters

$accountcode

string

varchar(20) (optional) If you want to delete User Extension Caller Id that belongs to a client of yours

$user_extension_caller_id_id

int

Exceptions

array {"status":"error","error_code":"400","message":"The 'user_extension_caller_id_id' you passed is either invalid or does not belong to selected Account","data":null}
array {"status":"error","error_code":"500","message":"There was a problem deleting this User Extension Caller Id entry","data":null} curl -k -i -H "Accept: application/json" -X DELETE -d "X-API-KEY=########&accountcode=########&user_extension_caller_id_id=238" http://sandbox.chainsolutions.net/voip/v1/user_extension_caller_id

Returns

array{"status":"success","message":"User Extension Caller Id entry deleted successfully","data":null}

User Extension Caller Id GET

API

Retrieve User Extension Caller Id entries

api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=########&accountcode=########&extension_id=1" http://sandbox.chainsolutions.net/voip/v1/user_extension_caller_id

Parameters

$accountcode

string

varchar(20) (optional) If you want to get User Extension Caller IDs that belong to a client of yours

$extension_id

int

the User Extension you want to get this entries for. You can get a list of User Extensions from User Extension GET

$user_extension_caller_id_id

int

(optional) if you want to get only a particular User Extension Caller Id entry

Exceptions

array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"The 'extension_id' you passed is wrong or does not belong to this account!","data":null}
array {"status":"error","error_code":"422","message":"user_extension_caller_id_id must be a numeric value!","data":null}

Returns

array{"status":"success","message":"User Extension Caller Id entries retrieved successfully","data":[{"user_extension_caller_id_id":"int(11)","did_number":"varchar(20)","dial_mask":"varchar(8)"}]}
array{"status":"success","message":"You don't have User Extension Caller Id entries for this extension yet","data":null}

User Extension Caller Id POST

API

Add User Extension Caller Id entry to a User Extension. This way you can present different DIDs depending on which numbers you are dialing

api curl -k -i -H "Accept: application/json" -X POST -d "X-API-KEY=########&accountcode=########&extension_id=1&dial_mask=00&did_number=0035924917414" http://sandbox.chainsolutions.net/voip/v1/user_extension_caller_id

Parameters

$accountcode

string

varchar(20) (optional) If you want to add User Extension Caller IDs for a client of yours

$extension_id

int

int(11) the User Extension you want to add this entry to. You can get a list of all User Extensions from User Extension GET

$did_number

string

varchar(20) you need to pass a DID number the account owns. You can get a list of all DIDs you own for DID GET

$dial_mask

string

varchar(8) Example: '00' for all numbers or '0044' for all UK numbers. Whenever you dial a number which starts with the 'dial_mask' you are using the 'did_number' you are passing will be presented as Caller Id

Exceptions

array {"status":"error","error_code":"400","message":"An entry with the same did_number/dial_mask already exists for this extension!","data":null}
array {"status":"error","error_code":"500","message":"There was a problem adding this User Extension Caller Id entry","data":null}

Returns

array{"status":"success","message":"User Extension Caller Id entry added successfully","data":{"user_extension_caller_id_id":"int(11)"}}

User Extension DELETE

API

Delete an existing User Extension

api curl -k -i -H "Accept: application/json" -X DELETE -d "X-API-KEY=########&accountcode=########&extension_id=####" http://sandbox.chainsolutions.net/voip/v1/user_extension

Parameters

$extension_id

int

int(11)

$accountcode

string

varchar(20) (optional) If you want to delete an Extension that belongs to a client of yours

Exceptions

array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"The 'extension_id' you passed does exist or does not belong to the selected Account","data":null}
array {"status":"error","error_code":"500","message":"Unable to delete User Extension right now. Please try again!","data":null}

Returns

array{"status":"success","message":"User Extension deleted successfully","data":null}

User Extension GET

API

Retrieve a list of all User Extensions for an account.
If 'accountcode' is not passed, then the User Extensions for for your own Reseller account will be retrieved.

api curl -k -i -H "Accept: application/json" -G -d "X-API-KEY=########" http://sandbox.chainsolutions.net/voip/v1/user_extension

Parameters

$accountcode

string

varchar(20) (optional) If you want to get the Extensions of a client of yours

$extension_id

int

int(11) (optional) If you want to get a particular Extension only

$offset

int

int(10) (optional) default is '0', which element to start the pagination from.

$limit

int

int(2) (optional) default and max is 20, how many records you want to display on a page.

Exceptions

array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"The 'extension_id' passed does not exist or belong to selected account","data":null}

Returns

array{"status":"success","message":"User Extensions retrieved successfully","data":[{"extension_id":"int(11)","extension":"int(20)","default_sip_device":"int(12)","home_sip_device":"int(12)","pin_code":"int(8)","dial_prefix":"varchar(10)","recording_enabled":"int(1)","international_calls_enabled":"int(1)","present_caller_id":"int(1)","billing_subscription_id":"int(11)","sip_address":"varchar(255)","follow_me_sip_address":"varchar(255)","remaining_free_minutes":"decimal(10,2) returned only for Extensions that have free minutes associated","caller_id_entries":[{"user_extension_caller_id_id":"int(11)","did_number":"varchar(20)","dial_mask":"varchar(10)"}]}]}
array{"status":"success","message":"No User Extensions found for account","data":null}

User Extension POST

API

Add new User Extension

api curl -k -i -H "Accept: application/json" -X POST -d "X-API-KEY=########&accountcode=########" http://sandbox.chainsolutions.net/voip/v1/user_extension

Parameters

$accountcode

string

varchar(20) (optional) If you want to add a new Extension for a client of yours

$physical_id

int

int(20) (optional) If you want to link the new User Extension to a particular SIP Device. You cannot link it to a device that is already taken by another extension!. You can get the 'physical_id' from SIP Device GET

$pin_code

int

int(4) (optional) Pass a four digit pin code the user will use to log in with. If not passed a random pin code will be generated

$extension_suffix

int

int(4) (optional) The last four digits of your extension, must be larger than 1000. If this is not passed you will get the next available extension

$dial_prefix

string

varchar(10) (optional) If you want all the numbers dialed form this extension to automatically have this prefix in front of them. Useful if you are making call campaigns to particular countries. For example you have have a '0044' as 'dial_prefix' to omit dialling country code every time

$recording_enabled

int

int(1) (optional) Default is '0' - Recordings are NOT created for calls done trough this extension. Pass '1' to have Recording creation enabled

$present_caller_id

int

int(1) (optional) default is '0' - do not present a Caller Id, '1' - present Caller Id. You can add Caller Id records for each User Extension by using User Extension Caller Id POST

$international_calls_enabled

int

int(1) (optional) default is '0' - cannot make international phone calls trough this User Extension, '1' - this User Extension is permitted to make international phone calls

$sip_address

string

varchar(255) (optional) connect User Extension to a SIP address, example: '557203765@infocus.net'

Exceptions

array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"extension_suffix should be 1000 or more!","data":null}
array {"status":"error","error_code":"400","message":"User Extension 'X' already exists! Please pass another 'extension_suffix'!","data":null}
array {"status":"error","error_code":"400","message":"Wrong accountcode, please check it and try again!","data":null}
array {"status":"error","error_code":"400","message":"Wrong 'physical_id' or it does not belong to selected account","data":null}
array {"status":"error","error_code":"400","message":"The 'present_caller_id' you passed is not a valid DID you own with us! Please use one from the DID GET method, use the 'did_number' index","data":null}
array {"status":"error","error_code":"400","message":"The sip_address you passed already has a DID with free minutes subscription associated. Please use another sip_address.","user_message":"Sorry, you can't have more than one PSTN number on the same device!","data":null}
array {"status":"error","error_code":"500","message":"Unable to create User Extension right now. Please try again!","data":null}

Returns

array{"status":"success","message":"User Extension added successfully","data":{"extension_id":"int(11)","extension":"int(20)","pin_code":"int(4)"}}

User Extension PUT

API

Edit existing User Extension

api curl -k -i -H "Accept: application/json" -X PUT -d "X-API-KEY=########&accountcode=########&extension_id=####" http://sandbox.chainsolutions.net/voip/v1/user_extension

Parameters

$extension_id

int

int(11)

$accountcode

string

varchar(20) (optional) If you want to edit an Extension that belongs to a client of yours

$physical_id

int

int(20) (optional) If you want to link the User Extension to a particular SIP Device. You can 'unlink' the extension from the SIP device by passing '0' for 'physical_id', You cannot link it to a device that is already taken by another extension!. You can get the 'physical_id' from SIP Device GET

$pin_code

int

int(4) (optional) Pass a four digit pin code the user will use to log in with.

$dial_prefix

string

varchar(10) (optional) If you want all the numbers dialed form this extension to automatically have this prefix in front of them. Useful if you are making call campaigns to particular countries. For example you have have a '0044' as 'dial_prefix' to omit dialling country code every time

$recording_enabled

int

int(1) (optional) '0' - Recordings are NOT created for calls done trough this Extension. Pass '1' to have Recording creation enabled

$present_caller_id

int

int(1) (optional) '0' - do NOT present a Caller Id, '1' - present Caller Id, if User Extension has a Billing Subscription DID associated with it default Caller ID Entry with this DID will be created if they don't already exist. You can add Caller Id records for each User Extension by using User Extension Caller Id POST

$international_calls_enabled

int

int(1) (optional) '0' - cannot make international phone calls trough this User Extension, '1' - this User Extension is permitted to make international phone calls

$sip_address

string

varchar(255) (optional) connect User Extension to a SIP address, example: '557203765@infocus.net'

$follow_me_sip_address

string

varchar(255) (optional) if Extension needs to be used for Multiring or other Service that requires SIP redirection. The value of 'sip_address' is overwritten by this 'follow me' SIP address

$follow_me_phone_number

string

varchar(20) Route Follow Me of User Extension to an external Phone Number. It will be 'normalized' to international standards with leading zeroes (example: 00448445025003)

$follow_me_extension

string

varchar(30) Route Follow Me of User Extension to an Extension. Pass the extension number here, example '5541000'. You can get the 'extension' from the User Extension GET method

$follow_me_extension_id

int

varchar(30) Do not pass together with 'follow_me_extension'. Route Follow Me of User Extension to an Extension. You can get the 'extension_id' from the User Extension GET method

$follow_me_queue_id

int

int(11) Route Follow Me of User Extension to a Queue. Pass the 'queue_id' returned from Queue GET method

$follow_me_ivr_id

int

int(11) Route Follow Me of User Extension to an IVR. Pass the 'irv_id' returned from IVR GET method

$follow_me_recording_id

int

int(11) Route Follow Me of User Extension to a pre-recorded Recording.

$remove_follow_me_routing

int

int(1) Pass '1' if you want to remove Follow Me routing from this User Extension

Exceptions

array {"status":"error","error_code":"403","message":"Invalid accountcode or no permissions to view or modify client data!","data":null}
array {"status":"error","error_code":"400","message":"The 'extension_id' you passed does exist or does not belong to the selected Account","data":null}
array {"status":"error","error_code":"400","message":"Wrong 'physical_id' or it does not belong to selected account","data":null}
array {"status":"error","error_code":"400","message":"The 'physical_id' you chose is already being used by another User Extension! Please use another one","data":null}
array {"status":"error","error_code":"400","message":"The 'present_caller_id' you passed is not a valid DID you own with us! Please use one from the DID GET method, use the 'did_number' index","data":null}
array {"status":"error","error_code":"400","message":"The sip_address you passed already has a DID with free minutes subscription associated. Please use another sip_address.","user_message":"Sorry, you can't have more than one PSTN number on the same device!","data":null}
array {"status":"error","error_code":"400","message":"Please pass any variables to change for this User Extension","data":null}
array {"status":"error","error_code":"400","message":"We could not find a Billing Subscription that is linked to this User Extension! Maybe you are passing 'sip_address' for an Extension that is not linked to a Billing Subscription","data":null}
array {"status":"error","error_code":"500","message":"Unable to update User Extension right now. Please try again!","data":null}

Returns

array{"status":"success","message":"User Extension updated successfully","data":null}