API 1.3 - Sonetel

Transcription

API 1.3 - Sonetel

API 1.3
August 30, 2016
Mailbox 647
11411 Stockholm
Sweden
[email protected]
help.sonetel.com/api
API-1.3.docx
August 30, 2016
Page 2 (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.
5.
4.4.
Authentication........................................................................... 9
4.5.
API versions ........................................................................... 10
4.6.
General notes ......................................................................... 10
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.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
Partial response ................................................................ 9
Properties ........................................................................ 50
API-1.3.docx
August 30, 2016
Page 3 (110)
5.4.2.
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.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
Fetch ............................................................................... 51
price-list/outboundcalls-price ............................................. 107
5.11.1.
Properties .................................................................. 107
5.11.2.
Fetch ......................................................................... 108
API-1.3.docx
August 30, 2016
Page 4 (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


1.3.02
2015-06-16
Prashant
Ability to upload voice prompts
Price for phone numbers and for making calls
to mobiles and landlines
API version 1.3.3. Improvements from 1.3 include

Mailbox 647
11411 Stockholm
Sweden
[email protected]
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
Page 5 (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.








Mailbox 647
11411 Stockholm
Sweden
[email protected]
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
Page 6 (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.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 7 (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.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 8 (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].
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 9 (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.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 10 (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.





Mailbox 647
11411 Stockholm
Sweden
[email protected]
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
API-1.3.docx
August 30, 2016
Page 11 (110)










Mailbox 647
11411 Stockholm
Sweden
[email protected]
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.
API-1.3.docx
August 30, 2016
Page 12 (110)



Mailbox 647
11411 Stockholm
Sweden
[email protected]
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
Page 13 (110)




Mailbox 647
11411 Stockholm
Sweden
[email protected]
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
API-1.3.docx
August 30, 2016
Page 14 (110)
o
o
o
o
o
o
o
o
o
o

Mailbox 647
11411 Stockholm
Sweden
[email protected]
swe  Swedish male
spa Spanish male
hin-fe  Hindi female
tam-fe  Tamil female
tel-fe  Telugu female
en-fe  English female
gr-fe  Greek female
en-uk-fe  English(UK accent) female
fr-fe  French female
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
Page 15 (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
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/outboundcallsprice
No
No
Yes
No
No
Matrix
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.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
Property
Description
id
The unique account Id of the company account in Sonetel
API-1.3.docx
August 30, 2016
Page 16 (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
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 17 (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.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 18 (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 subaccount 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.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 19 (110)
Property
Description
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”




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
credit_balance
The account balance in the account’s currency specified up
to 2 decimals.
priceplan
The priceplan that applies to this sub-account. Subaccounts 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

Mailbox 647
11411 Stockholm
Sweden
[email protected]
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 and change rules
API-1.3.docx
August 30, 2016
Page 20 (110)
o
o
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.
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.
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
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 21 (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”
country
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",
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 22 (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 subaccount template under your main account. A sub-account template is a
collection of account parameters and their values. Instead of passing
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 23 (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
Mailbox 647
11411 Stockholm
Sweden
[email protected]
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
area_code
address
If this is not specified, this field is not set
address2
city
zipcode
user_lname
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
Page 24 (110)
priceplan
If this is not specified, the priceplan is set to
“regular”
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
Property
Description
name
See here for details
status
status_desc
area_code
address
address2
city
zipcode
country
change_balance
A value by which the current credit_balance must
be updated. 2 digit decimal value.
priceplan
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
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 25 (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
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 26 (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.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
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
Page 27 (110)
5.3.1.1./<user-id>/call
Property
Description
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
Property
Description
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.
Property
Description
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



Mailbox 647
11411 Stockholm
Sweden
[email protected]
“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
Page 28 (110)

ring_time
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”.
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.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
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
Page 29 (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.
Property
Description
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.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
Property
Description
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
API-1.3.docx
August 30, 2016
Page 30 (110)
Each item in the phones list has the following fields
Property
Description
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
Property
Description
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.
Property
Mailbox 647
11411 Stockholm
Sweden
[email protected]
Description
API-1.3.docx
August 30, 2016
Page 31 (110)
number_id
Unique Id of the number
number_type
This can take three values



number
“internal": The user’s extension
“inum”: The user’s iNUM
“phnum”: Local number anywhere worldwide
from Sonetel connected to the user
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
Property
Description
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",
},
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 32 (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=phon
es,location
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 33 (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",
},
},
{
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 34 (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]
m
The search response is a list of user resources that have email matching
“@mycompany.com”
[
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 35 (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: {
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 36 (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",
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 37 (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",
},
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 38 (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",
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 39 (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.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 40 (110)
https://api.sonetel.com/1.3/account/53535/[email protected]
m&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",
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 41 (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" : "",
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 42 (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.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 43 (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>/phone
s
{
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 44 (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",
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 45 (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
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 46 (110)
PUT https://api.sonetel.com/1.3/account/<account_id>/user/<user_id>/
Example: POST or PUT
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",
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 47 (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
s
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
s/<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
s
“list” : [
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 48 (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>/numbe
rs/<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
You can also delete phones under a user by issuing a delete to the
phones resource. Only regular phones can be deleted this way.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 49 (110)
DELETE
s/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
s/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
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 50 (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.
Property
Description
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
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.
1
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 51 (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.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 52 (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",
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 53 (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_p
attern=*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=p
opular
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 54 (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.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
Property
Description
phnum
The number in E164 format without ‘+’ In the case of a
series, it represents the first number in the series.
country
country_code
area_code
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
descriptive and does not follow a fixed naming pattern.
type
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
API-1.3.docx
August 30, 2016
Page 55 (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.
price_category
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/availablephon
enumber/<phnum>
Example: GET
https://api.sonetel.com/1.3/numberstocksummary/USA/availablephonen
umber/12145535566
The response carries the following representation
"response":
{
"phnum" : "12145535566",
"country" : "USA",
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 56 (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",
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 57 (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/phnumstockde
tails?filters
Example: GET
umber?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.

Mailbox 647
11411 Stockholm
Sweden
[email protected]
Pattern follows wild cards such as *0001, *00*111
*00dd334 etc.
API-1.3.docx
August 30, 2016
Page 58 (110)

“*” matches any number of digits
“d” matches a single digit
area_code
The area code(s). This is a multi-value filter
city
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": "",
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 59 (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
umber?range=10,10&area_code=571&currency=USD
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 60 (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)",
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 61 (110)
"area_code": "571",
"freetest": "no",
"addr_req": "none",
"range": "10",
"phnum_end": "15712346579",
"price_catagory": "regular",
"currency": "USD",
"country": "USA"
}
"status": "success"
}
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 62 (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.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
Property
Description
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.
country
country_code
The telephony country code as per ITU
standards.
area_code
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
Page 63 (110)
series. The value specifies the quantity of
phone numbers in the number series of which
this phone number is a part of
Mailbox 647
11411 Stockholm
Sweden
[email protected]
City
Name of the city where the number is. The
name is descriptive and does not follow any
standard.
type
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
price_category
The price category of the number/series. The
allowed values are 1- regular, 2- gold, 3 - gold+,
4 - gold++, 5 -gold+++
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
Page 64 (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/subaccount
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/subaccount
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.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 65 (110)
GET
https://api.sonetel.com/account/<account_id>/phonenumbersubscription/
<phnum>
An example is
GET
https://api.sonetel.com/account/5533535/phonenumbersubscription/121
45535566
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" : "",
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 66 (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
455355005
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 subaccounts, but can be refined to a specific account using the filter
account_id.
GET
https://api.sonetel.com/account/<account_id/phonenumbersubscription?f
ilters
For e.g. the below returns all subscriptions for 10 number series in
account 2077654.
GET
https://api.sonetel.com/account/53535/phonenumbersubscription?accou
nt_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.

Mailbox 647
11411 Stockholm
Sweden
[email protected]
Pattern follows wild cards such as *0001,
*00*111 *00dd334 etc.
API-1.3.docx
August 30, 2016
Page 67 (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.
city
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",
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 68 (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",
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 69 (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
nt_id=2077654
To fetch all single number subscriptions in the sub-account, you can do
the following.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 70 (110)
GET
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 subaccount, the search will return 10 individual subscriptions, one for each
number that forms a part of the range.
GET
To search for a specific series, the starting number of the range must be
specified in the filter start_num
GET
nt_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”.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 71 (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
nt_id=2077654&series=yes&start_num=12144455010
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 72 (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
<phnum>/
or
PUT
<phnum>/
POST or PUT
556666
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
455355005
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 73 (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?seri
es=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
<phnum>/
DELETE
556666
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 74 (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
Property
Description
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
Mailbox 647
11411 Stockholm
Sweden
[email protected]
Property
Description
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
Page 75 (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
Property
Description
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.
country
area_code
city
descriptive and does not follow any standard.
type
“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
price_category
5.7.1.4./usage_details/priceplan
Property
Description
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
Mailbox 647
11411 Stockholm
Sweden
[email protected]
Property
Description
from
The phone number from where SMS was sent
to
The Sonetel phone number where the SMS was
received
API-1.3.docx
August 30, 2016
Page 76 (110)
delivered_to2
The email address where the SMS was delivered.
5.7.1.6./usage_details/inbound_fax
Property
Description
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
Property
Description
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
Property
Description
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
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 77 (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",
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 78 (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=207
7654&service=inbound_sms
The list of filters is specified here.
Property
Description
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=in
bound_call
[
{
"record_id" : "13244568",
"timestamp" : "20140603T03:15:15GMT",
"service" : "inbound_call",
"account_id" : "34231",
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 79 (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=in
bound_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" : {
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 80 (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
phnum_subscription&fields=charges,usage
[
{
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 81 (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
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",
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 82 (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",
},
},
}
]
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 83 (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.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
Property
Description
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
API-1.3.docx
August 30, 2016
Page 84 (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.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 85 (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
Disconnect the
call
disconnect
To connect to
callthru, it takes
the value
“callthru”
-NA-
-NA-
5.8.1.2.voiceapp/final_action
Property
Description
action
The action to be taken. This can take values “call”,
“play”, “connect”, “disconnect”
to
id
5.8.1.3.voiceapp/menu
Property
Description
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>
Property
Mailbox 647
11411 Stockholm
Sweden
[email protected]
Description
API-1.3.docx
August 30, 2016
Page 86 (110)
action
Can take values “play”, “call”, “connect”. An empty value
indicates that no action is taken.
to
id
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",
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 87 (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=Announce
ment%20before%20divert”
The response carries a list of voiceapp resources.
{
"response":
[
{
"app_id" : "VA234454658",
"name" : "Announcement before divert",
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 88 (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
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 89 (110)
error_repeat_voice
greeting_prompt
goodbye_prompt
deliver_to
deliver_to_details
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
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 90 (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.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 91 (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.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
Property
Description
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
API-1.3.docx
August 30, 2016
Page 92 (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,
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 93 (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.
{
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 94 (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
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 95 (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&field
s=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
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 96 (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/pro
mpt?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
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 97 (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/pro
mpt/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/pro
mpt/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”.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 98 (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.
Property
Description
country
The country’s ISO code.
name
Country name
country_code
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.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
Property
Description
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
Page 99 (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.Faxto-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.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
Property
Description
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.
API-1.3.docx
August 30, 2016
Page 100 (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,geo
graphic&name=USA
The following filters apply.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
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+++
API-1.3.docx
August 30, 2016
Page 101 (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",
}
]
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 102 (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",
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 103 (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
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 104 (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" : "",
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 105 (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",
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 106 (110)
"per_min_fee" : "0.01",
"per_sms_fee" : "",
"per_fax_fee" : "0.01",
"currency" : "USD",
}
]
}
]
},
]
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 107 (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.
Property
Description
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.
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 108 (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,
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 109 (110)
GET https://api.sonetel.com/1.3/price-list/outboundcallsprice?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/outboundcallsprice?country=IND&currency=EUR&priceplan=premium
[
{
{
"name" : "India",
"country" : "IND",
Mailbox 647
11411 Stockholm
Sweden
[email protected]
API-1.3.docx
August 30, 2016
Page 110 (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/outboundcallsprice?currency=USD
Mailbox 647
11411 Stockholm
Sweden
[email protected]

API 1.3 - Sonetel

Transcription

Similar documents

Whitepages Pro Caller Identification API

OMNITRAC LASER TRACKING SYSTEM

API and Mashup Tooklit - GeoJet Information Solutions

Quarterly NL May 2010-b

Dear Future Sponsor

ni.com - SDL.com

Sponsorship opportunities available

Air Pollutant Index - Jabatan Alam Sekitar

Siegfried`s One Stop Shop for partners in the pharmaceutical industry