DEVELOPER API. Last Updated: Simwood Mobile Developer API 1.5

(1)

 

SIMWOOD MOBILE

DEVELOPER

API

(2)

WELCOME TO SIMWOOD MOBILE

This is designed to be read in conjunction with our existing API documentation, the latest version of which can always be found at http://mirror.simwood.com/pdfs/APIv3.pdf.

Simwood Mobile API Documentation

2 SIM Branding

3 SIM Ordering

5 SIM Management

8 SIM Configuration

10 SIM Configuration - Voice

11 SIM Configuration - SIP Registration

12 SIM Configuration - SMS

13 Mobile Data Configuration

14 Mobile Data Configuration - Static IP rDNS

15 Mobile Data Balance

16 Purchasing Data Top-Ups

17 Managing Data Top-Ups

18 Mobile Data Usage (By SIM)

19 Message Waiting Indication (MWI)

20 Alerts and Notifications

21 Extended Main API Endpoints

22 Number Routing - Voice Configuration

22 Number Routing - Inbound SMS

23 Outbound SMS

24 Simwood SIP Interoperability

25 Outbound SIP (MT)

25 Inbound SIP (MO)

25 Notes and Caveats

26 Support

26

(3)

Simwood Mobile API Documentation

Each endpoint is documented below in the following format;

Please Note - Where example responses are shown in this documentation they may be reformatted to

be more easily human-readable, the actual response will have escaped slashes (e.g. / replaced with \/) and not include any excess white space unless queried with ?pretty=true

The following conventions are used in describing the URL and elsewhere in this document

{ACCOUNT} Where a word is capitalised and enclosed by curly braces { } it must be replaced with the appropriate data e.g. {ACCOUNT} or {ICCID} [ on | off ] Where two or more words are separated by the pipe character | and

enclosed within square brackets [ ] these are ‘either or’ options. /v3/URL

GET Explains what happens when the GET method is used

A sample response (in JSON) format may be shown in monospace type beneath each request, the variable names are usually self explanatory however some additional details may be provided.

POST Describes a POST request which uses HTTP Form Field parameters parameter An example HTTP Form Field parameter

anotherparam Another parameter to be sent by POST

A sample response (in JSON) format may be shown in monospace type beneath each request, the variable names are usually self explanatory

PUT Describes a PUT requiring JSON in the BODY of the request (not as HTTP Form Variables)

JSON request json_parameter Describes this parameter, may give examples

optional_json_parameter Optional parameters are shown in italics

{

“json_parameter": “this is a test", “optional_json_parameter”: true }

JSON response {

"success": true, "data": {

“json_parameter": “this is a test", “optional_json_parameter”: true }

(4)

SIM Branding

SIMs can be supplied in any of your pre-defined brands, offering a true ‘white-label’ solution.  

The branding of SIMs is managed via the API, enabling you to provide your own artwork for the printed SIM card, and network name for each brand which will be displayed on the handset.

List Brands

Modifying Brands

NB Changing the network or service provider name of a brand will only affect NEW SIMs   /v3/mvno/{ACCOUNT}/brands

GET Retrieve a list of all available brands

{

"success": true, "data": { "brands": [

{“brand”: “930000-ACME”, “network_name”: “Acme Mobile”}, {“brand”: “930000-FISH”, “network_name”: “Clownfish”} ]

} }

/v3/mvno/{ACCOUNT}/brands/{BRAND}

GET Get full details of {BRAND}

{

“brand”: “930000-ACME”,

“network_name”: “Acme Mobile”, “sender_name”: “Acme Mobile Products,

“sender_address”: “123 Some Street, Your Town, A12 3BC” “artwork”: { “sim_front”: “https://…”, “sim_back”: “https://…” } } }

PUT Create new, or update existing, {BRAND}

JSON request network_name The network name displayed on the handset (A-Z 0-9 only, max 19 chars) sp_name The service provider name displayed on

the handset (A-Z 0-9 only, max 16 chars) sender_name The sender name shown on packaging sender_address The return address shown on packaging

{

“brand”: “930000-ACME”,

“network_name”: “Acme Mobile”, “sender_name”: “Acme Mobile Products,

“sender_address”: “123 Some Street, Your Town, A12 3BC” }

}

(5)

SIM Artwork

Each brand, defined above, has two images associated with it.

Contact the Operations Desk, by eMail to team@simwood.com, to provide new artwork for a brand. SIM Branding artwork must comply with the specification outlined in the Simwood Mobile Artwork Guide. This, and a number of templates for popular applications, are provided to assist in creating appropriate SIM artwork files.

You can download this guide and templates from;

(6)

SIM Ordering

You can order SIMs for direct delivery to your customers via the API. These will be charged in accordance with your pricing schedule, and may include a delivery charge.

List Orders

You can view your outstanding orders (and any orders completed in the last 30 days) /v3/mvno/{ACCOUNT}/orders

GET Retrieve a list of outstanding or recent SIM orders

{ "success": true, "data": [ { "order_id": “300494", “ref”: “YOURREF03”,

"customer_name": “John Doe", "customer_postcode": “A12 3BC”, “quantity”: 1, "status": "processing", “date_placed”: “2015-02-30 12:30:04”, “date_updated”: “2015-02-30 16:23:06”, },{ "order_id": "300494", “ref”: “YOURREF04”,

"customer_name": “Jane Doe", "customer_postcode": “A12 3BC", "status": "received", “quantity”: 1, “date_placed”: “2015-02-30 12:30:13”, } ] }

(7)

Placing an Order

SIM orders are charged in accordance with your pricing schedule, and may include a delivery charge.

NB If ordering a branding SIM It is imperative that artwork is approved before placing an   order with a custom brand, otherwise a plain white SIM will be sent instead. 

/v3/mvno/{ACCOUNT}/orders

POST Place a new order for a SIM

JSON request ref Your own unique reference for this order  (optional, for your own reference only)

brand A brand created as described above

customer_name Customer Name for delivery customer_address Customer Address  

(address lines comma separated) customer_postcode Customer Postcode for delivery customer_country Customer ISO 3166 country code  

(use UK for United Kingdom)

quantity Number of SIMs required in this order

sim_type Reserved for future use, 

please use ‘voice’ in all requests.

{

"ref": “YOURREF03", “brand”: “930000-ACME”, "customer_name": "John Doe",

"customer_address": "123 Some St, Some Town", "customer_postcode": "A12 3BC", “customer_country": "UK", “quantity”: 1, “sim_type”: “voice” } JSON response { "success": true, "data": { “order_id”: “S000675”, “ref": “YOURREF03”, } }

(8)

Get Order Status

When an order is placed (see above) an order ID is returned, this can then be used to query the status of any outstanding order. Please note that this is a GET request only, the order cannot be changed.

An additional variable ‘status’ is provided, which can be one of the following;

The ‘sims’ variable will be present when an order has been fulfilled, this will show the ICCID(s) of the SIM(s) allocated to this order, to allow you to provision services before the customer receives their SIM card(s)

Order Cancellation

Orders placed in error, or whilst testing the API, can be cancelled whilst they are in the received state

NB Orders can be only cancelled before processing (e.g. if placed in error, or whilst testing)  Once an order status is ‘processing’ or ‘fulfilled’ (see below) this function will return an error /v3/mvno/{ACCOUNT}/orders/{ORDER ID}

GET Retrieve information on an existing SIM order

{

"ref": “YOURREF03", “brand”: “930000-ACME”, "customer_name": "John Doe",

"customer_address": "123 Some St, Some Town", "customer_postcode": "A12 3BC", “customer_country": "UK", “sim_type”: “voice”, “quantity”: 1, “status”: “fulfilled” “date_placed”: “2015-02-30 12:30:04”, “date_updated”: “2015-02-30 16:23:06”, “sims”: [“8944381214002200008“] } } status description

received Order has been received by Simwood and is awaiting processing processing Order is being processed by Simwood, and will be fulfilled shortly fulfilled Order has been prepared for dispatch, and will be dispatched that day 

At this point ‘sims’ will be present in the returned output. cancelled Order has been cancelled (see below)

/v3/mvno/{ACCOUNT}/orders/{ORDER ID}

(9)

SIM Management

You can manage your SIMs via the API. The unique reference to identify the SIM is the ICCID (Integrated Circuit Card Identifier) which is printed on the SIM in both human and machine readable (Code 128 barcode) format.

This number is also repeated on the back of the nano SIM.

SIM Activation

SIMs are shipped inactive, and must first be activated before they can be use. We recommend SIMs are shipped to your own customers inactive to protect you in the event of SIMs becoming lost in transit. Once active, deactivation of a SIM is permanent and is intended to be used where a SIM has been lost or stolen - NOT be used to temporarily disable a customer’s service (e.g. for credit control), barring should be used for this purpose.

Viewing your SIMs

SIMs can be either active or pending. Active SIMs incur ongoing charges in accordance with your contract. Pending SIMs are those that have been shipped to you but are not yet active, and do not incur charges.

/v3/mvno/{ACCOUNT}/sim/active

GET Retrieve a list of all active SIMs, together with their labels if provided.

{

"success": true, "data": { "sims": [

{“iccid”: “8944381214002200000”},

{“iccid”: “8944381214002200001”, “label”: “Ext 2034”} ]

} }

/v3/mvno/{ACCOUNT}/sim/pending

GET Retrieve a list of all SIMs assigned to your account that have not yet been activated

{ "success": true, "data": { "sims": [ {“iccid”: “8944381214002200008”}, {“iccid”: “8944381214002200009”}, {“iccid”: “8944381214002200009”} ] } }

(10)

SIM Activation and Configuration

SIMs must be activated before use.  

A simple text label can also be assigned at this time to allow you to keep track of your SIMs. These labels are also visible in the portal.

The default PIN and PIN2 along with the PUK and PUK2 codes are also returned by this endpoint. The PUK and PUK2 codes do not change, are unique to the SIM, and should be kept securely.   The PUK is required to unblock the SIM should your end user forget their PIN and lock the SIM.

The values for PIN and PIN2 are the initial values only and may be updated by the end user at any time. If the end user changes these, the new values are stored locally on the SIM and are not communicated to Simwood, therefore the response in the API will be invalid.

/v3/mvno/{ACCOUNT}/sim/active/{ICCID}

GET Request information on the SIM with the given ICCID

For more information on the parameters in this object see SIM Configuration

{ "success": true, "data": { "iccid": "8944381214002200002", "status": ”active”, “barred”: false, “label”: “My Test SIM”, "pin": 1234, "pin2": 7892, "puk": 14984212, "puk2": 94820242, “voice”: “/v3/mvno/930999/sim/active/8944381214002200002/voice”, “sms”: “/v3/mvno/930999/sim/active/8944381214002200002/sms”, “data”: “/v3/mvno/930999/sim/active/8944381214002200002/data”, } }

PUT Update the SIM or, if inactive, activate the SIM (and return the configuration as above) 

All parameters are optional, for activation you can just PUT a request to the endpoint. JSON request label An arbitrary label for this SIM, it will be displayed in the API and

in the portal. Can contain the letters A-Z, a-z, digits 0-9, underscore, hyphen and space characters only.

barred Set to true to temporarily block the SIM from using any network services (including Voice, SMS and Data). Setting false removes the bar.

{

"label": “Brian Test SIM" }

DELETE Permenantly deactivate the SIM.  

NB This renders the SIM useless, it cannot be reactivated. To disable a SIM temporarily (e.g. for credit control reasons) please use the barred attribute above.

(11)

SIM Configuration

SIMs can be configured in many ways to offer a wide degree of flexibility.

Each facet of the mobile service; Voice, SMS and Data is managed via it’s own API endpoint and can be configured in a variety of traffic profiles depending on your own application.

Full information on the profiles can be found in the main documentation, but a summary is below;

Profile API Name Description

Voice

Managed managed SIM is treated like Simwood Trunk

SIP Handoff sip MO traffic terminated to you over SIP SIP Registration registration SIM registers as a SIP device would

Hybrid hybrid as Managed, but short numbers (5 digits

or less) are terminated over SIP.

SMS

Managed managed SMS are terminated by Simwood

HTTP http MO SMS is delivered to you by HTTP

Hybrid hybrid as Managed, but SMS to short numbers (5

digits or less) delivered over HTTP

Data

Managed (NAT) nat Internet access via Simwood.  

RFC1918 address on mobile device Managed (Fixed IP) fixed Internet access via Simwood. 

Public fixed IP on mobile device

(12)

SIM Configuration - Voice

Important Information for SIP Handoff

Where calls are handed off by SIP to your equipment you will need to terminate them onwards to the destination number. Some calls are excluded from SIP handoff, e.g. calls to 112, 911, 999 and will be terminated directly.

We strongly advise using 4 digit numbers for ‘internal’ calls where providing a PBX-style service on a mobile device to avoid conflict with reserved 3 digit service numbers such as those above.

Default MO Voice Routing

MO Voice routing can be configured to an ‘account default’ so all new SIMs provisioned will behave identically. For more information, or to enable this on your account, please contact support. 

/v3/mvno/{ACCOUNT}/sim/active/{ICCID}/voice GET Request current voice configuration for the provided ICCID 

The output can vary depending on mode used. See SIP Registration below for more info.

{ "success": true, "data": { "mode": “managed", “trunk”: “930999-MOBILE20” } } { "success": true, "data": { "mode": “sip", “endpoint”: “%dialled%@sip.yourdomain.com:5080” } }

PUT Update voice configuration for the provided ICCID

JSON request mode one of [ managed | sip | registration | hybrid ] 

NB for registration mode, see additional parameters below

trunk Only where mode is ‘managed’

This should contain the trunk name   e.g. 930999-MOBILE20

The trunk must already exist (can be created with the API)

endpoint Only where mode is ‘sip’ or ‘hybrid’

A SIP Endpoint in the form user@host.com[:port]

The placeholder %dialled will be replaced with the number dialled by the mobile device

{ "mode": “sip", “endpoint”: “%dialled@sip.yourdomain.com:5080” } JSON response { "success": true, "data": { "mode": “sip", “endpoint”: “%dialled@sip.yourdomain.com:5080” } }

(13)

SIM Configuration - SIP Registration

SIMs can be configured to register using TCP to your own IP PBX much like any other SIP extension.  

Due to special network handling of numbers such as 112 we strongly advise using 4 digit extensions on your IP PBX or, if three digits must be used, numbers in the range 200-899

/v3/mvno/{ACCOUNT}/sim/active/{ICCID}/voice GET Request current voice configuration for the provided ICCID

{ "success": true, "data": { "mode": “registration”, “username”: “2004”, “host”: “pbx.example.com:5060;transport=tcp”, “expires”: 300, “registered”: true, “reg_from”: “178.22.140.37”, “registered_host”: “pbx.example.com”, “reg_expire”: “2015-07-19 12;40:39” } }

PUT Update voice configuration for the provided ICCID

JSON request mode registration 

For other parameters see above username Only where mode is ‘registration' 

The SIP username that should be used to register to your PBX password Only where mode is ‘registration' 

The password that is used to register to your PBX. Please note that due to the nature of SIP authentication this is stored in clear-text but is NOT returned in future API calls. 

We strongly advise using unique passwords for each SIP user and using passwords that are not used elsewhere.

host Only where mode is ‘registration' 

The host, transport, and optional port, we should register to, e.g. pbx.example.com;transport=tcp 

pbx.example.com:5080;transport=tcp

expires Only where mode is ‘registration' 

Registration expiry time (in seconds)

{ "mode": “registration”, “username”: “2004”, “password”: “YOUR-SIP-SECRET”, “host”: “pbx.example.com:5060;transport=tcp” }

(14)

SIM Configuration - SMS

Managed SMS

SMS messages are transmitted directly to the number they are addressed to, these will be charged at your standard SMS rates and visible in your outbound SMS CDRs.

HTTP Interface

The format of the received SMS messages is detailed below.

Default MO SMS Routing

MO Voice routing can be configured to an ‘account default’ so all new SIMs provisioned will behave identically. For more information, or to enable this on your account, please contact support.

/v3/mvno/{ACCOUNT}/sim/active/{ICCID}/sms

GET Request current MO SMS configuration for the provided ICCID

{ "success": true, "data": { “mode": “managed”, “originator": “447700900123" } } { "success": true, "data": { "mode": “http", “endpoint”: “http://api.yourdomain.com/path/to/mosms.cgi” } }

PUT Update voice configuration for the provided ICCID

JSON request mode one of [ managed | http ]

endpoint Only where mode is ‘http’

An HTTP URL that will receive a POST request for each SMS sent from this SIM.

originator Only where mode is ‘managed’

The originator (CLI) that will be shown on messages sent from the SIM

{ "mode": “http”, “endpoint”: “http://api.yourdomain.com/path/to/mosms.cgi" } JSON response { "success": true, "data": { "mode": “http” } }

(15)

Mobile Data Configuration

All Developer Preview SIMs ship with managed NAT mobile data enabled, this is a standard data service where your SIM has an RFC1918 non-routable IP assigned, and internet access is via NAT with our standard APN.

You can manage the data usage per SIM as detailed below /v3/mvno/{ACCOUNT}/sim/active/{ICCID}/data

GET Request current data configuration for the provided ICCID

{ "success": true, "data": { “enabled”: true, “mode: “nat”, “apn”: “sim.uk”, “balance”: 103410 } }

PUT Update data configuration for the provided ICCID

JSON request mode one of [ nat | fixed | l2tp ]

l2tp Only where mode is ‘l2tp’ 

Reserved for future use, this currently must be specified as the value ‘direct’ in order to use L2TP Data

host Only where mode is ‘l2tp’ 

The host (IP or FQDN) of the L2TP server

relayhost Only where mode is ‘l2tp’ 

The host/username recognised by the L2TP server for this SIM (note, this should not be confused with the ‘host’ parameter itself)

relaypass Only where mode is ‘l2tp’ 

The password to be used for L2TP authentication

{ "mode": “fixed” } JSON response { "success": true, "data": { “enabled: “true”, “mode”: “fixed”, “ip”: “10.0.0.0”, “balance”: 103410 } }

(16)

Mobile Data Configuration - Static IP rDNS

The rDNS (in-addr.arpa record) for any SIM with a static IP can be configured. If none is specified the default is the IP (with each octet separated by a hyphen) as a subdomain of mobile.simwood.com e.g the IP 185.63.140.21 would have a default rDNS entry of 185-63-140-21.mobile.simwood.com

NB Before configuring rDNS on an IP address the FQDN to be used for rDNS must resolve to the Simwood Mobile IP address.

/v3/mvno/{ACCOUNT}/sim/active/{ICCID}/data/rdns GET Get the current rDNS and IP of a SIM

{ "success": true, "data": { “ip: “185.63.140.21”, “rdns”: “185-63-140-21.mobile.simwood.com” } }

PUT Update data configuration for the provided ICCID

JSON request rdns The FQDN for the PTR record,

{ "rdns": “mobile-21.example.net” } JSON response { "success": true, “data": { “ip: “185.63.140.21”, "rdns": "mobile-21.example.net" } }

(17)

Mobile Data Balance

NB Due to the limitations of the mobile network it is possible for a balance to drop slightly   below 0 before the data session is terminated when credit is exhausted.

Mobile Data Balance Alerts

It is possible to set a per-sim alert level, you will receive a notification (configurable in the portal or via the Notifications API to be delivered by SMS, eMail or HTTP POST) when the data balance drops below this pre-set level.

This is in addition to the account-level alerts.

/v3/mvno/{ACCOUNT}/sim/active/{ICCID}/data/balance GET Request current data balance (in bytes) for the provided ICCID

{ "success": true, "data": { “balance”: 103410 } } /v3/mvno/{ACCOUNT}/sim/active/{ICCID}/data/balance/alert GET Request the current data balance alert for the provided ICCID

{ "success": true, "data": { “alert_balance”: 100000 } }

PUT Update data alert configuration for the provided ICCID

JSON request alert_balance Alert level (in bytes)

{ “alert_balance": 100000 } JSON response { "success": true, "data": { “alert_balance”: 100000 } }

(18)

Purchasing Data Top-Ups

Data must be assigned to a SIM before it can be used, doing so will charge your Simwood prepay

account in accordance with your pricing schedule. Top-up Packages

You can retrieve the top-up break points applicable to this SIM with the following API endpoint.

Purchasing Data

You may add any number of whole megabytes (multiple of 1000000 bytes) to a SIM, which will be charged according to the breakpoints shown (e.g. in the above example 1000000-32000000 bytes will cost 0.04 per megabyte, 32000000 bytes and above will cost 0.03 per megabyte.

If you have insufficient credit in your Simwood prepay account, this request will fail. /v3/mvno/{ACCOUNT}/sim/active/{ICCID}/data/topups/available

GET Retrieve available data top-up break points for this SIM

JSON response { "success": true, "data": [ { “min_bytes”: 1000000, “price_per_mb”: 0.040 }, { “min_bytes”: 32000000, “price_per_mb”: 0.030 } ] } /v3/mvno/{ACCOUNT}/sim/active/{ICCID}/data/topups POST Purchase data for the provided ICCID

JSON request bytes Increment data balance by the amount shown (in bytes). This must be a whole number of bytes in accordance with your pricing schedule. The amount allocated will affect pricing and expiry date. 

NB it is not possible to decrease the balance, and all data purchases are non-refundable, so consideration should be given in how credit is allocated to the SIM.

JSON response { "success": true, "data": { “bytes_added”: 1048576, “billed”: 0.05, “expires”: “2015-07-30”, “balance”: 1748376 } } { "success": false, "errors": [ “Insufficient Credit” ] }

(19)

Managing Data Top-Ups

Any top-ups that are still to be used can be queried, as can bundles which have been consumed or expired. This should allow you to manage top-ups for individual SIMs easily.

These are updated daily so should not be used to determine the remaining data on an account   ( see the /data/balance function, documented above )

/v3/mvno/{ACCOUNT}/sim/active/{ICCID}/data/topups/valid GET Returns the currently valid purchased blocks of data for this ICCID as an array

{ "success": true, "data": { [ { “date_added”: “2015-07-01”, “bytes_added”: 3000, “bytes_used”: 1520, “rate”: 0.02, “date_updated”: “2015-07-03”, “date_expires”: “2015-08-01” }, { “date_added”: “2015-07-03”, “bytes_added”: 4000, “bytes_used”: 0, “rate”: 0.02, “date_expires”: “2015-08-03” } ] } } /v3/mvno/{ACCOUNT}/sim/active/{ICCID}/data/topups/used GET Returns any top-ups that were exhausted or expired in the last 30 days

{ "success": true, "data": { [ { “date_added”: “2015-06-01”, “bytes_added”: 7000, “bytes_used”: 5640, “bytes_expired”: 4940, “rate”: 0.02, “date_expires”: “2015-07-01” }, { “date_added”: “2015-06-28”, “bytes_added”: 3000, “bytes_used”: 3000,

(20)

Mobile Data Usage (By SIM)

You can view a daily summary of mobile data usage per ICCID.

This is updated throughout the day, but is not as up-to-date as the data balance endpoint. 

An hourly view is also available (for the last 30 days only) 

Hour is a value between 0 and 23. For the current day, only the hours passed will be returned e.g. a request at 1540 would return data for hours 0 through 14 inclusive.  

/v3/mvno/{ACCOUNT}/sim/active/{ICCID}/data/usage GET Get usage

date_start Start date in format YYYY-MM-DD   If not specified, defaults to today

date_end End date in format YYYY-MM-DD  If not specified, defaults to today

{ "success": true, "data": [ { “date”: “2015-06-01”, “bytes_in”: 102481, “bytes_out”: 402492 }, { “date”: “2015-06-02”, “bytes_in”: 104100, “bytes_out”: 78392 } ] } /v3/mvno/{ACCOUNT}/sim/active/{ICCID}/data/usage/hourly GET Get usage

date Date in format YYYY-MM-DD 

If not specified, defaults to the current date

{ "success": true, "data": [ { “hour”: 0, “bytes_in”: 0, “bytes_out”: 0 }, { “hour”: 1, “bytes_in”: 2304, “bytes_out”: 24401 }, { “hour”: 2, “bytes_in”: 4043, “bytes_out”: 32401 }, ] }

(21)

Message Waiting Indication (MWI)

It is possible to set and unset the MWI (Message Waiting Indicator) on most mobile handsets using the API. Most handsets will show this as a Voicemail icon in the status bar and some devices will generate a notification to the user (e.g. “You have new Voicemail”) with an option to call the retrieval number.

Voicemail Retrieval Number

The voicemail retrieval number pre-programmed onto SIMs is 1571  

At present this cannot be changed, therefore we would recommend you ensure you platform can connect calls to this number to your voicemail retrieval service. 

/v3/mvno/{ACCOUNT}/sim/active/{ICCID}/mwi PUT Set the MWI

(22)

Alerts and Notifications

Data Balance

You can configure alerts to be sent when any SIM’s remaining data drops below a pre-determined level. The notification destination is configurable in the portal or via the Notifications API to be delivered by SMS, eMail or HTTP POST.

/v3/mvno/{ACCOUNT}/alerts/data

GET Request the current data balance alert for the provided ICCID

{ "success": true, "data": { “alert_balance”: 100000 } }

PUT Update data alert configuration for the provided ICCID

JSON request alert_balance Alert level (in bytes)

{ “alert_balance": 100000 } JSON response { "success": true, "data": { “alert_balance”: 100000 } }

(23)

Extended Main API Endpoints

Several API endpoints in our main API ( http://mirror.simwood.com/pdfs/APIv3.pdf ) have been extended to include mobile functionality, these are detailed below

Number Routing - Voice Configuration

The conventional Number Routing Configuration endpoint is extended as below to add a new routing block - sim - which can be used alongside the existing options such as pstn, sip and reg. This enables you to terminate Simwood numbers (included geographic and NGNs) to your Simwood Mobile SIMs.

Example Configuration

The Simwood number configuration API allows you to configure numbers and SIMs in many ways - there doesn’t need to be a simple one-to-one relationship between a number and a SIM. For example;

type parameter

sim iccid Mobile ICCID

The ICCID in form 8944xxxxxxxxxxxxxxxx of a Simwood Mobile SIM which should receive calls.

Send calls to two SIMs simultaneously

{

"routing": { "default": [ [

{"type": "sim", "iccid": “8944381214002200002”}, {"type": "sim", "iccid": “8944381214002200007"} ]

] } }

Call SIP registration user JOE, then call Simwood SIM

{

"routing": { "default": [ [

{"type": "reg", "user": “93xxxx-JOE”, “timeout”: 20} ],

[

{"type": "sim", "iccid": “8944381214002200002"} ]

] } }

(24)

Number Routing - Inbound SMS

UK Mobile Numbers will be able to receive SMS (this includes both MSISDNs obtained from Simwood, and SMS to numbers ported-in) - you can deliver these directly to a SIM or over HTTP to your own platform.

/v3/numbers/{ACCOUNT}/allocated/{NUMBER}/sms

GET Request current inbound SMS configuration for the provided number

{ "success": true, "data": { “mode": “direct”, “iccid": “8944xxxxxxxxxxxxxxx" } } { "success": true, "data": { "mode": “http", “endpoint”: “http://api.yourdomain.com/path/to/mtsms.cgi” } }

PUT Update SMS configuration for the provided mobile number

JSON request mode one of [ direct | http ]

endpoint Only where mode is ‘http’

An HTTP URL that will receive a POST request for each SMS sent to this number.

iccid Only where mode is ‘direct’

The ICCID of the SIM that should receive SMS to this number { "mode": “http”, “endpoint”: “http://api.yourdomain.com/path/to/mt" } JSON response { "success": true }

(25)

Outbound SMS

The conventional outbound SMS endpoint is extended as below;

If successful the message will be queued immediately and an id returned as follows;

[{"id":"02f150a0690171038624cc9d0e89207d"}]

Please note that this differs from the response format of most mobile API calls, but is consistent with our existing SMS API.

/v3/messaging/{ACCOUNT}/sms POST Send an SMS Message

to Recipient in e164 format (e.g. 447700900123) 

or ICCID in form 8944xxxxxxxxxxxxxxxx

from Originator number in e.164 format or alpha-numeric (maximum 11 characters if alphanumeric)

message Plain text message to send

flash

[optional] Defaults to 0. If set to 1 message is sent as a ‘flash’ message (i.e. it will be displayed on the phone screen but not stored in the recipient’s inbox, subject to handset and network support)

replace

[optional] Defaults to 0. If set to 1 message is sent with an instruction to the handset to replace the previous. This must be set to 1 on both the original and replacement message.

concat

[optional] An integer defining the maximum number of SMS to send to deliver your message where it is too long for the normal 160 plain text character limit of a single SMS. The default value of 1 will truncate your message if it is longer than 160 characters unless you set this parameter to a higher value.

(26)

Simwood SIP Interoperability

This should be read in conjunction with our SIP Interoperability documentation which can be found here; https://support.simwood.com/entries/23275426-Outbound-SIP

Outbound SIP (MT)

SIP Destination

All calls should be sent in E164 format or as the ICCID to the hostname selected e.g.; sip:447700900123@slough.out.simwood.com

sip:8944xxxxxxxxxxxxxxxx@slough.out.simwood.com 

Please note that prefixes (such as 999001 for rate deck selection) cannot be used when   calling an ICCID.

Caller ID

When calling a Simwood Mobile SIM by ICCID some of our normal rules on Caller ID (CLI) are relaxed, notably you may present ‘internal’ extensions (e.g. 305, 2120 etc) where these accurately represent the origin of the traffic.  

Good practice is you should only present a CLI that can be dialled back from the SIM

When passing a call received from the PSTN onto a SIM the usual rules apply - Caller ID must be provided on all calls in E.164 format. The leading + should not be included in any E.164 CLI. Caller ID must be provided on all calls to Simwood Mobile SIMs, calls without a valid CLI will not complete. If you wish to withhold the number, you can do so using Remote-Party-ID / Privacy headers.

Inbound SIP (MO)

Calls from the Simwood Mobile SIM will be delivered to your platform to the URI specified with the

%dialled part of the URI replaced by the number dialled from the handset.

The from header will contain the ICCID of the calling SIM as the CLI, this should never be passed onwards to the PSTN or to another Simwood Mobile subscriber, but should be used to identify the calling SIM and allow you to map an appropriate CLI.

The host in the From header will always be mo.mvno.simwood.com

The traffic will originate from the same IPs and subnets detailed in our Standard Interoperability Information document which can be found at the above link.

Short Numbers

Some calls are excluded from SIP handoff, e.g. calls to 112, 911, 999 and will be terminated directly.

We strongly advise using 4 digit numbers for ‘internal’ calls where providing a PBX-style service on a mobile device to avoid conflict with reserved 3 digit service numbers such as those above. Dialled Numbers containing # and *

Dialled numbers containing # and * will not be terminated.  

(27)

Notes and Caveats

Roaming

Simwood Mobile SIMs are for use in the UK only and do not currently support international roaming

SMS to Short Numbers

SMS messages to shortcodes are currently unsupported.

SMS Encoding

Some issues may be experienced with encoding of SMS containing UTF-16BE characters (e.g. Emoji)

Emergency Services Access (999/112)

Calls to 999 / 112 will complete as dialled. These calls are terminated directly and you will not see this traffic as MO traffic to your platform, nor will you see CDRs for such calls.

There is no requirement or facility to provide address information for mobile numbers, the callers location is inferred from information is provided by the radio access network operator. 

It is an offence to call 999/112 other than in the case of a genuine emergency. We would like to remind you that there is no provision in law for you to make ‘test’ calls to the Emergency Services and such calls must not be made from your Simwood Mobile SIM

Support

If you require support for any issue with the Simwood Mobile API, or the service itself, please do not hesitate to raise a support ticket via the Support Portal or by eMailing our Operations Desk; 

Support Portal https://support.simwood.com/ Operations Desk team@simwood.com

When contacting the Operations Desk via ticket or eMail, please include your Simwood Account number and as much information as possible regarding the issue you are experiencing.

(28)