API 1 - Sonetel · API 1.3 August 30, 2016 Mailbox 647 11411 Stockholm Sweden...

API 1.3

August 30, 2016

Mailbox 647 11411 Stockholm Sweden [email protected] help.sonetel.com/api

API-1.3.docx

August 30, 2016

(110)


1. Revision history .............................................................................. 4

2. Sonetel API ..................................................................................... 5

3. Technical overview ......................................................................... 6

4. General Notes ................................................................................. 7

4.1. API structure............................................................................. 7

4.2. Operations ................................................................................ 7

4.2.1. CREATE............................................................................ 7

4.2.2. FETCH .............................................................................. 7

4.2.3. UPDATE............................................................................ 7

4.2.4. DELETE ............................................................................ 7

4.3. Responses and Error codes ..................................................... 8

4.3.1. Partial response ................................................................ 9

4.4. Authentication ........................................................................... 9

4.5. API versions ........................................................................... 10

4.6. General notes ......................................................................... 10

5. Sonetel resources ......................................................................... 15

5.1. Account .................................................................................. 15

5.1.1. Properties ........................................................................ 15

5.1.2. Fetch ............................................................................... 16

5.1.3. Update ............................................................................ 17

5.2. Sub-account ........................................................................... 18

5.2.1. Properties ........................................................................ 18

5.2.2. Fetch ............................................................................... 20

5.2.3. Create ............................................................................. 22

5.2.4. Update ............................................................................ 24

5.2.5. Delete .............................................................................. 25

5.3. User ....................................................................................... 26

5.3.1. Properties ........................................................................ 26

5.3.2. Fetch ............................................................................... 31

5.3.3. Create ............................................................................. 42

5.3.4. Update ............................................................................ 45

5.3.5. Delete .............................................................................. 48

5.4. Number stock summary .......................................................... 50

5.4.1. Properties ........................................................................ 50

API-1.3.docx

August 30, 2016

(110)


5.4.2. Fetch ............................................................................... 51

5.5. Available phone number ......................................................... 54

5.5.1. Properties ........................................................................ 54

5.5.2. Fetch ............................................................................... 55

5.6. Phone number subscription .................................................... 62

5.6.1. Properties ........................................................................ 62

5.6.2. Fetch ............................................................................... 64

5.6.3. Create ............................................................................. 70

5.6.4. Update ............................................................................ 71

5.6.5. Delete .............................................................................. 73

5.7. Usage records ........................................................................ 74

5.7.1. Properties ........................................................................ 74

5.7.2. Fetch ............................................................................... 77

5.8. Voice app ............................................................................... 83

5.8.1. Properties ........................................................................ 83

5.8.2. Fetch ............................................................................... 86

5.8.3. Create ............................................................................. 88

5.8.4. Update ............................................................................ 89

5.8.5. Delete .............................................................................. 90

5.9. Prompt .................................................................................... 91

5.9.1. Properties ........................................................................ 91

5.9.2. Fetch ............................................................................... 92

5.9.3. Create ............................................................................. 95

5.9.4. Update ............................................................................ 97

5.9.5. Delete .............................................................................. 97

5.10. Country ............................................................................... 98

5.10.1. Properties .................................................................... 98

5.10.2. Fetch ......................................................................... 100

5.11. price-list/outboundcalls-price ............................................. 107

5.11.1. Properties .................................................................. 107

5.11.2. Fetch ......................................................................... 108

API-1.3.docx

August 30, 2016

(110)


1.Revision history

Revision Date Changed by

Changes

1.3.01 2015-02-14 Prashant API version 1.3. Improvements from 1.2 include

Ability to upload voice prompts Price for phone numbers and for making calls

to mobiles and landlines

1.3.02 2015-06-16 Prashant API version 1.3.3. Improvements from 1.3 include

1.3.03 2015-09-18 Prashant Account and sub-account: Field and filter priceplan added

1.3.04 2015-11-06 Prashant phonenumbersubscription: Voice apps can be specified using hteir voiceappId

API-1.3.docx

August 30, 2016

(110)


2.Sonetel API The Sonetel API is a REST based web-service that enables you to manage your Sonetel account from your own platform or service. You can manage your account, your phone numbers and view the phone numbers available for ordering etc.

The Sonetel API is a powerful tool that enables you to integrate your business processes with the Sonetel phone system.

The current version of the API supports the following.

Managing accounts and sub-accounts Managing users Managing your phone numbers Managing voice apps and voice prompts Viewing usage and charges for your account Viewing phone number stock and available numbers for ordering Viewing world-wide coverage of types of phone number

supported and their price Viewing price for making calls to mobiles and landlines worldwide

API-1.3.docx

August 30, 2016

(110)


3.Technical overview

The Sonetel API is based on REST principles.

The API base URL is https://api.sonetel.com/. It supports Create, Retrieve, Update, Delete (CRUD) operations on Sonetel resources over Https. Http is not supported to ensure that the API is secure.

To get started, you need to sign up for a Sonetel account.

The API can be enabled or disabled by requesting Sonetel support. Once the API is enabled, you can view and manage your API settings in of Sonetel account from the web interface. Your account_id and API secret key are your API credentials that are needed to access your account resources and are available and managed from within your Sonetel account.

Sonetel API follows HTTP BASIC authentication.

The API uses JSON (JavaScript object notation) for resource representations.

https://api.sonetel.com/

http://www.sonetel.com/en/sign-up

API-1.3.docx

August 30, 2016

(110)


4.General Notes

4.1.API structure

The Sonetel API uses HTTP methods to perform the operations in-line with the general approach used for REST based APIs.

The API credentials are used to authorize and authenticate the entity invoking the API to grant privilege to perform the operation.

4.2.Operations

4.2.1.CREATE

You can create a resource using HTTP POST method. The content of the HTTP POST is in JSON. The response to an HTTP POST in a successful create operation is an HTTP 200 OK with the resource representation in JSON format.

4.2.2.FETCH

You can fetch a resource or their list using HTTP GET method. Filters can be applied using query string parameters to narrow down the results. The response to a HTTP GET in a successful Fetch operation is the HTTP 200 OK with the resource representation in JSON format.

Partial response that enables only specific data fields to be returned in the response is also supported in some of the resources.

4.2.3.UPDATE

You can update a resource using HTTP PUT method. The content of the HTTP PUT is in JSON. The response to an HTTP PUT in a successful update operation is an HTTP 200 OK with the resource representation in JSON format.

4.2.4.DELETE

You can delete a resource using HTTP DELETE method. Not all resources can be deleted. The response to a HTTP DELETE in a successful delete operation is the HTTP 200 OK.

API-1.3.docx

August 30, 2016

(110)


4.3.Responses and Error codes

A request processed by the API would return either an HTTP 200 OK or an HTTP error code.

In the case when a 200 OK is returned, the status of the operation is specified in the content of the response.

In the case of an operation processed successfully, the following format is returned as content

{

"response":

{

<Resource representation>

},

"resource": <Resource name accessed>,

"status": "success"

}

In the case the request processing failed, details of the error are returned in the response.

Here is how a failed operation response looks.

{

"response":

{

"detail": "Error string",

"code": "Error code"

},

"resource": "Resource accessed",

"status": "failed"

}

The error string and error codes are specified here [TBD].

API-1.3.docx

August 30, 2016

(110)


Appropriate HTTP error code is returned if the request is not understood by Sonetel. If the request is valid then a status code is returned depending on the status of the request processing. Following list of HTTP error codes are supported.

HTTP status Text Description

200 OK Success

400 Bad request The request format is not understood by the web server.

401 Unauthorized Authentication credentials are missing or incorrect.

404 Not found The resource requested does not exist

415 Unsupported

500 Internal server error The server is currently unable to handle this request

503 Service unavailable The server is currently unable to handle this request due to overload

4.3.1.Partial response

In most cases, API users do not need all the data in a resource, rather they need only specific parts of data in the resource. Partial response enables just that. It allows the API user to specify the list of fields that are required in the response. This saves bandwidth, which may be important when the API is consumed by mobile apps, and also enables the API to be customized to the needs of the API users.

API users can specify what fields they need in a comma separated list under the filter “fields”. The following format applies. /resource?fields=field1,field2,field3

For e.g. to GET only phones of users

GET /user?field=phones

4.4.Authentication

The API supports HTTP basic authentication. The authentication is using an API Key and an API Token. The API Key represents the username and the API Token represents the password during the authentication.

You can get your API Key and API Token from your API panel on Sonetel web portal. Multiple tokens can be generated via the panel.

https://portal.sonetel.com/portal/UI/Pages/signIn/signIn.aspx

API-1.3.docx

August 30, 2016

(110)


4.5.API versions

The API version is formatted as major.minor. The current version of the API is 1.00.

Usually a change in the minor version of the API ensures backward compatibility within the same major version. For e.g. version 3.05 of the API would be backward compatible with 3.03, but not 2.55. However, please note that backward compatibility is not guaranteed and there may be instances where minor version upgrades may result in loss of backward compatibility. This will, however, be clearly specified from time to time.

The version of the API is exchanged and specified in the API request/response content currently. This support will be added in the future.

The latest version of the API is available at https://api.sonetel.com. To access a specific version of the API, use https://api.sonetel.com/<major.minor>.

4.6.General notes

To keep the API consistent, there are certain general format definitions and principles followed. These are listed here.

Countries are specified using the standard ISO codes as per ISO 3166-1.

Currencies are specified as per the standard ISO 4217. Telephone country code is used as a property and filter in many

resources, usually specified as field country_code. This field refers to the standard code assigned to a specific country(ies) by ITU-T. For e.g. +1 for USA, or +46 for Sweden or +91 for India. See http://en.wikipedia.org/wiki/List_of_country_calling_codes for more details. Some countries may share the same telephone country code, for e.g. both ISA

Telephone area code is a 2 to 5 digit routing code for a geographical region in a country and forms part of an E164 number. It is used as a property and filter (specified as area_code in the API) in some resources in the API. Telephone area codes are often quoted with a national dialing prefix “0” or other digits, for e.g. a number in London listed as 020 8765 4321). The API expects the area code usage as the exact area code for that region without the prefix. In some countries such as Italy, a “0” is a part of the area code, in which case “0” must be included in the area code when specified.

All properties and string values follow an all lower case approach except where specifically mentioned. One exception to this rule

https://api.sonetel.com/

https://api.sonetel.com/%3cmajor.minor

http://en.wikipedia.org/wiki/ISO_3166-1

http://en.wikipedia.org/wiki/ISO_3166-1

http://www.iso.org/iso/home/standards/currency_codes.htm

http://en.wikipedia.org/wiki/List_of_country_calling_codes

API-1.3.docx

August 30, 2016

(110)


are places where ISO codes such as those for country, currency, date/time etc. are specified.

Boolean or flags in query strings in the urls always use “yes” or “no”, unless explicitly specified. For e.g. parameter=”yes”.

Date and time format: All time values used in filters and properties are specified in GMT only. The time format is used as per ISO8601. The basic time format is the default format (YYYYMMDDThh:mm:ssZ).

Unknown parameters in urls are ignored while processing requests.

User passwords are between 5 and 32 characters and can carry anything except some special characters, namely (%^()+=[]\';/{}|\"<>?).

User extension should only be 3 digits and has to be numeric. An extension can start with 0. 000 is not allowed as extension.

Decimal values are represented with a dot (“.”). For e.g. 2.14 or 3.556 etc. As a general rule, the decimal precision (digits after decimal) are specified in the definition of the property or filter. Values passed are always rounded to the specified definition. For e.g. if a property credit_balance can take up to 2 decimals and a value of 5.334 is specified, the API automatically assumes the value to be 5.33.

Multi-value filters: Filters are used while performing searches. The filters are normally passed as query string parameters in the url. In certain cases, it is required that multiple values can be passed for a single filter field. For e.g. if a search requires getting all resources that has a property, country with values either “USA” or “GBR”. In such cases, the values can be passed in the URL as a comma separated list. E.g. api.sonetel.com/resource?country=”USA”,”GBR”

String wild-card search: Some filters support wild-card search. This is normally common for string based searches such as account names, user names, country name etc. The wild card character used is “*” and a minimum of 3 characters are required to be provided for the search, unless explicitly specified in the filter definition. For e.g. to search for all countries with name having “united” use “name”=*united*. Wild card searches are case-insensitive.

Free test numbers: Sonetel allows specific partners to use its phone number stock to allocate free test numbers for trial for a specific period. If you would like to partner with Sonetel and be able to assign free test numbers for your customer, please contact [email protected].

Evaluation mode: An account in evaluation mode has certain limitations. Outbound phone calls are limited to 1 min and more than 1 parallel call are not allowed. Voicemail to email and SMS to email does not work.

http://sonetel.com/en/help/support-center/help-topics/api/can-i-give-free-test-numbers-to-my-users/

mailto:[email protected]

API-1.3.docx

August 30, 2016

(110)


Sonetel services: Each service within Sonetel is identified using a fixed string identifier across the API. The list of service strings are listed here

o outbound_call o inbound_call o phnum_subscription o on-net_call o fax_to_email o sms_to_email o priceplan_premium o voiceapp_menu o voiceapp_company-voicemail o voiceapp_prompt-recording o voiceapp_call-thru o overusage o voiceapp_call-thru o voiceapp_user-voicemail

Endpoints and endpoint types: Calls made through Sonetel can be started from and sent to different types of endpoints. The following endpoint types are defined. For each endpoint type, the endpoint Id can take specific values as defined below.

o user: A Sonetel user in an account. The endpointId is the user_id

o phonenumber: In case of outbound calls, this represents a regular phone number (such as a mobile or landline number. For incoming calls, this represents a phone number purchased from Sonetel. The endpointId is the E164 number

o sip: A SIP endpoint. The endpointId is a SIP address. E.g. sip:[email protected]

o app: A Sonetel voice app. The endpointId address is left empty and will be fixed in future revisions.

Charge types: When a service is used in an account, the charges for that usage are applied to the prepaid balance. The charges are classified into the following types

o one_time_fee: A fee applied to the account when an when a service is added, or in some cases, an instance of a service is added. For e.g. when a phone number subscription is purchased, there is usually a one time fee applied.

o recurring_fee: A fee applied on a recurring basis. A recurrence_interval defines the period when the fee is applied.

o per_instance_fee: A fee applied based on the count of usage events. For e.g. a fee for a service that is applied per user in an account.

o time_usage_fee: A fee applied based on the usage in time for a service. For e.g. the fee per minute for calls. This fee is also associated with a time_pulse that specifies the interval for measuring the time usage. For

API-1.3.docx

August 30, 2016

(110)


e.g. a pulse of 60 seconds for a call implies that the fee is applied per minute.

Phone number access restrictions: Some phone numbers, especially toll-free numbers, in some countries have access limitations where they are not reachable from either fixed phones, mobile phones, pay phones or from outside the country. Access restrictions are used in properties for phone number related resources. The restrictions are specified as a comma separated list of access networks from where the phones numbers are not reachable. Possible networks are “fixed”, “mobile”, “payphone” or “international”. For e.g. “international,payphone” implies that the phone number is not reachable from phones outside the country and from pay phones.

Address requirements for phone numbers: Purchasing some type of phone numbers in some countries require an address to be submitted. In some cases an address proof is also needed. The specifications on what is required is available via the API through two separate fields.

o addr_req: Specifies if there is any requirement to have a local address or any address to use this phone number. More details are available at this link. This field can take the following values none: There are no address requirements.

Anyone anywhere can purchase this phone number

on-request: An address is required to be provided if there is a request from the local provider.

global: Any address world-wide local: An address in the same geographic zone as

the phone number o addr_proof: A flag that indicates if an address proof is

required along with the address. Voice app types: Voice applications - or Voice apps - are various

types of automated telephone services for playing and recording messages, handling callers etc. See more details here. The following voice app types are supported.

o ivr – A voice menu with welcome message, main menu message and actions on digits pressed or timeout and auto attendant functions that to forward calls based on extensions entered

o mailbox – A shared voicemail box for an account receives voicemails and delivers emails to a specified email address.

o sysprompt – Settings for error prompts for an account/sub-account.

Pre-recorded prompts: Sonetel provides pre-recorded voice prompts in various languages that can be used in voice apps as default “voice”. The “voice” field in the JSON definitions can take one of the values specified below.

o en English male

http://sonetel.com/en/help/support-center/help-topics/phone-numbers/are-there-limitations-with-phone-numbers/

http://www.sonetel.com/site/pmwiki.php?n=Admin.VoiceApps

http://sonetel.com/en/help/support-center/help-topics/voice-response/

API-1.3.docx

August 30, 2016

(110)


o swe Swedish male o spa Spanish male o hin-fe Hindi female o tam-fe Tamil female o tel-fe Telugu female o en-fe English female o gr-fe Greek female o en-uk-fe English(UK accent) female o fr-fe French female o ara-fe Arabic female

Default prompts: Voice apps have a set of standard prompts

without which the voice app cannot function. These prompts cannot be deleted.

o Ivr Welcome prompt Get extension prompt Main menu prompt

o Mailbox Greeting prompt Goodbye prompt

o Sysprompt Person unavailable prompt Person busy prompt

API-1.3.docx

August 30, 2016

(110)


5.Sonetel resources

Your Sonetel account and its various components are available via the API as resources. Each resource has a set of properties that can be managed by accessing the resource.

Here is a look at the list of resources supported and what operations are supported on what resources.

Resource/Operation

Matrix CREATE SHOW SEARCH UPDATE DELETE

account No Yes No No No

sub-account Yes Yes Yes Yes Yes

user Yes Yes Yes Yes Yes

numberstocksummary No No Yes No No

availablephonenumber No Yes Yes No No

phnumsubscription Yes Yes Yes Yes Yes

country No Yes Yes No No

usagerecord No Yes Yes No No

voiceapp Yes Yes Yes Yes Yes

prompt No Yes Yes No No

pricelist/outboundcalls-price

No No Yes No No

5.1.Account

The account resource represents the Sonetel account for your company. This resource contains your company wide settings, account status, prepaid credit etc. The account resource is accessed using the unique account-id under the base URL with a format https://api.sonetel.com/account/<account_id>.

When you sign up on Sonetel, an account is created for you. This account becomes your main Sonetel account.

Your main Sonetel account can be fetched and updated but cannot be created or deleted via the API.

5.1.1.Properties

The account resource has the following properties.

Property Description

id The unique account Id of the company account in Sonetel

https://api.sonetel.com/rest/account/%3caccount-id

API-1.3.docx

August 30, 2016

(110)


name The name of the company

status The status of the account – “active”, “inactive”, “evaluation” or “disabled”

evaluation – The account is usable for free and paid Sonetel services in evaluation mode. Paid services work in restricted mode as long as credit is available in the account.

active – The account is usable for free and paid Sonetel services.

inactive – The account is inactive. The account is moved to this state if the account does not have enough credit balance. status_desc provides details for the reason why the account is inactive.

status_desc An additional description of the status of the account. For e.g. this could carry a text describing why the account was disabled.

currency Currency for the account. A currency, once set, cannot be changed. All billing related transactions for the account are done in this currency.

area_code The telephone area code where the company is located.

address Company address first line

address2 Company address second line

city Company address city name

zipcode Company address postal ZIP code

country The country where the company is located.

credit_balance The account balance in the account’s currency specified up to 2 decimals.

priceplan The priceplan that applies to this account. Accounts that have premium enabled, have this value set as “premium”. For other accounts, this value is “regular”.

status and change rules o

5.1.2.Fetch

An account can be fetched using its account_id.

GET https://api.sonetel.com/account/<id>

Example: GET https://api.sonetel.com/account/53535

The response carries the following representation

http://sonetel.com/en/help/support-center/help-topics/premium/

https://api.sonetel.com/rest/account/%3cid

https://api.sonetel.com/rest/account/53535

API-1.3.docx

August 30, 2016

(110)


{

"account_id" : "53535",

"name" : "My company",

"account_status" : "active",

"status_desc" : null,

"currency" : "USD",

"address" : "My company address Line 1",

"address2" : null,

"city" : "Some city",

"zipcode" : "336655",

"country" : "USA",

"credit_balance" : "3.77",

"priceplan" : "regular",

}

5.1.3.Update

Account can be modified by issuing an HTTP POST or PUT to the account resource.

POST https://api.sonetel.com/account/< id>/

or

PUT https://api.sonetel.com/account/< id>/

Example : POST or PUT https://api.sonetel.com/account/55353

The following properties can be updated and sent in the request.

Parameter

name

area_code

address

address2

city

zipcode

country

priceplan

The response to a successful request carries the resource representation of the updated sub-account.


API-1.3.docx

August 30, 2016

(110)


5.2.Sub-account

A sub-account is an account created under your main Sonetel account and is owned by your main account. You may optionally create multiple sub-accounts under your main account via the API (it is currently not possible to view or create sub-accounts via your Sonetel web management panel). Each sub-account is a complete account in itself with its own settings, account credentials, balance etc.

You cannot create sub-accounts under sub-accounts.

Sub-accounts allow you to segment data in any way you want. For e.g. you may separate the data for each of your customers by creating a sub-account for each customer.

A sub-account can be created, searched and deleted using your main account credentials.

Credit balance – accounts and sub-accounts

All service usage charges in any of your sub-accounts are applied and debited from your main account credit balance. Your main account balance represents unused funds available for use of Sonetel services both in the main account and all the sub-accounts under the main account.

Sub-accounts also have a credit balance. However, the balance in a sub-account does not represent real money. Sonetel enables you to configure such that the sub-account balance also can be automatically debited when a service is used by that sub-account. i.e. that Sonetel charges the main account for the Service provided, but also can update the balance in the sub-account accordingly. You can also increase or decrease the balance of a sub account in accordance with your own business logic. For example if you receive payments from your customer, want to add credit for testing etc.

The balance in the main account represents the financial relation between Sonetel and you. The balance in the sub-accounts represents the financial relation between you and your customers. From Sonetel’s perspective the sub-account balance is merely a counter that you can do anything you want with, but Sonetel can debit the sub account balance on your behalf, when there is service usage in the sub-account

The balance in the sub-account can be controlled by the main account credentials via the API.

5.2.1.Properties

The sub-account resource has the following properties.

API-1.3.docx

August 30, 2016

(110)



account_id The unique account Id of the company account in Sonetel

name The name of the company

status The status of the account – “active”, “inactive”, “evaluation” or “disabled”

evaluation – The account is usable for free and paid Sonetel services in evaluation mode. Paid services work in restricted mode as long as credit is available in the account.

active – The account is usable for free and paid Sonetel services.

inactive – The account is inactive. The account is moved to this state if the account does not have enough credit balance. status_desc provides details for the reason why the account is inactive.

disabled – The account is suspended for suspected misuse or other reason. The account cannot be used for any service. An account cannot be moved to/from this state via the API. This state can only be controlled by Sonetel.

status_desc An additional description of the status of the account. For e.g. this could carry a text describing why the account was disabled.

currency Currency for the account. A currency, once set, cannot be changed. All billing related transactions for the account are done in this currency.

area_code The telephone area code where the company is located.

address Company address first line

address2 Company address second line

city Company address city name

zipcode Company address postal ZIP code


credit_balance The account balance in the account’s currency specified up to 2 decimals.

priceplan The priceplan that applies to this sub-account. Sub-accounts that have premium enabled, have this value set as “premium”. For other accounts, this value is “regular”.

user_lname The last name of the company user

email The user’s email address

password The user’s password

status and change rules

http://sonetel.com/en/help/support-center/help-topics/premium/

API-1.3.docx

August 30, 2016

(110)


o active – The account is usable for free and paid Sonetel services in Full mode. Paid services work based on the credit balance in the account.

o inactive – The account is inactive and no services can be used in this account. status_desc provides details for the reason why the account is inactive.

o disabled – The account is suspended for misuse or other reason. The account cannot be used for any service. An account cannot be moved to/from this state via the API. This state can only be controlled by Sonetel.

5.2.2.Fetch

A sub-account can either be retrieved using its account_id or searched using filters.

5.2.2.1.Show

A sub-account can be fetched using its account_id as below.

GET https://api.sonetel.com/account/<id>

Example: GET https://api.sonetel.com/account/53535

A sub-account resource has the following details.

{

"account_id" : "53535",


"status" : "active",


"currency" : "USD",


"address2" : null,


"zipcode" : "336655",

"country" : "USA",

"area_code" : "414",



}

5.2.2.2.Search

A sub-account can be searched using filters passed as query string parameters to the account list resource.

GET https://api.sonetel.com/account?filters


https://api.sonetel.com/rest/account?filters

API-1.3.docx

August 30, 2016

(110)


The available filters are listed here.

Filter Description

name Exact/partial company name. The search is done ignore case. Minimum 3 characters are required in the filter. This is a string wild card search.

status The account status string value. The values it can take are “evaluation”, “active”, “inactive”, “disabled”


min_credit Accounts having credit balance more than this value. The credit balance can be specified up to 2 decimals.

max_credit Accounts having credit balance more than this value. The credit balance can be specified up to 2 decimals.

email The email address in full of a user in the company

priceplan The priceplan of the sub-account. Can take values “premium” or “regular”

Example: GET https://api.sonetel.com/account?name=my co

The response carries a list of account resources.

[

{

"account_id" : "53535",




"currency" : "USD",


"address2" : null,


"zipcode" : "336655",

"country" : "USA",




},

{

account_id

"name" : "My company 2",

https://api.sonetel.com/rest/account?name=my

API-1.3.docx

August 30, 2016

(110)


"status" : "disabled",

"status_desc" : "Disabled due to misuse",

"currency" : "USD",

"address" : "",

"address2" : "",


"zipcode" : "756643",

"country" : "USA",



"priceplan" : "premium",

},

{

account_id

"name" : "My company 3",

"status" : "evaluation",

"status_desc" : "",

"currency" : "USD",

"address" : "",

"address2" : "",


"zipcode" : "756643",

"country" : "USA",




}

]

5.2.3. Create

A sub-account resource is created via POST to the account list resource. Only the main account credentials can be used while creating a sub-account. A sub-account can never create another sub-account.

POST https://api.sonetel.com/account/

Sub-account templates

In many cases, most sub-accounts that are created under a main account may have fixed and common values for various parameters. For e.g. all sub-accounts should be created with currency as “USD” and country as “USA. In such cases, it may be helpful to define a sub-account template under your main account. A sub-account template is a collection of account parameters and their values. Instead of passing

https://api.sonetel.com/rest/account/

API-1.3.docx

August 30, 2016

(110)


each parameter and its value while creating a sub-account, you only need to pass the template reference and the API automatically sets the corresponding values in the sub-account. One or more sub-account templates can be defined in the main account via the API panel on Sonetel web portal.

More information on sub-account templates can be found here [TBD].

When a template-id is not passed in the request while creating an account, the API automatically uses the default template in the account.

Mandatory parameters are listed here

Property

name

email

user_fname

password

Optional parameters are listed here

Property More description

status If this is not specified, the status is set to “active”. The status of the account can be “active”, “inactive”, “evaluation” or “disabled”

country If this is not specified, it is either taken from the default template(if available) or set equal to the value in the main account

currency If this is not specified, it is either taken from the default template(if available) or set equal to the value in the main account

area_code If this is not specified, it is either taken from the default template(if available) or set equal to the value in the main account

address If this is not specified, this field is not set

address2 If this is not specified, this field is not set

city If this is not specified, this field is not set

zipcode If this is not specified, this field is not set

user_lname If this is not specified, this field is not set

template_id If this is not specified, the API assumes and uses the default template in the main account.

credit_balance If this is not specified, it is set as zero.

API-1.3.docx

August 30, 2016

(110)


priceplan If this is not specified, the priceplan is set to “regular”

The response to a successful request carries the resource representation of the newly created sub-account.

5.2.4.Update

Sub-accounts can be updated by issuing a PUT to the account.

PUT https://api.sonetel.com/account/<account_id of B>

Example: https://api.sonetel.com/account/75432

The following parameters can be updated


name See here for details

status See here for details

status_desc See here for details

area_code See here for details

address See here for details

address2 See here for details

city See here for details

zipcode See here for details

country See here for details

change_balance A value by which the current credit_balance must be updated. 2 digit decimal value.

priceplan See here for details

change_balance is handled in a special way during Update. credit_balance as a value that must be added or removed from the current credit_balance.

To increment the current credit_balance, specify a positive value, for e.g.

change_balance : 1.2

To decrement the current credit_balance, specify a negative value

change_balance : -1.2



API-1.3.docx

August 30, 2016

(110)


For e.g. if a sub-account has a balance of $3 and an Update is issued with a change_balance as -1.2 (The currency is automatically assumed to be the same as the sub-account currency), the resulting credit balance in the account will be updated to $1.8.

5.2.5.Delete

Sub-accounts can be deleted by main account using the main account credentials.

A deleted sub-account can in no way be retrieved.

DELETE https://api.sonetel.com/account/<account_id of sub-account>

Example: DELETE https://api.sonetel.com/account/53535



API-1.3.docx

August 30, 2016

(110)


5.3.User

Every user in your account (or a sub-account) is available as a resource via the API. Each user has a unique identity, a userId, which can be used to access the user. Users can be fetched, created, updated and deleted via the API.

Users can also be searched using filters such as email address, their names etc.

When an account is created, a default user is automatically created as part of the account creation. There is always, at-least, one user in an account.

An account or a sub-account can have many users (up to a 1000 users), each representing employees of the company that owns the account.

5.3.1.Properties

User’s properties are listed below. Property Description

email The primary email address of the user.

title Title of user in staff such as CEO, Engineer etc.

user_fname The first name of the user

user_lname The last name of the user

user_id Unique Id of the Sonetel user.

type Privilege of user. admin/regular

password Password for the user.

call Settings that control how calls to the user (incoming) and calls made by the user (outgoing) are handled. For e.g. what caller-Id should be shown when the user makes a call to a mobile or landline number, or what phones of the user have to ring and for how many seconds when there is an incoming call to the user.

phones Settings of the user’s phones. A user can have one or more of their mobile or landline numbers setup as their phones when someone tries to reach the user. All IP phones for a user that are connected to Sonetel are also included in these settings.

numbers The Sonetel phone numbers including the extension and iNUM, where the user receives incoming phone calls

location User’s country and area code

API-1.3.docx

August 30, 2016

(110)


5.3.1.1./<user-id>/call


incoming Settings for handling incoming calls to a user

outgoing Settings for handling outgoing calls made by a user

5.3.1.2./<user-id>/call/incoming

You can customize what happens when a user receives an incoming phone call. This includes settings that define what phones should ring, for how many seconds, and what caller-Id should be sent to the phones.

All this is done using two Action blocks in the user incoming call settings, /user/call/incoming, one each for first and second (fallback) action. The system attempts the first_action, and if it is unsuccessful (the call doesn’t connect), the instructions in the second_action are followed.

The following fields are available in the incoming call settings


first_action The first action taken when there is an incoming call to the user.

second_action The fallback action to be taken when the call cannot be connected with instructions in the first_action

Each of the first_action and second_action are represented by an action block. The following fields are part of an action block.


action The action to be taken. See action block scenarios for details. It can take the following values.

“ring”: ring a set of phones “forward”: Forward calls to voicemail, to another

user, SIP URI etc. “disconnect”: Disconnect the call

to The type of function on which the action is to be taken, depending on the action. See action block for details

id The Id of the function based on the action and to. See action block for details

show The caller-Id that is shown on the phone(s) receiving the call. This field is only available in first_action currently. This field is not relevant when forwarding to voicapps or in case the action is “disconnect”. This can take values

“caller”: show the phone number of the caller “none”: No caller-Id is shown “inum”: User’s iNUM.

API-1.3.docx

August 30, 2016

(110)


One of the user’s phone number. Any of the phone numbers in the account that is assigned to the user can be set in the value of this field. The full E164 number must be set. The phone number would then be shown as te caller-Id. For e.g. if a number +14243332434 is assigned to the user, the value of the field could be set as “14243332434”.

ring_time The number of seconds that the phones that are called should ring. This only applies when the action is “ring” or “forward”. Also, when forwarding calls to a user, please note that the ring settings of the user to whom the call is forwarded-to would override the settings specified here. The value of this field can be between 5 and 30.

This field is only available in first_action currently

Action block

The table below specifies the scenarios and the possible values that the fields can take in the scenario.

Scenario action to id

Ring all phones of the user

ring myphones -NA-

Ring all IP phones of the user

ring sipphones -NA-

Ring one of the user’s (non-IP) phone

ring phone phoneid

Forward calls to the user’s voicemail

forward voicemail -NA-

Forward call to another user

forward user userid of the user to which the call is being forwarded

Forward calls to a phone number

forward phnum Any mobile or landline number

Forward calls to a voice application

forward voiceapp appId of the voiceapp

Forward calls to a SIP address

forward sip [sip]:<URI>:<port>

Disconnect the call

disconnect -NA- -NA-

API-1.3.docx

August 30, 2016

(110)


5.3.1.3./<user-id>/call/outgoing

The outgoing settings are used when a user makes an outgoing call from Sonetel. For e.g. a when a user makes a call to a mobile number using their IP phone.

Currently, only the caller-Id to be shown to the called number is available as a setting.


show The caller-id shown when a user makes an outgoing call. This can take values

“auto”:The caller-Id is automatically selected by the system.

“none”: No caller-Id is shown “inum”: User’s iNUM. One of the user’s phone number. Any of the

phone numbers in the account can be set in the value of this field. The full E164 number must be set. The phone number would then be shown as te caller-Id. For e.g. if a number +14243332434 is assigned to the user, the value of the field could be set as “14243332434”.

Please note that there are some exceptions where the caller-Id shown can be controlled via the mobile apps when either callback or callthru services is used for making calls

5.3.1.4./<user-id>/phones

The “phones” lists the user’s phones where the user can choose to receive incoming phone calls.

You can add one or many mobile or landline phones for a user via the API. You can also define which of these phones are available for receiving incoming calls for the user.

Besides the regular mobile or landline phones, any SIP phone that a user connects to the Sonetel SIP service is available as a sip_phone via the API.


receive_calls_on_sip Flag that indicates if incoming calls to the user should be sent to the SIP phones.

list The list of phones

http://sonetel.com/en/help/support-center/help-topics/my-settings/can-i-change-the-number-shown-when-i-call/

http://www.sonetel.com/site/pmwiki.php?n=Admin.CallThru

API-1.3.docx

August 30, 2016

(110)


Each item in the phones list has the following fields


phone_id The unique Id of a user’s phone

phone_name User’s chosen name for the phone number

phone_type This can take values “sip” or “regular”

phnum The phone number. Applies only in case of non-SIP phones

receive_calls Flag that indicates if incoming calls to the user should be sent to this phone. In case of SIP phones, this field is not applicable.

sip_details The SIP related details. Applies only in case of SIP phones

5.3.1.5./phones/<phone-id>/sip_details


registered Flag indicating if the SIP phone is registered

registered_since The date/time since when the SIP phone is registered to Sonetel.

auto_provision Flag that indicates if the SIP phone is automatically provisioned. Sonetel ready phones can be automatically provisioned.

In the current version of the API, a phone cannot be added to Sonetel for automatic provisioning. This function will be added in future upgrades of the API.

address The SIP address of the phone. This address is automatically specified by the phone to Sonetel using SIP when the phones registers to Sonetel

useragent The SIP device information published by the SIP phone while registering to Sonetel.

mac The MAC address of the SIP phone.

5.3.1.6./<user-id>/numbers

The “numbers” represents Sonetel numbers assigned to the user including the user’s extension, the user’s iNUM.


http://sonetel.com/en/help/support-center/help-topics/sip/what-sip-phones-can-i-connect-to-sonetel/how-can-i-connect-a-greandstream-phone/

http://sonetel.com/en/help/support-center/help-topics/users/how-can-i-configure-a-user/

http://sonetel.com/en/help/support-center/help-topics/phone-numbers/what-is-an-inum-number/

API-1.3.docx

August 30, 2016

(110)


number_id Unique Id of the number

number_type This can take three values

“internal": The user’s extension “inum”: The user’s iNUM “phnum”: Local number anywhere worldwide

from Sonetel connected to the user

number The E164 phone number. In the case of extension, it is the short number assigned to the user (usually between 3 to 5 digits).

5.3.1.7./<user-id>/location


country The country where the user is located

tel_area_code The telephone area code for the city or region where the user is located

5.3.2.Fetch

User can either be fetched using a userId or can be searched with filters.

User also supports partial response with the fields “call”, “phones”, “numbers” and “location”.

5.3.2.1.Show

To get a specific user details, you can fetch it with the userId.

GET https://api.sonetel.com/1.3/account/<account_id>/user/<user_id>

Example: GET https://api.sonetel.com/1.3/account/53535/user/206671234

{

"email" : "[email protected]",

"title" : "CEO",

"user_fname" : "First user",

"user_lname" : "Lastname1",

"user_id" : "206671234",

"type" : "admin",

"location" : {

"country" : "RUS",

"tel_area_code" : "223",

},

https://api.sonetel.com/rest/account/%3caccount_id%3e/user/%3cuser_id

https://api.sonetel.com/rest/account/53535/user/206671234

API-1.3.docx

August 30, 2016

(110)


The standard response returns only certain details, as shown above.

To get additional details, you can specify what additional fields you need.

For e.g. if you want to get call settings for a user,

https://api.sonetel.com/1.3/account/53535/user/206671234?fields=call

{


"title" : "CEO",



"user_id" : "206671234",

"type" : "admin",

"location" : {

"country" : "RUS",


},

"call" : {

"outgoing" : {

"show" : "auto",

},

"incoming" : {

"first_action" : {

"action" : "ring",

"to" : "ipphones",

"id" : "",

"show" : "caller",

"ring_time" : "15",

},

"second_action" : {

"action" : "forward",

"to" : "user",

"id" : "1094223423",

},

},

},

Similarly, to get the user’s phones and location

https://api.sonetel.com/1.3/account/53535/user/206671234?fields=phones,location

https://api.sonetel.com/rest/account/53535/user/206671234?fields=call

https://api.sonetel.com/rest/account/53535/user/206671234?fields=phones,location

https://api.sonetel.com/rest/account/53535/user/206671234?fields=phones,location

API-1.3.docx

August 30, 2016

(110)


{


"title" : "CEO",



"user_id" : "206671234",

"type" : "admin",

"location" : {

"country" : "RUS",


},

"phones" : {

"receive_calls_on_sip" : "yes",

"list" :

[

{

"phone_id" : "6122093aFFr",

"phone_name" : "",

"phone_type" : "sip",

sip_details: {

"registered" : "yes",

"registered_since" : "20141002T12:34:56Z",

"auto_provision" : "no",

"address" : "[email protected]:3434",

"useragent" : "X-Lite Ver 2.3",

}

},

{

"phone_id" : "519982365",

"phone_name" : "",


sip_details: {

"registered" : "no",

"registered_since" : "",

"auto_provision" : "yes",

"address" : "",

"useragent" : "Grandstream GXP 2100",

"mac" : "4560DD3CD23D",

},

},

{

API-1.3.docx

August 30, 2016

(110)


"phone_id" : "132466856",

"phnum_name" : "My mobile",

"phone_type" : "regular",

"phnum" : "+72146007000",

"receive_calls" : "yes",

},

{

"phone_id" : "132466857",

"phnum" : "+72236023000",


"phnum_name" : "Landline",

"receive_calls" : "no",

},

]

},

5.3.2.2.Search

Users can also be searched by using filters passed as query string parameters to the user list resource.

GET https://api.sonetel.com/1.3/account/account_id/user?filters


Filter Description

name Exact/partial user first name and last name match. Wild card search is supported for this filter

email The email address of a user. Wild card search is supported for email. For e.g. email=”test123” will search and return all email addresses with the string test123 in it.

account_id The account to which a user belongs

Example: GET https://api.sonetel.com/1.3/account/53535/[email protected]

The search response is a list of user resources that have email matching “@mycompany.com”

[

https://api.sonetel.com/rest/account/53535/[email protected]

https://api.sonetel.com/rest/account/53535/[email protected]

API-1.3.docx

August 30, 2016

(110)


{


"title" : "CEO",



"user_id" : "206671234",

"type" : "admin",

"location" : {

"country" : "RUS",


},

"call" : {

"outgoing" : {

"show" : "auto",

},

"incoming" : {

"first_action" : {

"action" : "ring",

"to" : "ipphones",

"id" : "",

"show" : "caller",

"ring_time" : "15",

},

"second_action" : {


"to" : "user",

"id" : "1094223423",

},

},

},

"phones" : {


"list" :

[

{


"phone_name" : "",


sip_details: {




API-1.3.docx

August 30, 2016

(110)




}

},

{

"phone_id" : "519982365",

"phone_name" : "",


sip_details: {




"address" : "",


"mac" : "4560DD3CD23D",

},

},

{

"phone_id" : "132466856",



"phnum" : "+72146007000",


},

{

"phone_id" : "132466857",

"phnum" : "+72236023000",




},

]

},

"numbers" : {

{

"number_id" : "14cc72384",

"number_type" : "internal",

"number" : "101",

},

{

"number_id" : "14cc72385",

"number_type" : "phnum",

API-1.3.docx

August 30, 2016

(110)


"number" : "+14644356656",

}

{

"number_id" : "14cc72386",

"number_type" : "inum",

"number" : "88531053435334",

}

{

"number_id" : "14cc72387",


"number" : "+724544343445",

},

},

},

{


"title" : "Staff engineer",

"user_fname" : "Second user",


"user_id" : "206671238",

"type" : "regular",

"location" : {

"country" : "USA",


},

"call" : {

"outgoing" : {

"show" : "none",

},

"incoming" : {

"first_action" : {

"action" : "ring",

"to" : "myphones",

"id" : "",

"show" : "number",

"ring_time" : "30",

},

"second_action" : {

"action" : "ring",

"to" : "phnum",

"id" : "+919863325434",

},

API-1.3.docx

August 30, 2016

(110)


},

},

"phones" : {

"receive_calls_on_sip" : "no",

"list" :

[

{

"phone_id" : "4522093a534",

"phone_name" : "",


sip_details: {





"useragent" : "acrobits 1.334.23",

}

},

]

},

"numbers" : {

{

"number_type" : "Extension",

"number" : "102",

},

{

"number_type" : "e164",

"number" : "+65792434344",

}

{


"number" : "88531053435334",

}

},

},

{


"title" : "HR Manager",

"user_fname" : "Third user",


"user_id" : "206671245",

"type" : "admin",

API-1.3.docx

August 30, 2016

(110)


"location" : {

"country" : "AUS",


},

"call" : {

"outgoing" : {

"show" : "+84343623443",

},

"incoming" : {

"first_action" : {

"action" : "ring",

"to" : "myphones",

"id" : "",

"show" : "none",

"ring_time" : "25",

},

"second_action" : {

"action" : "ring",

"to" : "sip",

"id" : "[email protected]",

},

}

},

"numbers" : {

{

"number_type" : "e164",

"number" : "+72876534343",

}

{


"number" : "88531053435345",

}

},

},

]

Partial response can be used to get specific details for multiple users. For e.g. if you want to get only the user’s phones for all user’s that have emails ending with “mycompany.com”, you could do the following.

API-1.3.docx

August 30, 2016

(110)


https://api.sonetel.com/1.3/account/53535/[email protected]&fields=phones

[

{


"title" : "CEO",



"user_id" : "206671234",

"type" : "admin",

"phones" : {


"list" :

[

{


"phone_name" : "",


sip_details: {






}

},

{

"phone_id" : "519982365",

"phone_name" : "",


sip_details: {




"address" : "",


"mac" : "4560DD3CD23D",

},

},

{

"phone_id" : "132466856",

https://api.sonetel.com/rest/account/53535/[email protected]&fields=phones

https://api.sonetel.com/rest/account/53535/[email protected]&fields=phones

API-1.3.docx

August 30, 2016

(110)




"phnum" : "+72146007000",


},

{

"phone_id" : "132466857",

"phnum" : "+72236023000",




},

]

},

{


"title" : "Staff engineer",

"user_fname" : "Second user",


"user_id" : "206671238",

"type" : "regular",

"phones" : {

"receive_calls_on_sip" : "no",

"list" :

[

{

"phone_id" : "4522093a534",

"phone_name" : "",


sip_details: {






}

},

]

[

{

"phone_id" : "4522093a534",

"phone_name" : "",

API-1.3.docx

August 30, 2016

(110)



sip_details: {


" registered_since" : "20141002T12:36:56Z",




}

},

]

},

5.3.3.Create

A user is created issuing an HTTP POST to the user list resource.

POST https://api.sonetel.com/1.3/account/<account_id>/user

Example: POST https://api.sonetel.com/1.3/account/53535/user

Mandatory parameters are listed here.

Parameter

email

user_fname

password

Optional parameters are listed here.

Parameter

type

title

user_lname

call

phones

location

numbers

While creating a user, you can also specify phones to be added for the user in the same request. This automatically creates the specified phones. Only the phones with phone_type “regular” can be created.

https://api.sonetel.com/rest/account/53535/user

API-1.3.docx

August 30, 2016

(110)


POST https://api.sonetel.com/1.3/account/<account_id>/user

[

{


"title" : "Mr.",



"user_id" : "206671234",

"type" : "admin",

"location" : {

"country" : "RUS",


},

"phones" : {


“list” : [

{

"phone_id" : "132466856",



"phnum" : "+72146007000",


},

{

"phone_id" : "132466857",

"phnum" : "+72236023000",


"phnum_name" : "Landphone",


},

]

},

}

You can also create a phone by issuing a POST to the phones resource directly.

POST https://api.sonetel.com/1.3/account/<account_id>/user/<user_id>/phones

{

https://api.sonetel.com/rest/account/%3caccount_id%3e/user

https://api.sonetel.com/rest/account/%3caccount_id%3e/user/%3cuser_id%3e/phones


API-1.3.docx

August 30, 2016

(110)




"phnum" : "+72146007000",


},

You can also specify location information while creating the user. If the location for a user is not explicitly defined, the system automatically uses the location settings of the account while handling calls and dialing preferences. See here for more details.

{


"title" : "CEO",



"user_id" : "206671234",

"type" : "admin",

"location" : {

"country" : "RUS",


},

Call settings can provided while creating a user. If these are not provided, the API automatically sets up pre-defined settings, which can be seen in the response to the Create user request.

{


"title" : "CEO",



"user_id" : "206671234",

"type" : "admin",

"call" : {

"outgoing" : {

"show" : "auto",

},

"incoming" : {

"first_action" : {

"action" : "ring",

http://www.sonetel.com/site/pmwiki.php?n=User.MakingCalls

API-1.3.docx

August 30, 2016

(110)


"to" : "sipphones",

"id" : "",

"show" : "caller",

"ring_time" : "15",

},

"second_action" : {


"to" : "user",

"id" : "1094223423",

},

},

},

To assign an extension to the user, you can create the user with the extension number in the number resource

{


"title" : "CEO",



"user_id" : "206671234",

"type" : "admin",

"numbers" : {

{


"number" : "+724544343445",

},

},

},

Only extension can be created as a number. iNUMs are automatically assigned by Sonetel. Other numbers, are assigned when a phonenumbersubscription is created and is connected to the user.

5.3.4.Update

User can be modified by issuing an HTTP POST or PUT to the user resource.

POST https://api.sonetel.com/1.3/account/<account_id>/user/<user_id>/

or

API-1.3.docx

August 30, 2016

(110)


PUT https://api.sonetel.com/1.3/account/<account_id>/user/<user_id>/

Example: POST or PUT https://api.sonetel.com/1.3/account/53535/user/206671236

The following fields can be updated.

Parameter

email

title

user_fname

user_lname

type

password

call

phones

location

numbers

Updating call settings

To update call settings for a user, the update request must be issued directly to the call resource under the user.

POST OR PUT https://api.sonetel.com/1.3/account/<account_id>/user/<user_id>/call

"outgoing" : {

"show" : "none",

},

"incoming" : {

"first_action" : {

"action" : "ring",

"to" : "myphones",

"id" : "",

"show" : "number",

"ring_time" : "30",

},

"second_action" : {

"action" : "ring",

"to" : "phnum",

"id" : "+919863325434",


https://api.sonetel.com/rest/account/%3caccount_id%3e/user/%3cuser_id%3e/call

API-1.3.docx

August 30, 2016

(110)


},

},

You can also send a request with only the outgoing or the incoming settings data to update the specific settings. For e.g. to update only the outgoing settings, you can send the following request to the call resource

"outgoing" : {

"show" : "none",

}

Updating phones

To update the field “receive_calls_on_sip”, you must issue a request to the phones list resource and provide the updated value of the field in the request body.

PUT https://api.sonetel.com/1.3/account/<account_id>/user/<user_id>/phones

To update an individual phone in the phones list, you can issue an update request to the specific phone_id. It is only possible to update regular phones. siphones cannot be updated.

PUT https://api.sonetel.com/1.3/account/<account_id>/user/<user_id>/phones/<phone_id>

{



"phnum" : "+72146007000",


},

You can also update multiple phones for a user in a single request by issuing an update to the phones resource and listing all the updated phones and the associated fields.

PUT https://api.sonetel.com/1.3/account/<account_id>/user/<user_id>/phones


“list” : [







API-1.3.docx

August 30, 2016

(110)


{

"phone_id" : "132466856",



"phnum" : "+72146007000",


},

{

"phone_id" : "132466857",

"phnum" : "+72236023000",




},

]

The response will include the complete phones list resource for the user.

Updating numbers

You can only update extension for a user. Inum or other numbers (phnum) cannot be updated.

To update the extension, you can issue a PUT to the specific number resource

PUT https://api.sonetel.com/1.3/account/<account_id>/user/<user_id>/numbers/<number_id>

{

"number_type" : "Extension",

"number" : "102",

},

5.3.5.Delete

A user can be deleted from your account by issuing a DELETE to the user resource.

DELETE https://api.sonetel.com/1.3/account/<account_id>/user/<user_id>

Example: DELETE https://api.sonetel.com/1.3/account/53535/user/206671236

You can also delete phones under a user by issuing a delete to the phones resource. Only regular phones can be deleted this way.

https://api.sonetel.com/rest/account/%3caccount_id%3e/user/%3cuser_id%3e/numbers/%3cnumber_id

https://api.sonetel.com/rest/account/%3caccount_id%3e/user/%3cuser_id%3e/numbers/%3cnumber_id



API-1.3.docx

August 30, 2016

(110)


DELETE https://api.sonetel.com/1.3/account/<account_id>/user/<user_id>/phones/phone_id

SIP phones cannot be deleted, rather they automatically get removed when they are no longer registered to the Sonetel SIP service.

To remove a user’s extension, you can issue a DELETE to the user’s numbers resource with the number_id of the extension.

DELETE https://api.sonetel.com/1.3/account/<account_id>/user/<user_id>/phones/number_id

iNUM cannot be deleted. Other phone numbers cannot be deleted from within the user resource. They need to be deleting the associated phonenumbersubscription



API-1.3.docx

August 30, 2016

(110)


5.4.Number stock summary

Sonetel maintains a world-wide stock of phone numbers from many countries which can be ordered via the API.

Sonetel provides Toll-free, National or Geographic phone numbers in different countries, cities and under different area codes. Phone numbers are also available in sequential series of 10, 20, 100 numbers etc.

The Number stock summary resource, numberstocksummary, provides the count of Available phone number in stock or available phone number series in stock, and not the actual numbers themselves. Specific phone numbers and their details can be fetched using the resource Available phone number.

The stock information includes a list of one of more area code information blocks in a country with each block carrying data about the count of and free test numbers.

Number stock summary can only be fetched and is fetched for a specific country at a time.

5.4.1.Properties

The Number stock summary resource has the following properties.


country The country where the number is from.

country_code The telephony country code as per ITU standards.

range Applicable in case of number series. The value specifies the total phone numbers in a phone number series. For e.g. for a single number, the value is “1”. For a 10 number series, the value is “10” etc.

area_code The telephone area code of the phone number.

city Name of the city where the number is. The name is descriptive and does not follow any fixed standard.

type1 Type of number – This can be either “national”, “geographic”, or “tollfree”

price_category The price category of the number/series. The allowed values are 1- regular, 2- gold, 3 - gold+, 4 - gold++, 5 -gold+++

stock The amount of numbers in stock at this instant.

freenum_stock The amount of numbers available for time-limited free

1 iNUM is considered as a number of type National in country “Global”. iNUMs stock information can be fetched by using number pattern search. iNUM is not being classified as a separate type or as a separate area code since iNUM only forms a smaller branded subset of +883 region code allocated by ITU.

API-1.3.docx

August 30, 2016

(110)


testing in stock. The ability to assign numbers for free testing is dependent on your agreement with Sonetel

tags A set of tags associated to this city/type of number. The tags are primarily used to indicate if the city is special in any way. Currently, two tags are supported

popular: Indicates that phone numbers from this city are popular with customers. This usually identifies the largest cities in a country.

default: A display recommendation indicating that this city or number type could be made the default choice in user interfaces, typically since the city or number type is most popular or does not require a local address.

simple_name A suggested simple name for the city/type of number. This field is especially useful in cases where a bigger city may have many area codes and the field “city” has a slightly complex naming convention to ensure that each area code is uniquely named, such as “New York Zone 1”, “New York Zone 2” etc.

state The state to which this city belongs. This field is only applicable for numbers in USA.

price_category is a numerical level indicator with value ranging between 1 and 5 that specifies how “good”(easy to remember) the number is. Typically, higher the price category level, the better the number and higher the cost (in most cases, only the initial cost varies). For e.g. numbers ending with “00”(such as 18005528800), or following a pattern such as “1010” (e.g. 1-772-551-1010).

5.4.2.Fetch

5.4.2.1.Show or Search

Number stock summary resource is identified and fetched per country.

GET https://api.sonetel.com/1.3/numberstocksummary/<country>

Filters can be specified to get specific stock information in the country.

To search, the following URL can be used.

GET https://api.sonetel.com/1.3/numberstocksummary/<country>?filters

Example: GET https://api.sonetel.com/1.3/numberstocksummary/USA?area_code=214&type=geographic

The response carries the stock information in the following representation. A block of information is repeated, categorized based on type, range, price_category, area_code and city.

https://api.sonetel.com/rest/numberstocksummary/USA?area_code=214&type=geographic

https://api.sonetel.com/rest/numberstocksummary/USA?area_code=214&type=geographic

API-1.3.docx

August 30, 2016

(110)



Filter Description

range The number series required. Default is “all”. 1,10,20,100 can be specified individually This is a multi-value filter

area_code The area code(s). This is a multi-value filter.

city Exact/partial name match of the city name. The search is done ignore case. Minimum 2 characters required.

tags The tags associated to the city. Providing one or more tags filters the results to the city/type of number that have the tags assigned to them. This is a multi-value filter. Supported values are “default” and “popular”

state The state in which the stock information is needed. This only applies in case of numbers in USA

The response looks like this.

[

{

"country" : "USA",

"country_code" : "1",

"range" : "1",


"city" : "Dallas",

"type " : "geographic",

"price_category" : "1",

"stock" : "30",

"freenum_stock" : "20",

"tags" : "popular",

"simple_name" : "Dallas",

"state" : "Texas",

},

{

"country" : "USA",


"range" : "1",


"city" : "Allen",



"stock" : "23",


API-1.3.docx

August 30, 2016

(110)


"tags" : "",

"simple_name" : "Allen",

"state" : "Texas",

},

{

"country" : "USA",


"range" : "10",


"city" : "Allen",



"stock" : "5",


"tags" : "",

"simple_name" : "Allen",

"state" : "Texas",

}

]

For e.g. to get Number stock summary report in USA for single numbers with area code 214 or 972 and for numbers ending with “00” GET https://api.sonetel.com/1.3/numberstocksummary/USA?range=1&num_pattern=*00&area_code=214,972

If you want to get stock information of single numbers in popular cities in the USA, you can issue the following request

GET https://api.sonetel.com/1.3/numberstocksummary/USA?range=1&tags=popular

https://api.sonetel.com/rest/numberstocksummary/USA?range=1&num_pattern=*00&area_code=214,972

https://api.sonetel.com/rest/numberstocksummary/USA?range=1&num_pattern=*00&area_code=214,972

https://api.sonetel.com/rest/numberstocksummary/USA?range=1&tags=popular

https://api.sonetel.com/rest/numberstocksummary/USA?range=1&tags=popular

API-1.3.docx

August 30, 2016

(110)


5.5.Available phone number

Available phone number resource represents the phone numbers available for ordering in a country in the Sonetel phone number stock.

You can fetch the phone numbers and their details such as their pricing, features they support (SMS, Fax etc.), price category etc.

Available phone number resource could represent a single number or a number series.

An Available phone number is uniquely identified as the E164 number (without +).

5.5.1.Properties

The Available phone number resource has the following properties.


phnum The number in E164 format without ‘+’ In the case of a series, it represents the first number in the series.




phnum_end The range end of the E164 number in the case of number series.

range Applicable in case of number series. The value specifies the total phone numbers in a phone number series. For e.g. for a single number, the value is “1”. For a 10 number series, the value is “10” etc.

city Name of the city where the number is. The name is descriptive and does not follow a fixed naming pattern.

type Type of number – This can be either “national”, “geographic”, or “tollfree”

sms_support Flag that specifies if the number(s) support receiving SMS.

fax_support Flag that specifies if the number(s) support receiving Fax. Fax has to be explicitly activated per phone number. For more details, see here.

access_restrictions Specifies the phone number reachability from different networks

restrictions_desc A text that summarizes a special restriction applicable to this number.

addr_req Specifies if there is any requirement to have an address to purchase and use the phone number

addr_proof A flag that specifies if an address proof is required to

http://en.wikipedia.org/wiki/E.164



http://sonetel.com/en/help/support-center/help-topics/phone-numbers/can-i-send-and-receive-fax/

API-1.3.docx

August 30, 2016

(110)


be submitted for this phone number.

currency The currency in which the fee is specified

one_time_fee One-time fee for purchasing the number(s). Up to 2 decimals.

recurring_fee Periodic fee on purchasing the number(s). Up to 2 decimals.

recurrence_interval The recurrence interval for the recurring fee. Specified in days(e.g. 15d) or months(e.g. 3m)

per_call_fee The per call fee applicable for calls to the number. Up to 2 decimals.

per_min_fee The charge per minute for calls to the number. Up to 2 decimals.

charge_interval The charge interval in seconds for calls to the number.

per_sms_fee The per SMS receiving fee applicable Up to 2 decimals.

per_fax_fee The per FAX receiving fee applicable Up to 2 decimals.

freetest Flag that specifies if this number is available for free testing.


5.5.2.Fetch

5.5.2.1.Show

Available phone number resource represents a unique phone or a phone number series that is available for purchase or for testing. The E164 number uniquely identifies the Available phone number resource.

GET https://api.sonetel.com/1.3/numberstocksummary/country/availablephonenumber/<phnum>

Example: GET https://api.sonetel.com/1.3/numberstocksummary/USA/availablephonenumber/12145535566

The response carries the following representation

"response":

{

"phnum" : "12145535566",

"country" : "USA",


https://api.sonetel.com/rest/numberstocksummary/USA/availablephonenumber/12145535566

https://api.sonetel.com/rest/numberstocksummary/USA/availablephonenumber/12145535566

API-1.3.docx

August 30, 2016

(110)




"phnum_end" : null,

"range" : "1",

"city" : "Dallas",

"type" : "geographic",

"sms_support" : "yes",

"fax_support" : "yes",

"access_restrictions" : "",

"addr_req" : "0",

"one_time_fee" : "0.99",

"recurring_fee" : "0.99",

"recurrence_interval" : "1m",

"per_call_fee" : "0.01",

"per_min_fee" : "0.01",

"charge_interval" : "60",

"per_sms_fee" : "0.01",

"per_fax_fee" : "0.01",

"currency" : "USD",

"freetest" : "yes",


}

"resource": “availablephonenumber”,

"status": "success"

}

A similar example with a phone number series would be as below. Note the values of properties phnum_end and range.

"response":

{

"phnum" : "12145535500",

"country" : "USA",



"phnum_end" : "12145535509",

"range" : "10",

"city" : "Dallas",



API-1.3.docx

August 30, 2016

(110)




"addr_req" : "",

"one_time_fee" : "8",

"recurring_fee" : "8",



"per_min_fee" : "0.01",


"per_sms_fee" : "0.01",

"per_fax_fee" : "0.01",

"currency" : "USD",

"freetest" : "no",


}


"status": "success"

}

5.5.2.2.Search

Available phone number can also be searched using various filters by querying the Available phone number list resource

GET https://api.sonetel.com/1.3/numberstocksummary/country/phnumstockdetails?filters

Example: GET https://api.sonetel.com/1.3/numberstocksummary/USA/availablephonenumber?range=1,10&area_code=214&currency=USD

Filter Description

range The number series required. Default is “all”, in which case numbers in all available series are searched. A value of “1” indicates a single number, value of “10” indicates a 10 number series, etc. This is a multi-value filter

num_pattern Search on the number pattern needed. Search is done on the complete E164 number. A minimum of 3 digits have to be specified.

Pattern follows wild cards such as *0001, *00*111 *00dd334 etc.

https://api.sonetel.com/rest/numberstocksummary/USA/availablephonenumber?range=1,10&area_code=214&currency=USD


API-1.3.docx

August 30, 2016

(110)


“*” matches any number of digits

“d” matches a single digit

area_code The area code(s). This is a multi-value filter


currency The currency in which the pricing details are required. The default is to send the details in the currency of the account

type “national”, “geographic”, or “tollfree” number types can be specified. This is a multi-value filter

freetest Flag that specifies if only free test numbers are to be searched.

price_category The price_category needed. This is a multi-value filter

The response for the search carries a list of Available phone number resources.

{

"response":

[

{

"per_fax_fee": "0.01",

"per_sms_fee": "0.01",

"recurring_fee": "0.99",

"city": "Atlanta (404)",

"area_code": "404",

"country_code": "1",

"freetest": "no",

"fax_support": "yes",

"sms_support": "yes",

"addr_req": "none",

"access_restrictions": "",

"one_time_fee": "1.99",

"recurrence_interval": "0",

"per_call_fee": "0.0",

"per_min_fee": "0.01",

"charge_interval": "60",

"phnum": "14044653577",

"phnum_end": "",

API-1.3.docx

August 30, 2016

(110)


"price_catagory": "gold",

"range": "1",

"currency": "USD",

"type": "geographic",

"country": "USA"

},

{




"city": "New York City Zone 01 (917)",

"area_code": "917",


"freetest": "no",



"addr_req": "none",







"phnum": "19176775320",

"phnum_end": "",

"price_catagory": "gold",

"range": "1",

"currency": "USD",


"country": "USA"

}


"status": "success"

}

Here is an example of a response in case of a phone number series search. Note then change to phnum_end and range values. A single block of data represents a full phone number series.

Example: GET https://api.sonetel.com/1.3/numberstocksummary/USA/availablephonenumber?range=10,10&area_code=571&currency=USD



API-1.3.docx

August 30, 2016

(110)


{

"response":

[

{






"phnum": "15712346560",




"city": "Washington Zone 19 (571)",

"area_code": "571",


"freetest": "no",



"addr_req": "none",


"range": "10",

"phnum_end": "15712346569",

"price_catagory": "regular",

"currency": "USD",


"country": "USA"

},

{






"phnum": "15712346570",




"city": "Washington Zone 19 (571)",

API-1.3.docx

August 30, 2016

(110)


"area_code": "571",


"freetest": "no",



"addr_req": "none",


"range": "10",

"phnum_end": "15712346579",

"price_catagory": "regular",

"currency": "USD",


"country": "USA"

}


"status": "success"

}

API-1.3.docx

August 30, 2016

(110)


5.6.Phone number subscription

A phone number subscription resource represents a phone number or a number series that you have purchased from or ported to Sonetel or is available for free testing in your account.

To buy a phone number or to assign a free test number from Sonetel via the API, you have to create a phone number subscription. A phone number subscription may be assigned to your main account or to any of your sub-accounts. You can also move subscriptions between accounts and sub-accounts.

At the time of creation (or later via an update) you may specify where the phone number should be connected. For e.g. you can specify whether calls to the phone number should be sent to a mobile or landline number or whether they should be sent to a SIP address.

Phone number subscriptions can be fetched, searched and updated.

Deleting a phone number subscription removes the number from your account.

Phone number series can be updated in a similar way as handling a phone number. While creating or deleting a series, the first/lowest phone number in the series is used to refer to the complete series. All numbers in a series are created and deleted together. Updating a specific number in a series updates only that number and its settings. To fetch or update all numbers in a series, you can use the subscription list resource and set the search criteria to point to the series using special filters. Assigning a series to an account assigns all numbers in the series to that account. Individual numbers of the series cannot be created, deleted or assigned to an account individually.

5.6.1.Properties

The phone number subscription resource has the following properties.


Phnum The number in E164 format without ‘+’

account_id The account_id is the account to which the number is currently assigned. It could be the main account-id or any of the sub-account’s account-id.




is_part_of_series A flag that specifies if the number is a part of a number series

Range Applicable if the phone number subscription is of a number that is a part of a phone number


API-1.3.docx

August 30, 2016

(110)


series. The value specifies the quantity of phone numbers in the number series of which this phone number is a part of

City Name of the city where the number is. The name is descriptive and does not follow any standard.

type Type of number – This can be either “national”, “geographic”, or “tollfree”

currency The currency in which the fee is specified

one_time_fee One-time fee for the number/series. Up to 2 decimals.

recurring_fee Recurring fee for the number/series. Up to 2 decimals

recurrence_interval The recurrence interval for the recurring fee. Specified in days(e.g. 15d) or months(e.g. 3m).

per_call_fee The per call fee applicable to the number. Up to 2 decimals

per_min_fee The charge per minute fee for calls. Up to 2 decimals

charge_interval The charge interval in seconds

per_sms_fee The per SMS receiving fee applicable. Up to 2 decimals

per_fax_fee The per FAX receiving fee applicable. Up to 2 decimals


connect_to_type The destination to which this number is connected. The supported values are user, phnum, sip,app

connect_to The id of the connected to entity

activation_date The date/time the number/series was activated.

next_fee_date The date/time that the next recurring fee is to be charged

reclaim_date The date/time an inactive number will be automatically removed from your account if it is inactive due to insufficient balance in the account.

freetest Flag that specifies if this subscription is currently under free testing. Takes Boolean values.

free_test_expiry_date The date/time when the free testing period ends.

API-1.3.docx

August 30, 2016

(110)


Status The number/series status. Can take values “active” or “inactive”

status_desc The text reason specification. Applies in case the number is inactive.

Connect_to – Type and Id

A phone number can be connected to send calls to various types of destinations. The connect_to_type and connect_to together define the destination where the number is connected. The below table specifies how these two properties can be used.

Connected where connect_to_type connect_to

To a user in the account/sub-account

user UserId of the user

To any phone number – mobile or landline

phnum The destination Phone number

SIP address sip [sip]:<URI>:<port>

To a voice app in account/sub-account

app {

“app_type” : “ivr”,

“app_id” : “15sh2jajdj39”

}

app-type can take values “callthru”, “mailbox”, “ivr”

app_id is only relevant in case the app_type is “ivr” or “mailbox” and takes the value of a specific voiceapp app_id

5.6.2.Fetch

5.6.2.1.Show

Phone number subscription is uniquely identified by the phone number in E164 format.


API-1.3.docx

August 30, 2016

(110)


GET https://api.sonetel.com/account/<account_id>/phonenumbersubscription/<phnum>

An example is

GET https://api.sonetel.com/account/5533535/phonenumbersubscription/12145535566

The response carries the following representation.

"response":

{

"phnum" : "12145535566",

"account_id" : "5533535",

"country" : "USA",



"is_part_of_series" : "no",

"range" : "1",

"city" : "Dallas",





"per_call_fee" : "0",

"per_min_fee" : "0.01",


"per_sms_fee" : "0.01",

"per_fax_fee" : "0.01",

"currency" : "USD",


"connect_to_type" : "phnum",

"connect_to" : "+12237651212",

"activation_date" : "20120628T093209Z",

"next_fee_date" : "20120528T093309Z",

"reclaim_date" : "20120528T093209Z",

"freetest" : "no",

"free_test_expiry_date" : "",


"status_desc" : "",

API-1.3.docx

August 30, 2016

(110)


}

"resource": “phonenumbersubscription”,

"status": "success"

}

To fetch a single number subscription in the series you can issue a GET to the specific phone number in the series. For e.g. if you want to retrieve the phone number subscription for a number 121455355005 that is part of a series 121455355001-09, you can issue the following GET request.

GET https://api.sonetel.com/account/5533535/phonenumbersubscription/121455355005

This only returns the phone number subscription for 121455355005 and its details. If you want to get all the numbers in a series together in a list, you can use the search functions below to do that.

5.6.2.2.Search

Phone number subscriptions can be searched using filters. The search is done on phone number subscriptions of the main account and all sub-accounts, but can be refined to a specific account using the filter account_id.

GET https://api.sonetel.com/account/<account_id/phonenumbersubscription?filters

For e.g. the below returns all subscriptions for 10 number series in account 2077654.

GET https://api.sonetel.com/account/53535/phonenumbersubscription?account_id=2077654&range=10

The list of filters is specified here.

Filter Description

range The number series required. Default is “all”, in which case numbers in all available series are searched. A value of “1” indicates a single number, value of “10” indicates a 10 number series, etc. This is a multi-value filter

num_pattern Search on the number pattern needed. Search is done on the complete E164 number. A minimum of 3 digits have to be specified.

Pattern follows wild cards such as *0001, *00*111 *00dd334 etc.

https://api.sonetel.com/rest/account/5533535/phonenumbersubscription/121455355005


https://api.sonetel.com/rest/account/53535/phonenumbersubscription?account_id=2077654&range=10


API-1.3.docx

August 30, 2016

(110)


“*” matches any number of digits “d” matches a single digit

country The country of the phone number.

area_code The area code(s). This is a multi-value filter.


currency The currency in which the pricing details are required. The default is to send the details in the currency of the account

type “national”, “geographic”, or “tollfree” number types can be specified. Multiple values can also be specified as a comma separated list. For e.g. type=”national”,”geographic”

freetest A flag value. Specify “yes” if only free test numbers are to be searched.

price_category The price_category needed. This is a multi-value filter

connect_to_type The destination to which this number is connected. The supported values are user, phnum, sip,app

connect_to The id of the connected to entity

activation_date_min Number/series activated after this date/time.

activation_date_max Number/series activated before this date/time

next_fee_date_min Numbers with next recurring fee due after this date/time

next_fee_date_max Numbers with next recurring fee due before this date/time

reclaim_date_min Numbers that will be reclaimed after this date/time.

reclaim_date_max Numbers that will be reclaimed before this date/time

status The number/series status – “active” or “inactive”

account_id The account_id to which the phone number is associated

start_num This filter is applicable with the filter series. This specifies the first number in the series when all the numbers in a series are to be fetched.

The response to a search carries a list of phone number subscriptions.

{

"response":

{

"phnum" : "12145535566",

API-1.3.docx

August 30, 2016

(110)


"account_id" : "5533535",

"country" : "USA",




"range" : "1",

"city" : "Dallas",






"per_min_fee" : "0.01",


"per_sms_fee" : "0.01",

"per_fax_fee" : "0.01",

"currency" : "USD",



"connect_to" : "+12237651212",


"next_fee_date" : "20120528T093309Z",

"reclaim_date" : "20120528T093209Z",

"freetest" : "no",



"status_desc" : "",

},

{

"phnum" : "12145761234",

"account_id" : "5533538",

"country" : "USA",




"range" : "1",

"city" : "Dallas",



API-1.3.docx

August 30, 2016

(110)





"per_min_fee" : "0.01",


"per_sms_fee" : "0.01",

"per_fax_fee" : "0.01",

"currency" : "USD",



"connect_to" : "+12237651212",


"next_fee_date" : "20120628T093209Z",

"reclaim_date" : "20120528T093209Z",

"freetest" : "no",



"status_desc" : "",

},

]

"resource": “phonenumbersubscription”,

"status": "success"

}

Here are a few more examples on how to use the search filters in the phone number subscriptions resource

The following retrieves all subscriptions in your account including you main account and all your sub-accounts.

GET

https://api.sonetel.com/account/53535/phonenumbersubscription

To fetch all subscriptions in a sub-account 2077654, use the following

GET

https://api.sonetel.com/account/53535/phonenumbersubscription?account_id=2077654

To fetch all single number subscriptions in the sub-account, you can do the following.

https://api.sonetel.com/rest/account/53535/phonenumbersubscription

https://api.sonetel.com/rest/account/53535/phonenumbersubscription?account_id=2077654

https://api.sonetel.com/rest/account/53535/phonenumbersubscription?account_id=2077654

API-1.3.docx

August 30, 2016

(110)



Searching for all 10 number range subscriptions in the sub-account will retrieve all subscriptions for phone numbers that are part of the 10 number range. For e.g. if there is only one 10 number series in a sub-account, the search will return 10 individual subscriptions, one for each number that forms a part of the range.


To search for a specific series, the starting number of the range must be specified in the filter start_num

GET https://api.sonetel.com/account/53535/phonenumbersubscription?account_id=2077654&range=10&start_num=12144455010

5.6.3.Create

A phone number subscription is created when you want to buy a new phone number or phone number series from Sonetel, and add it to your main account or a sub account. This is done by issuing a POST to the phone number subscription list resource under your account. The charges for the phone number are debited from your account on a successful create, unless the subscription is created as a free test number subscription.

If you issue a POST to the phone number subscription list resource of a sub-account, the phone number subscription is automatically created under the sub-account.

To find a phone number that you want to buy, you can use the Number stock summary and Available phone number resources and identify a phone number.

Subscription for phone number series is created the same way that you create subscriptions for a phone number, except that you specify only the first/lowest phone number in the series along with the range in the request. Individual phone number subscription for each number in the series is automatically created as part of the Create request.

While creating phone number subscription, you may also, optionally, specify where the number is connected for receiving calls.

To create a subscription for free test, you should specify freetest as “yes”.





https://api.sonetel.com/rest/account/53535/phonenumbersubscription?account_id=2077654&range=10&start_num=12144455010

https://api.sonetel.com/rest/account/53535/phonenumbersubscription?account_id=2077654&range=10&start_num=12144455010

API-1.3.docx

August 30, 2016

(110)


POST https://api.sonetel.com/account/<account_id>/phonenumbersubscription

POST https://api.sonetel.com/account/53535/phonenumbersubscription


Property

Phnum


Property

range

connect_to_type

connect_to

freetest

The response carries the phone number subscription resource.

5.6.4.Update

Phone number subscription can be modified by issuing a POST or PUT to the phone number subscription resource.

The account to which the phone number is assigned can be changed. Also, you can modify where the phone number is connected.

For phone number series, you can update individual numbers in a series independently (for e.g. if you want to connect different numbers to different destinations). Alternately, you can update all the numbers in the series together, for e.g. in a case where you want to move the series to another sub-account. To update all numbers in a series together, you will have to use the phone number subscription list resource.

For e.g., to update all numbers in a 10 number series that stars with the number 12144455010, issue the following PUT or a POST request and specify the updated fields in the JSON content.

PUT https://api.sonetel.com/account/53535/phonenumbersubscription?account_id=2077654&series=yes&start_num=12144455010

https://api.sonetel.com/rest/account/%3caccount-id%3e/phonenumbersubscription

https://api.sonetel.com/rest/account/53535/phonenumbersubscription

https://api.sonetel.com/rest/account/53535/phonenumbersubscription?account_id=2077654&series=yes&start_num=12144455010

https://api.sonetel.com/rest/account/53535/phonenumbersubscription?account_id=2077654&series=yes&start_num=12144455010

API-1.3.docx

August 30, 2016

(110)


The response will return all numbers in the series with the updated values.

While changing the account_id to which a series is assigned, you must update the entire series by changing the account_id for all the numbers in the series together. In the case where the series is being changed from one account to another, connect_to_type and connect_to are reset to be set to “nowhere” automatically. A number subscription under free test can be converted to a paid subscription by specifying the freetest as “no” during an update. A number cannot be set for free test via an update i.e., freetest can never be specified as “yes” during an update. Please note that a number that reaches its free_test_expiry_date is automatically removed from the account, so the conversion to paid should be done prior to the expiry period.

POST https://api.sonetel.com/account/<account_id>/phonenumbersubscription/<phnum>/

or

PUT https://api.sonetel.com/account/<account_id>/phonenumbersubscription/<phnum>/

POST or PUT https://api.sonetel.com/account/53535/phonenumbersubscription/12145556666

The list of parameters that can be passed are listed here.

Parameter

account_id

connect_to_type

connect_to

freetest

The response carries the updated phone number subscription resource.

To update a single number subscription in the series

PUT https://api.sonetel.com/account/5533535/phonenumbersubscription/121455355005





API-1.3.docx

August 30, 2016

(110)


To UPDATE all the number subscriptions in the series, for e.g. in case you want to connect all numbers to a specific destination,

PUT https://api.sonetel.com/account/5533535/phonenumbersubscription?series=yes&start_num=121455350050

5.6.5.Delete

A phone number subscription can be removed from your account by issuing a DELETE to the phone number subscription resource.

Removing the phone number subscription permanently removes the phone number from your account. In the case of a series, you can issue a DELETE to the first/lowest phone number subscription in the series which deletes all the phone number subscriptions in the series.

DELETE https://api.sonetel.com/account/<account_id>/phonenumbersubscription/<phnum>/

DELETE https://api.sonetel.com/account/53535/phonenumbersubscription/12145556666

https://api.sonetel.com/rest/account/5533535/phonenumbersubscription?series=yes&start_num=121455350050

https://api.sonetel.com/rest/account/5533535/phonenumbersubscription?series=yes&start_num=121455350050



API-1.3.docx

August 30, 2016

(110)


5.7.Usage records

A usage records is created when you use a service from Sonetel. For e.g. when you make outbound calls, receive calls on your Sonetel phone number, a monthly subscription for Sonetel phone number, use SMS to email etc.

Each usage record has a unique Id. Usage records can only be retrieved.

Usage-records may have charges applied to them for the use of the service. However, not every usage record has a charge applied to it. For e.g. on-net calls within Sonetel are free and hence a usage record for an on-net call does not have a charge associated to it. Charges and their details are also included in the usage-records.

5.7.1.Properties

5.7.1.1.usagerecord


record_id The unique Id of the usage record.

timestamp The date/time when the service was used. In case of calls and services that are used over a period of time, the detailed specifications are provided in other fields.

service The service used

account_id The account_id that used the service. In the case the service is used in a sub-account, this field carries the account_id of the sub-account.

usage_details This field carries specific details about the usage depending on the service that is used. For e.g. in case of calls, it carries details of the calls including start and end time, caller-id etc.

charges The charges applied on the account for the usage.

5.7.1.2./usage_details/call


start_time The usage start date/time

end_time The usage end date/time

call_length The length of the call in seconds

from_type The endpoint type of source from where the call originated.

API-1.3.docx

August 30, 2016

(110)


from The endpoint Id of the source from where the call originated.

caller_id The caller-Id sent to to the called destination

to_type The endpoint type of destination where the call is sent

to The endpoint Id of the destination where the call is sent

5.7.1.3./usage_details/phnumsubscription


phnum The Sonetel phone to which this record applies. In case of a number series, the value in the field is the first phone number in the series.



city Name of the city where the number is. The name is descriptive and does not follow any standard.

type Type of number – This can be either “national”, “geographic”, or “tollfree

range Applicable if the phone number subscription is of a number that is a part of a phone number series. The value specifies the quantity of phone numbers in the number series of which this phone number is a part of


5.7.1.4./usage_details/priceplan


priceplan_package The priceplan package, such as “premium”, for which this usage record is created. Please note that this field represents the usage of the priceplan

priceplan_count The number of instances of the price_plan used

5.7.1.5./usage_details/inbound_sms


from The phone number from where SMS was sent

to The Sonetel phone number where the SMS was received

http://en.wikipedia.org/wiki/Caller_ID

API-1.3.docx

August 30, 2016

(110)


delivered_to2 The email address where the SMS was delivered.

5.7.1.6./usage_details/inbound_fax


from The phone number from where Fax was sent

to The Sonetel phone number where the Fax was received

delivered_to3 The email address where the Fax was delivered.

5.7.1.7./usage_details/overusage


type The type of overusage. This can take values “outbound_call_mins” or “inbound_call_mins”

period The period for which the overusage is calculated. This can take values “daily”, “weekly” or “monthly”

count The total instances of overusage.

unit The units for measuring overusage instance. This only takes the value “mins” representing minutes of overusage.

5.7.1.8./charges


priceplan The price plan applicable for charges. Price plans define special discounts/special prices for services. An account that adds/subscribes to a priceplan will have pricing applicable as per the priceplan.

currency The currency in which the charges are applied

count The number of usage instances that are charged. (For e.g. number of users in case of monthly premium charges)

usage_fixed The total instance fee charged to this usage record

usage_time The time usage fee charged to this record. This applies for calls that are normally charged per minute

2 In the future, when more delivery options for SMS such as web-hooks or apps are added, the field will be enhanced to handle this

3 In the future, when more delivery options for Fax such as web-hooks or apps are added, the field will be enhanced to handle this

API-1.3.docx

August 30, 2016

(110)


subscription_setup The one time fee charged to this usage record

subscription_recurring The recurring fee charged to this usage record

5.7.2.Fetch

Usagerecord supports both show and search. While fetching, partial response is also supported with the fields “charges”, “usage”

5.7.2.1.Show

Usage record is uniquely identified by the record-Id.

GET https://api.sonetel.com/1.3/account/<account_id>/usagerecord/record_Id

An example where a usage record of an outbound call is fetched.

GET https://api.sonetel.com/1.3/account/5533535/usagerecord/ 13244567

The response carries the following representation.

{

"record_id" : "13244567",

"timestamp" : "20140603T03:15:15GMT",

"service" : "outbound_call",

"account_id" : "34231",

"usage_details" : {

"call" : {

"start_time" : "20140603T03:15:15GMT",

"end_time" : "20140603T03:16:20GMT",

"call_length" : "65",

"from_type" : "user",

"from" : "51009676",

"caller_id" : "+15539785654",

"to_type" : "phonenumber",

"to" : "+16017778888",

"to_orig" : "6017778888",

},

},

"charges" : {


"currency" : "USD",

API-1.3.docx

August 30, 2016

(110)


"count" : "1",

"usage_time" : "0.06",

"usage_fixed" : "0.01",

}

}

5.7.2.2.Search

Usage records can be searched using filters.

GET https://api.sonetel.com/1.3/account/<account_id/usagerecord?filters

Example: GET https://api.sonetel.com/1.3/account/53535/usagerecord?account_id=2077654&service=inbound_sms

The list of filters is specified here.


start_time The service usage start date/time

end_time The service usage end date/time

account_id The account_id in the usage record

service The service used.

charge_type The type of charge that is applied to the usage record. This can take values “usage_fixed”, “usage_time”, “subscription_setup” and “subscription_recurring”

To get usage records for inbound calls, specify the service as inbound_call

GET https://api.sonetel.com/1.3/account/<account_id/usagerecord?service=inbound_call

[

{

"record_id" : "13244568",

"timestamp" : "20140603T03:15:15GMT",

"service" : "inbound_call",

"account_id" : "34231",

https://api.sonetel.com/rest/account/53535/usagerecord?account_id=2077654&service=inbound_sms

https://api.sonetel.com/rest/account/53535/usagerecord?account_id=2077654&service=inbound_sms

https://api.sonetel.com/rest/account/%3caccount_id/usagerecord?service=inbound_call


API-1.3.docx

August 30, 2016

(110)


}

{

"record_id" : "13245568",

"timestamp" : "20140609T03:15:15GMT",


"account_id" : "34231",

}

]

If you also want to get the call details for the inbound calls, you can request for additional fields in the response by adding usage as an additional field.

GET https://api.sonetel.com/1.3/account/<account_id/usagerecord?service=inbound_call&fields=usage

[

{

"record_id" : "13244568",

"timestamp" : "20140603T03:15:15GMT",


"account_id" : "34231",

"usage_details" : {

"call" : {

"start_time" : "20140603T03:15:15GMT",

"end_time" : "20140603T03:16:20GMT",


"from_type" : "phonenumber",

"from" : "+19722223434",

"caller_id" : "+19722223434",


"to" : "+12146007000",

"to_orig" : "+12146007000",

},

}

{

"record_id" : "13245568",

"timestamp" : "20140609T03:15:15GMT",


"account_id" : "34231",

"usage_details" : {

"call" : {



API-1.3.docx

August 30, 2016

(110)


"start_time" : "20140609T03:13:10GMT",

"end_time" : "20140609T03:15:10GMT",


"from_type" : "phonenumber",

"from" : "+19722223434",

"caller_id" : "+19722223434",


"to" : "+12146007000",

"to_orig" : "+12146007000",

},

}

]

To get charges for monthly subscription for phone numbers, set the service as phnum_subscription and fields as charges

GET https://api.sonetel.com/1.3/account/<account_id/usagerecord?service= phnum_subscription&fields=charges

[

{

"record_id" : "13244569",

"timestamp" : "20140603T03:15:15GMT",

"service" : "phnum_subscription",

"account_id" : "34231",

"charges" : {


"currency" : "USD",

"subscription_recurring" : "0.99",

}

}

]

If you want to get usage and charges for the monthly subscription specify both fields in the request

GET https://api.sonetel.com/1.3/account/<account_id/usagerecord?service= phnum_subscription&fields=charges,usage

[

{

API-1.3.docx

August 30, 2016

(110)


"record_id" : "13244569",

"timestamp" : "20140603T03:15:15GMT",

"service" : "phnum_subscription",

"account_id" : "34231",

"usage_details" : {

"phnumsubscription" : {

"phnum" : "+12146007000",

"country" : "USA",


"city" : "Dallas",


"range" : "1",


},

},

"charges" : {


"currency" : "USD",

"subscription_recurring" : "0.99",

}

}

]

Usagerecord does not support pagination yet. This means that if you fetch too many records, it could result in a lot of data being sent over the network. It is recommended that the searches are performed in an optimized way using start_time and end_time to get smaller sets of details till pagination options are made available via the API.

To get records for outbound calls during a specific time interval, you can specify the start_time and end_time accordingly.

GET https://api.sonetel.com/1.3/account/<account_id/usagerecord?service= outbound_call&start_time=20140603T03:14:15GMT&end_time= 20140603T03:16:00GMT&fields=usage

[

{

"record_id" : "13244567",

"timestamp" : "20140603T03:15:15GMT",

"service" : "outbound_call",

"account_id" : "34231",

API-1.3.docx

August 30, 2016

(110)


"usage_details" : {

"call" : {

"start_time" : "20140603T03:15:15GMT",

"end_time" : "20140603T03:16:20GMT",


"from_type" : "user",

"from" : "51009676",

"caller_id" : "+15539785654",


"to" : "+16017778888",

"to_orig" : "6017778888",

},

},

}

]

API-1.3.docx

August 30, 2016

(110)


5.8.Voice app

Voice applications in your account can be managed using the voice app resource.

Every voiceapp has a voice field, which is a set of pre-recorded messages or prompts grouped based on language, accent, male/female voices etc. These messages are played to callers interacting with a voiceapp. Sonetel provides ready-made voices that can be used in your voiceapp. Additionally, prompts in a voiceapp can be customized by replacing the default prompt in the voice with a custom prompt. A custom prompt can be replaced using the Sonetel recording service. In the next phase, it will also be possible to upload voice files to setup a custom prompt.

When a sub-account is created, two default voice apps, an ivr and sysprompt are automatically created under the sub-account. These two default voiceapps cannot be deleted.

Voice apps can be created, fetched, searched, updated and deleted.

Deleting a voice app removes the app from your account.

5.8.1.Properties

5.8.1.1.voiceapp

The voice-app resource has the following properties.


app_id The unique app Id of the voice app in Sonetel

name The name of the voiceapp

app_type The voice app type.

shortcode The dial code that can be dialed or setup as a forwarding destination to connect calls to the voice app.

sip_address The SIP address of the voice app

voice The set of pre-recorded voice prompts for the voice app. The list of supported voice are here.

play_welcome A flag that indicates if the Welcome message is played or not.

get_extension A flag that indicates if the auto-attendant function is active.

play_menu A flag that indicates if the interactive voice menu function(receive digits from callers to take actions) is active or not.

final_action The final action that is taken in case the menu (represented by field play_menu) is not active.

menu The voice response menu that defines the digits and the actions taken on each digit press

http://sonetel.com/en/help/support-center/help-topics/voice-response/how-can-i-record-my-own-messages/



http://sonetel.com/en/help/support-center/help-topics/voice-response/http:/www.sonetel.com/site/pmwiki.php?n=Admin.EditWelcomeMenu


API-1.3.docx

August 30, 2016

(110)


error_voice The voice that applies for playing system messages. This field applies in case the app_type is “sysprompt”.

error_repeat_voice In case the same system message is required to be played in two different voices, the error_repeate_voice field specifies the voice for playing the system messages in a second voice. This may be used, for e.g., in case there are two different languages in which the error message needs to be played to the callers. This field applies in case the app_type is “sysprompt”.

greeting_prompt A flag that indicates if a greeting message is played when a caller reaches the voicemail. This field applies in case the app_type is “mailbox”

goodbye_prompt A flag that indicates if a goodbye message is played when a caller has left a voicemail message. This field applies in case the app_type is “mailbox”

deliver_to Voicemails are delivered as email attachments. This field can specify either a user or an email address to which the voicemail are delivered. This can take values “user” or “email”

This field applies in case the app_type is “mailbox”

deliver_to_details If “deliver_to” is a user, this field takes the user_id of the user. The email is delivered to the email address of the user configured in the Sonetel account.

If “deliver_to” is an email, this field takes the email address to which the voicemail is delivered.

5.3.1.1.1 Action blocks

Voice apps interact with a caller, which includes taking digits, playing messages and connecting and forwarding calls. An action block is used in voice apps to define instructions for such interaction with the user.

An Action block has three fields

action: The action that has to be taken. This could be one of the below

o call: Forward the call to a destination o play: Play a specific prompt o connect: Continue to process another voice app o disconnect: Disconnect the call

to: Depending on the action to be taken, this defines the type of function on which the action is to be taken.

Id: This specifies the unique Id of the function based on the action.

The table below specifies the scenarios and the possible values that the fields can take in the scenario.

http://www.sonetel.com/site/pmwiki.php?n=Admin.SystemPrompts

http://www.sonetel.com/site/pmwiki.php?n=Admin.SystemPrompts



API-1.3.docx

August 30, 2016

(110)


Description action to id

Connect the call to a user

call user user_Id

Connect the call to a SIP address or a phone number

call other Phone number or SIP address

Play a prompt play prompt prompt_Id

Connect the call to another voice app

connect app app_Id OR

To connect to callthru, it takes the value “callthru”

Disconnect the call

disconnect -NA- -NA-

5.8.1.2.voiceapp/final_action


action The action to be taken. This can take values “call”, “play”, “connect”, “disconnect”

to See here for details

id See here for details

5.8.1.3.voiceapp/menu


digit_<x> In an ivr, action blocks can be defined on digits 0 to 9. digit_<x> represents a field where the value of the field is an action block that specifies the action to be taken when the digit is pressed. For e.g.

digit_1:{action:call, to: other, id: +12223334444}.

This implies that if the caller presses digit 1, the call should be forwarded to the phone number +12223334444.

timeout In case the caller does not press any digit till the IVR times out (10 mins), this field defines the action to be taken under that condition.

5.8.1.4.voiceapp/menu/digit_<x>


API-1.3.docx

August 30, 2016

(110)


action Can take values “play”, “call”, “connect”. An empty value indicates that no action is taken.

to See here for details

id See here for details

5.8.2.Fetch

A voice app can either be retrieved using its app_id or searched using filters.

5.8.2.1.Show

A voice app can be fetched using its app_id as below.

GET https://api.sonetel.com/1.3/account/<id>/voiceapp/<app_id>

Example: GET https://api.sonetel.com/1.3/account/5353534/voiceapp/VA234454654

A voice app resource has the following details.

{

"response":

{

{

"app_id" : "VA234454654",

"name" : "English menu",

"app_type" : "ivr",

"shortcode" : "*21*1",

"voice" : "en-mycompany",

"sip_address" : "[email protected]",

"play_welcome" : "yes",

"get_extension" : "yes",

"menu" : {

"digit_1": {

"action" : "call",

"to" : "user",

"id" : "2023523233",

}

"digit_2": {

"action" : "play",

"to" : "promptid",

https://api.sonetel.com/rest/account/5353534/voiceapp/VA234454654

API-1.3.docx

August 30, 2016

(110)


"id" : "2021434543",

}

"timeout": {

"action" : "connect",

"to" : "app",

"id" : "2023242354",

}

}

}

},

"resource": voiceapp,

"status": "success"

}

5.8.2.2.Search

A sub-account can be searched using filters passed as query string parameters to the account list resource.

GET https://api.sonetel.com/1.3/account/5353534/voiceapp?filters


Filter Description

name Exact/partial voice app name. This is a string wild card search.

app_type The application type can be searched for three types. “ivr”, “sysprompt” and “mailbox”.

Example: GET https://api.sonetel.com/1.3/account/5353534/voiceapp?name=Announcement%20before%20divert” The response carries a list of voiceapp resources.

{

"response":

[

{

"app_id" : "VA234454658",

"name" : "Announcement before divert",


https://api.sonetel.com/rest/account/5353534/voiceapp?name=Announcement%20before%20divert

https://api.sonetel.com/rest/account/5353534/voiceapp?name=Announcement%20before%20divert

API-1.3.docx

August 30, 2016

(110)


"app_type" : "ivr",

"shortcode" : "*21*2",

"voice" : "en-mycompany",

"sip_address" : "[email protected]",

"play_welcome" : "yes",

"get_extension" : "no",

"play_menu" : "no",

"final_action": {

"action" : "call",

"to" : "user",

"id" : "2023523233",

}

}

]

"resource": voiceapp,

"status": "success"

}

5.8.3. Create

Voice apps can be created via a POST request to the voice app list resource.

POST https://api.sonetel.com/1.3/account/5353534/voiceapp


Property

name

app_type


Property

voice

play_welcome

get_extension

play_menu

final_action

menu

error_voice


API-1.3.docx

August 30, 2016

(110)


error_repeat_voice

greeting_prompt

goodbye_prompt

deliver_to

deliver_to_details

The response to a successful request carries the resource representation of the newly created sub-account.

5.8.4.Update

Voice apps can be updated by issuing a PUT to the account.

PUT https://api.sonetel.com/1.3/account/5353534/voiceapp/<voice app Id>

Example: https://api.sonetel.com/1.3/account/5353534/voiceapp/2034332323

The following parameters can be updated

Property

Name

voice

play_welcome

get_extension

play_menu

final_action

menu

error_voice

error_repeat_voice

greeting_prompt

goodbye_prompt

deliver_to

deliver_to_details

https://api.sonetel.com/rest/account/5353534/voiceapp/%3cvoice


API-1.3.docx

August 30, 2016

(110)


5.8.5.Delete

Voice apps can be deleted by issuing a POST to the voiceapp resource

DELETE https://api.sonetel.com/1.3/account/5353534/voiceapp/<voice app Id>

Example: DELETE https://api.sonetel.com/1.3/account/5353534/voiceapp/2034332323

The deleted resource is sent in the response.

https://api.sonetel.com/rest/account/5353534/voiceapp/%3cvoice


API-1.3.docx

August 30, 2016

(110)


5.9.Prompt

A Prompt represents a voice message in a voice app. Prompts can be created, retrieved, deleted and updated with the exception that voiceapps have a set of default prompts that cannot be created or deleted.

Each prompt has a unique prompt_id, through which it is referenced in the voice app. The prompt_id can be specified in an action block in the voice app to have the voice message played under defined condition. For e.g. play (action) a specific prompt (prompt_id) when digit 3 is pressed (condition) by the user.

Every prompt has a voice message associated to it. When a prompt is created, the voice message file can subsequently be uploaded to the prompt. The uploaded file is then set as the voice message for the prompt. Alternately, a voice message file can be recorded by calling in to the prompt recording function.

When a voice app is created, default prompts in a voice app are automatically created along with it. For all default prompts, Sonetel provides standard pre-recorded voice messages. The voice setting in the voice app defines the language and the corresponding standard voice message that is played when the prompt is used. For e.g. if you set the voice as “en”, the prompt that plays a welcome message to the caller, would play the audio message “Welcome” in an English, male voice. If you change the voice to “se”, the message changes to the equivalent message in a Swedish, male voice.

Default prompts can also be customized in the same way as regular prompts, by uploading a voice file or via the prompt recording function.

Deleting a prompt removes the prompt from the voice app.

5.9.1.Properties

The prompt resource has the following properties.


prompt_id The unique Id of the prompt

type Takes values “custom” or “standard”. Specifies if the associated voice message is a custom message or a standard message. A custom message is one that has been recorded or uploaded by the customer, while a standard message is a pre-recorded message provided by Sonetel

name A descriptive name of the prompt as defined by the customer.

app_id The voiceapp app_id the prompt belongs to

account_id The account that the prompt belongs to

record_id The Id of the prompt that can be dialed via DTMF digits when updating the voice message from the recording

http://www.sonetel.com/site/pmwiki.php?n=Admin.WelcomeMenuRecordedMessages


API-1.3.docx

August 30, 2016

(110)


function. The recording function can be accessed through IP-telephony phones, Sonetel call-thru, callback or using the Sonetel callback API

exists A flag that specifies if the associated voice message for this prompt exists. This flag is only relevant in case of custom prompts. For standard prompts, the flag is always “yes” since there is always a voice message associated to a standard prompt.

If there is no voice message associated for the prompt, the prompt cannot be used in a voice app.

file_name The name of the audio file uploaded by the customer. The field is empty if no file has been uploaded.

audio_length The length of the audio in seconds.

size The size of the file in kilobytes.

message_url The URL of the voice message of the prompt. This is the URL where the voice file for the prompt can be accessed and uploaded.

5.9.2.Fetch

A specific prompt can be fetched using the prompt_id. Prompts can also be searched under a voiceapp using filters. Prompt supports partial response with the field message.

5.9.2.1.Show

A prompt can be fetched using its prompt_id as below.

GET https://api.sonetel.com/1.3/account/5353534/voiceapp/9822345/prompt/PT132435

This returns a response carrying a basic representation of the prompt resource excluding details related to the voice message.

{

"prompt_id" : "PT132435",

"type" : "standard",

"name" : "Welcome",

"record_id" : "2021",

"app_id" : "9822345",

"account_id" : "5353534",

"exists" : "yes",

}

To get all details, including the voice message details,



API-1.3.docx

August 30, 2016

(110)


GET https://api.sonetel.com/1.3/account/5353534/voiceapps/9822345/prompt/PT132435?fields=message

{


"type" : "standard",

"name" : "Welcome",

"record_id" : "2021",

"app_id" : "9822345",

"account_id" : "5353534",

"exists" : "yes",

"fle_name" : "",

"create_date" : "",

"size" : "",

"audio_length" : "12",

"message_url" : "api.sonetel.com/prompt/PT132439/message",

}

The above is a representation of a standard prompt. If it’s a custom prompt, it looks a little different.

{


"type" : "custom",

"name" : "Press 1 for details",

"record_id" : "2030",

"app_id" : "9822345",

"account_id" : "5353534",

"exists" : "yes",

"fle_name" : "press_for_details.wav",

"create_date" : "20141010T19:55:45Z",

"size" : "435",

"audio_length" : "15",


}

In case of a custom prompt, the create_date and size are also specified.

In case the prompt does not have any voice message associated to it, the representation appears like this.

{

https://api.sonetel.com/rest/account/5353534/voiceapps/9822345/prompt/PT132435?fields=message

https://api.sonetel.com/rest/account/5353534/voiceapps/9822345/prompt/PT132435?fields=message

API-1.3.docx

August 30, 2016

(110)



"type" : "custom",

"name" : "Press 2 to change language",

"record_id" : "20131",

"app_id" : "9822345",

"account_id" : "5353534",

"exists" : "no",

"fle_name" : "",

"create_date" : "",

"size" : "",

"audio_length" : "",


}

Instead of a using a full path URL (url that includes the account and voice app Id in its path), you can also access a prompt using a general url such as

GET https://api.sonetel.com/1.3/prompt/PT132435

5.9.2.2.Search

Prompts under voice app can be listed using the prompt list resource.

The following filters are available.

Filter Description

name Exact/partial prompt name. This is a string wild card search.

type The type of prompt; custom or standard

app_id The voiceapp Id to which this prompt belongs

account_id The account_id to which this prompt belongs

The prompts list resource is available at GET https://api.sonetel.com/1.3/prompt

To get the list of all prompts under all voice apps in all sub-accounts in your main account, with name containing “press” GET https://api.sonetel.com/1.3/prompt?name=press

https://api.sonetel.com/rest/

https://api.sonetel.com/rest/

https://api.sonetel.com/rest/prompt?name=press

API-1.3.docx

August 30, 2016

(110)


The response carries a list of prompt resources matching the name “press”.

[

{


"type" : "custom",

"name" : "Press 1 for details",

"record_id" : "2030",

"app_id" : "9822345",

"account_id" : "5353534",

"exists" : "yes",

}

{


"type" : "custom",

"name" : "Press 2 to change language",

"record_id" : "20131",

"app_id" : "9822345",

"account_id" : "5353534",

"exists" : "no",

}

To get the prompts only under a specific sub-account,

GET https://api.sonetel.com/1.3/prompt?name=Press&account_id=5353534

To get prompts under a specific voiceapp including the voice message details

GET

https://api.sonetel.com/1.3/prompt?name=Press&app_id=5353534&fields=message

You can also search for prompt using the full path url

GET

https://api.sonetel.com/1.3/account/5353534/voiceapp/9822345/prompt?name=Press&fields=message

5.9.3.Create

You can create one or more prompts under a voiceapp. The voice message associated to a prompt can be setup in different ways. You can upload an audio file with the voice message. Alternately, you can record the voice message by calling in to the recording service. In the future, it

https://api.sonetel.com/rest/account?filters

https://api.sonetel.com/rest/prompt?name=Press&app_id=5353534&fields=message

https://api.sonetel.com/rest/prompt?name=Press&app_id=5353534&fields=message

https://api.sonetel.com/rest/account/5353534/voiceapp/9822345/prompt?name=Press&fields=message

https://api.sonetel.com/rest/account/5353534/voiceapp/9822345/prompt?name=Press&fields=message

API-1.3.docx

August 30, 2016

(110)


will also be possible to specify a text which is then converted to the voice message using automatic text-to-speech functions.

Creating a prompt and associating a voice message to it, is hence, setup as a two-step process.

The first step involves creation of the prompt resource and setting its properties. At this stage, the prompt does not have any voice message associated to it and is not usable in the voiceapp.

This is done by issuing a POST to the prompt resource. The field name must be specified as a parameter in the request.

POST https://api.sonetel.com/1.3/account/5353534/voiceapp/2034332323/prompt?name=We%20are%20closed

In response, you will receive the created prompt resource.

{


"type" : "custom",

"name" : "We are closed",

"record_id" : "20131",

"app_id" : "9822345",

"account_id" : "5353534",

"exists" : "no",

"fle_name" : "",

"create_date" : "",

"size" : "",

"audio_length" : "",


}

The response contains a message_url, which is where the audio file with the message can be uploaded or accessed.

The response also has the field exists set to “no” implying that the voice message for this prompt does not exist yet. The type of the prompt that is created via the API is always “custom”. You cannot create or delete “standard” prompts via the API, but you can add and delete “custom” prompts.

To upload the voice file, you can issue a POST to the message URL along with the file in the body. The file should be .WAV file, PCM uncompressed, 16 bit with a maximum size of 10 mb, and passed as a multi-part form-data object.

POST https://api.sonetel.com/prompt/PT132439/message

https://api.sonetel.com/rest/account/5353534/voiceapp/2034332323/prompt?name=We%20are%20closed

https://api.sonetel.com/rest/account/5353534/voiceapp/2034332323/prompt?name=We%20are%20closed

https://api.sonetel.com/prompt/PT132439/message

API-1.3.docx

August 30, 2016

(110)


If, instead of uploading a voice file, you want to record the voice message using the recording service, it can be done by calling into the recording service available at TBD. A voice message created using the recording service is also available at the message_url.

There can only be a single voice message per prompt. So, in case you upload a voice message to the message_url or record a voice message via the recording function, any existing voice message is replaced with the newly uploaded or recorded one.

5.9.4.Update

The only field that you can update in a prompt is the name. This can be done by issuing a POST to the prompt.

POST https://api.sonetel.com/prompt/PT132439

Besides that, the voice message can be updated by issuing a POST to the message along with the voice file that will replace the existing voice message.

5.9.5.Delete

Prompts can be deleted by issuing a DELETE to the prompt resource, either using the full path url or the general url

To delete using the full path url.

DELETE https://api.sonetel.com/1.3/account/5353534/voiceapps/2034332323/prompt/1032434344

Response to a successful method call carries a string with confirmation.

To delete using the general url, you can issue the following request.

DELETE https://api.sonetel.com/1.3/prompt/1032434344

If you only want to remove the voice message associated to a prompt,

DELETE https://api.sonetel.com/1.3/account/5353534/voiceapps/2034332323/prompt/1032434344

If you delete a voice message associated to a default prompt, the voice message in the prompt will simply get replaced by the standard voice message. For non-default prompts, the voice message will get deleted completely and exists flag in the prompt will change to “no”.

https://api.sonetel.com/prompt/PT132439


https://api.sonetel.com/rest/prompt/

https://api.sonetel.com/rest/account/5353534/voiceapps/2034332323/prompt/1032434344

https://api.sonetel.com/rest/account/5353534/voiceapps/2034332323/prompt/1032434344

API-1.3.docx

August 30, 2016

(110)


5.10.Country

The country resource represents standard details of a country such as the telephone country code, the ISO country code etc. It also includes phone number coverage and pricing per country.

Country is a list resource and can only be fetched.

5.10.1.Properties

The country resource has the following properties.


country The country’s ISO code.

name Country name


phonenumbers Information on local phone numbers that are supported in the country

5.10.1.1. /country/phonenumbers

phonenumbers is a list of entries under a country, with each entry carrying information about a specific type of phone number(national, tollfree or geographic) in that country.

You can view the capabilities and services available of the phone number type such as support for SMS or Fax.

You can also view if the numbers of this type are available for free testing in the country. Free test numbers can be assigned to your account by creating a phnumsubscription with a special flag.

In some countries, local telephone authorities may require address information and/or address proof document to be submitted while purchasing phone numbers of a particular type. This information is also available per number type via the API. The API does not yet support upload of such information, which makes it impossible to purchase numbers in such countries via the API.

Toll-free numbers in many countries are only reachable from some types of phones. For e.g. they may not be reachable from pay-phones or mobile phones, or from outside the country. You can get information about such restrictions in the access_restrictions field.


type “national”, “geographic”, or “tollfree” number types can be specified

freetest Flag specifying if numbers of this type are available for free test in this country

API-1.3.docx

August 30, 2016

(110)


fax_support Flag that specifies if this type of number can receive Fax. Fax has to be explicitly activated per phone number. For more details, see http://www.sonetel.com/site/pmwiki.php?n=Admin.Fax-to-email.

sms_support Flag that specifies if phone numbers of this type can receive SMS

addr_req Specifies if there is any requirement to have an address to purchase and use this type of phone number

addr_proof A flag that specifies if an address proof is required to be submitted for this type of phone number.

access_restrictions Specifies the phone number reachability from different networks

restrictions_desc A general text specifying restrictions applicable to numbers of the specific type within the country.

price The price details for the type of phone number

5.10.1.2./phonenumbers/price

You can get pricing information for the number type via the API. This is available under price.


currency The currency in which the price is specified

range The number series. The value specifies the total phone numbers in a phone number series. For e.g. for a single number, the value is “1”. For a 10 number series, the value is “10” etc.

price_category The price category of the number. This can take values 1- regular, 2- gold, 3 - gold+, 4 - gold++, 5 -gold+++. This field only applies to single numbers.

one_time_fee One-time fee for purchasing the number(s). Up to 2 decimals.

recurring_fee Periodic fee on purchasing the number(s). Up to 2 decimals.

recurrence_interval The recurrence interval for the recurring fee. Specified in days(e.g. 15d) or months(e.g. 3m)

per_call_fee The per call fee applicable for calls to the number. Up to 3 decimals.

per_min_fee The charge per minute for calls to the number. Up to 3 decimals.

charge_interval The charge interval in seconds for calls to the number.

http://www.sonetel.com/site/pmwiki.php?n=Admin.Fax-to-email

http://www.sonetel.com/site/pmwiki.php?n=Admin.Fax-to-email

API-1.3.docx

August 30, 2016

(110)


per_sms_fee The per SMS receiving fee applicable Up to 2 decimals.

per_fax_fee The per FAX receiving fee applicable Up to 2 decimals.

Phone numbers are priced differently based on their type (national, geographic, toll-free). Also, numbers that look good, that are easy to remember, are categorized as GOLD numbers and are priced differently. The field price_category specifies the category of the number.

A number series, having either 10, 20 or 100 numbers in a series are usually available at a discount. The field range specifies if the price information is for a number series.

5.10.2.Fetch

Country is a list resource and can be used to fetch one or many entries based on the filters applied.

GET https://api.sonetel.com/1.3/country?filters

Example: GET https://api.sonetel.com/1.3/country?phnum_sup=yes&type=national,geographic&name=USA

The following filters apply.

Filter Description

country The country ISO code.

name Country name. Allows string wild card search

country_code The telephony country code as per ITU standards

phnum_support Flag that specifies searching for countries where phone numbers are supported

freetest Flag that specifies searching for countries where free test phone numbers are supported.

type “national”, “geographic”, or “tollfree” number types can be specified. This is a multi-value filter

sms_support Flag to specify searching for countries where phone numbers support fax

fax_support Flag to specify searching for countries where phone numbers support SMS

range The count of numbers in a number series

price_category The price category of the number. This can take values 1- regular, 2- gold, 3 - gold+, 4 - gold++, 5 -gold+++

http://www.sonetel.com/site/pmwiki.php?n=Admin.PhoneNumbersFromSonetel

https://api.sonetel.com/rest/country?phnum_sup=yes&type=national,geographic&name=USA

https://api.sonetel.com/rest/country?phnum_sup=yes&type=national,geographic&name=USA

API-1.3.docx

August 30, 2016

(110)


currency The currency in which price data is to be returned. The default is assumed to be USD

The country resource supports partial response. Currently, only the field price is supported.

The default response returns country information and phonenumbers(excluding the price)

GET https://api.sonetel.com/1.3/country?country=USA

[

{

"country" : "USA",

"name" : "USA",


"phonenumbers" : {

[

{


"freetest" : "yes",



"addr_req" : "none",

"addr_proof" : "no",


"restrictions_desc" : "some text",

},

{

"type" : "toll-free",

"freetest" : "no",

"fax_support" : "no",

"sms_support" : "no",





}

]

https://api.sonetel.com/rest/country?country=USA

API-1.3.docx

August 30, 2016

(110)


To get price information for numbers in USA,

GET https://api.sonetel.com/1.3/country?fields=price&country=USA

[

{

"country" : "USA",

"name" : "USA",


"phonenumbers" : {

[

{


"freetest" : "yes",







price:{

"range" : "1",






"per_min_fee" : "0.01",


"per_sms_fee" : "0.01",

"per_fax_fee" : "0.01",

"currency" : "USD",

},

{

"range" : "1",






"per_min_fee" : "0.01",


"per_sms_fee" : "0.01",

"per_fax_fee" : "0.01",

https://api.sonetel.com/rest/country?fields=price&country=USA

API-1.3.docx

August 30, 2016

(110)


"currency" : "USD",

},

{

"range" : "10",






"per_min_fee" : "0.01",


"per_sms_fee" : "0.01",

"per_fax_fee" : "0.01",

"currency" : "USD",

},

{

"range" : "20",






"per_min_fee" : "0.01",


"per_sms_fee" : "0.01",

"per_fax_fee" : "0.01",

"currency" : "USD",

},

},

{

"type" : "toll-free",

"freetest" : "no",

"fax_support" : "no",






}

]

To get the coverage and price of National single numbers world-wide

API-1.3.docx

August 30, 2016

(110)


GET https://api.sonetel.com/1.3/country?fields=price&type=national&range=1

[

{

"country" : "HKG",

"name" : "Hong Kong",


"phonenumbers" : [

{

"type" : "national",

"freetest" : "yes",






"restrictions_desc" : "",

"price": [

{

"range" : "1",






"per_min_fee" : "0.01",


"per_sms_fee" : "",

"per_fax_fee" : "0.01",

"currency" : "USD",

},

{

"range" : "1",






"per_min_fee" : "0.01",


"per_sms_fee" : "",

https://api.sonetel.com/rest/country?fields=price&type=national&range=1

API-1.3.docx

August 30, 2016

(110)


"per_fax_fee" : "0.01",

"currency" : "USD",

}

]

}

]

},

{

"country" : "SWE",

"name" : "Sweden",


"phonenumbers" : [

{

"type" : "national",

"freetest" : "yes",






"restrictions_desc" : "",

"price": [

{

"range" : "1",






"per_min_fee" : "0.01",


"per_sms_fee" : "",

"per_fax_fee" : "0.01",

"currency" : "USD",

},

{

"range" : "1",






API-1.3.docx

August 30, 2016

(110)


"per_min_fee" : "0.01",


"per_sms_fee" : "",

"per_fax_fee" : "0.01",

"currency" : "USD",

}

]

}

]

},

]

API-1.3.docx

August 30, 2016

(110)


5.11.price-list/outboundcalls-price

The outboundcalls-price resource presents the pricing details for making outbound calls using Sonetel.

5.11.1.Properties

The outboundcalls-price resource has the following properties.


name The name of the call destination. E.g. “Argentina” or “Argentina mobile” etc.

country The call destination country

country_name The call destination country name

currency Currency in which the price is reported

per_call_fee The per call fee applicable for calling to this destination. This fee is also sometimes called the call setup fee/charge and is a fixed fee that is charged when a call is successfully connected. Up to 3 decimals

usage_fee The usage fee for time of the call, applicable for calling to this destination. Up to 3 decimals

charge_interval The charge interval for the usage fee in seconds for calls to the destination. This is usually 60 secondss, which implies that the call is billed in increments of 1 minute.

priceplan The priceplan under which this price applies. Sonetel Premium provide discounts on the price of outbound calls. If the price details (usage_fee and per_min_fee) are for premium, this field can take the value “premium”. Otherwise, it takes the value “regular”.

dialcode_list A comma separated list of prefix dial codes for this destination. It is the destination within the country that has the longest matching dialcode – compared with dialed number - that defines the cost for calling the number

tags A set of tags associated to this price information. Currently, this can only take the value “default” or can be empty. “default” represents that this particular price detail corresponds to the default price in the country. In most countries, the price to call mobiles, landlines or other special destinations differ. One, out of these destinations is marked as a default, to assist user interface design in consuming and showing a price per country.

The outboundcalls-price shows the pricelist for making international phone calls via Sonetel in the form of a list of entries. Each entry in the pricelist is the price to call a certain destination, in a certain currency under, a certain priceplan.

http://www.sonetel.com/en/html/prices/premium-usd.shtml

API-1.3.docx

August 30, 2016

(110)


Calls to different numbers in the same country may have different rates. For e.g. calling mobile numbers in a country may have a different price than calling a landline number. Each such unique destination has a name which is a simple name describing the destination.

Certain destinations may not belong to a country, such as satellite phones from Inmarsat or iNUMs. In such cases, the country field is not relevant and is empty.

The pricelist is available in 3 currencies. SEK, USD and Euro.

Most destinations have a fixed per min fee for making calls. Some destinations may have a setup fee, which is a fixed fee charged when the call connects successfully.

5.11.2.Fetch

An outboundcalls-price is special in a way that it does not support a Show operation. Rather, only Search is supported.

5.11.2.1.Search

An outboundcalls-price can be searched using filters passed as query string parameters to the outboundcalls-price resource.

GET https://api.sonetel.com/1.3/price-list/outboundcalls-price?filters


Filter Description

country Price details for calling to this country

currency Currency in which the price is required

priceplan Price under a special priceplan. Some services such as the Sonetel Premium provide discounts and affect the price of outbound calls. This filter can be used to retrieve the price for outbound calls under the specific priceplan.

Currently, this filter can take the value “premium” or “regular”. E.g. priceplan=”premium” or priceplan=”premium”,”regular”

In case no priceplan is specified, the prices are as per the “regular” priceplan.

This is a multi-value filter

To get the price in a specific country, say India, in EURO and under regular and premium priceplans,

http://en.wikipedia.org/wiki/Inmarsat

http://en.wikipedia.org/wiki/INum_Initiative

https://api.sonetel.com/1.3/price-list/outboundcalls-price?filters

API-1.3.docx

August 30, 2016

(110)


GET https://api.sonetel.com/1.3/price-list/outboundcalls-price?country=IND&currency=EUR

[

{

"name" : "India",

"country" : "IND",

"country_name" : "India",

"currency" : "EUR",


"usage_fee" : "0.012",



"dialcode_list" : "91,916",

"tags" : "default",

},

{

"name" : "India mobile",

"country" : "IND",


"currency" : "EUR",


"usage_fee" : "0.016",



"dialcode_list" : "91,918,919,91772",

"tags" : "",

},

]

To get the price in India, in EURO and only under premium,

GET https://api.sonetel.com/1.3/price-list/outboundcalls-price?country=IND&currency=EUR&priceplan=premium

[

{

{

"name" : "India",

"country" : "IND",


https://api.sonetel.com/1.3/price-list/outboundcalls-price?country=IND&currency=EUR

https://api.sonetel.com/1.3/price-list/outboundcalls-price?country=IND&currency=EUR

https://api.sonetel.com/1.3/price-list/outboundcalls-price?country=IND&currency=EUR&priceplan=premium

https://api.sonetel.com/1.3/price-list/outboundcalls-price?country=IND&currency=EUR&priceplan=premium

API-1.3.docx

August 30, 2016

(110)


"currency" : "EUR",


"usage_fee" : "0.009",



"dialcode_list" : "91,916",

"tags" : "default",

},

{

"name" : "India mobile",

"country" : "IND",


"currency" : "EUR",


"usage_fee" : "0.011",



"dialcode_list" : "91,918,919,91772",

"tags" : "",

},

]

You can get the complete pricelist for all destinations in all currencies under in the regular priceplan using GET https://api.sonetel.com/1.3/price-list/outboundcalls-price

To get the price for all destinations in only USD

GET https://api.sonetel.com/1.3/price-list/outboundcalls-price?currency=USD

https://api.sonetel.com/1.3/price-list/outboundcalls-price

https://api.sonetel.com/1.3/price-list/outboundcalls-price?currency=USD

https://api.sonetel.com/1.3/price-list/outboundcalls-price?currency=USD

API 1 - Sonetel · API 1.3 August 30, 2016 Mailbox 647 11411 Stockholm Sweden...

Documents

Transcript of API 1 - Sonetel · API 1.3 August 30, 2016 Mailbox 647 11411 Stockholm Sweden...