SIMWOOD MOBILE DEVELOPER API Last Updated: 2015-11-04
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 Document History 27 1
Simwood Mobile API Documentation Each endpoint is documented below in the following format; /v3/url Explains what happens when the 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 anotherparam An example HTTP Form Field parameter 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 "data": json_parameter": this is a test", optional_json_parameter : true 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. e.g.[ 1 5 10 ] allows either 1,5 or 10. 15 would be invalid. URLs The URLs are shown without the leading https://api.simwood.com/ paramname Parameters are shown in italics when referenced in the description, these are all passed in by JSON body requests and do not form part of the URI. Within the request specification, italics denote optional parameters. 2
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 /v3/mvno/account/brands Retrieve a list of all available brands "data": "brands": [ brand : 930000-ACME, network_name : Acme Mobile, brand : 930000-FISH, network_name : Clownfish ] Modifying Brands /v3/mvno/account/brands/brand Get full details of BRAND "data": 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 sender_name sender_address The service provider name displayed on the handset (A-Z 0-9 only, max 16 chars) The sender name shown on packaging The return address shown on packaging "data": brand : 930000-ACME, network_name : Acme Mobile, sender_name : Acme Mobile Products, sender_address : 123 Some Street, Your Town, A12 3BC DELETE Delete the specified BRAND NB Changing the network or service provider name of a brand will only affect NEW SIMs shipped for this brand. existing SIMs in service will continue to show the previous name. 3
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; http://mirror.simwood.com/mobile/simwood_mobile_sim_branding.zip 4
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 Retrieve a list of outstanding or recent SIM orders "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, ] 5
Placing an Order SIM orders are charged in accordance with your pricing schedule, and may include a delivery charge. /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. JSON response "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 "data": order_id : S000675, ref": YOURREF03, 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. 6
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 request only, the order cannot be changed. /v3/mvno/account/orders/order ID Retrieve information on an existing SIM order "data": "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 ] An additional variable status is provided, which can be one of the following; status received processing fulfilled cancelled description Order has been received by Simwood and is awaiting processing Order is being processed by Simwood, and will be fulfilled shortly Order has been prepared for dispatch, and will be dispatched that day At this point sims will be present in the returned output. Order has been cancelled (see below) 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 /v3/mvno/account/orders/order ID DELETE Cancel an existing SIM order 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 7
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 Retrieve a list of all active SIMs, together with their labels if provided. "data": "sims": [ iccid : 8944381214002200000, iccid : 8944381214002200001, label : Ext 2034 ] /v3/mvno/account/sim/pending Retrieve a list of all SIMs assigned to your account that have not yet been activated "data": "sims": [ iccid : 8944381214002200008, iccid : 8944381214002200009, iccid : 8944381214002200009 ] 8
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. /v3/mvno/account/sim/active/iccid Request information on the SIM with the given ICCID For more information on the parameters in this object see SIM Configuration "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. 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. 9
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 Managed managed SIM is treated like Simwood Trunk Voice 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. Managed managed SMS are terminated by Simwood SMS 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 Managed (NAT) nat Internet access via Simwood. RFC1918 address on mobile device Data Managed (Fixed IP) fixed Internet access via Simwood. Public fixed IP on mobile device L2TP l2tp L2TP 10
SIM Configuration - Voice /v3/mvno/account/sim/active/iccid/voice Request current voice configuration for the provided ICCID The output can vary depending on mode used. See SIP Registration below for more info. "data": "mode": managed", trunk : 930999-MOBILE20 "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 endpoint 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) 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 JSON response "mode": sip", endpoint : %dialled@sip.yourdomain.com:5080 "data": "mode": sip", endpoint : %dialled@sip.yourdomain.com:5080 DELETE Remove MO Voice configuration for the provided ICCID 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. 11
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 Request current voice configuration for the provided ICCID "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 password host expires Only where mode is registration' The SIP username that should be used to register to your PBX 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. 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 Only where mode is registration' Registration expiry time (in seconds) JSON response "mode": registration, username : 2004, password : YOUR-SIP-SECRET, host : pbx.example.com:5060;transport=tcp "data": "mode": registration, username : 2004, password : YOUR-SIP-SECRET, host : pbx.example.com:5060;transport=tcp DELETE Remove MO Voice configuration for the provided ICCID NB An active registration does not represent the SIMs status on the mobile network. All SIP registration must be using TCP only, UDP is not supported. 12
SIM Configuration - SMS /v3/mvno/account/sim/active/iccid/sms Request current MO SMS configuration for the provided ICCID "data": mode": managed, originator": 447700900123" "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 originator Only where mode is http An HTTP URL that will receive a POST request for each SMS sent from this SIM. Only where mode is managed The originator (CLI) that will be shown on messages sent from the SIM JSON response "mode": http, endpoint : http://api.yourdomain.com/path/to/mosms.cgi" "data": "mode": http 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. 13
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 Request current data configuration for the provided ICCID "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 host relayhost relaypass Only where mode is l2tp Reserved for future use, this currently must be specified as the value direct in order to use L2TP Data Only where mode is l2tp The host (IP or FQDN) of the L2TP server 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) Only where mode is l2tp The password to be used for L2TP authentication JSON response "mode": fixed "data": enabled: true, mode : fixed, ip : 10.0.0.0, balance : 103410 NB When changing to fixed from any other mode, an ip address will be returned by the API. This is the static IP address allocated to that SIM. If a SIM is changed from fixed to another mode and then returned to fixed, it is likely that the IP address will differ. 14
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 /v3/mvno/account/sim/active/iccid/data/rdns Get the current rdns and IP of a SIM "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, JSON response "rdns": mobile-21.example.net data": ip: 185.63.140.21, "rdns": "mobile-21.example.net" DELETE Restore the default rdns of the IP associated with the SIM (see above) NB Before configuring rdns on an IP address the FQDN to be used for rdns must resolve to the Simwood Mobile IP address. 15
Mobile Data Balance /v3/mvno/account/sim/active/iccid/data/balance Request current data balance (in bytes) for the provided ICCID "data": balance : 103410 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/alert Request the current data balance alert for the provided ICCID "data": alert_balance : 100000 PUT Update data alert configuration for the provided ICCID JSON request alert_balance Alert level (in bytes) JSON response alert_balance": 100000 "data": alert_balance : 100000 DELETE Remove the data balance alert for this ICCID 16
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. /v3/mvno/account/sim/active/iccid/data/topups/available Retrieve available data top-up break points for this SIM JSON response "data": [ min_bytes : 1000000, price_per_mb : 0.040, min_bytes : 32000000, price_per_mb : 0.030 ] 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 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 "data": bytes_added : 1048576, billed : 0.05, expires : 2015-07-30, balance : 1748376 "success": false, "errors": [ Insufficient Credit ] 17
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 Returns the currently valid purchased blocks of data for this ICCID as an array "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 Returns any top-ups that were exhausted or expired in the last 30 days "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, bytes_expired : 0, rate : 0.02, date_expires : 2015-07-28 ] 18
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. /v3/mvno/account/sim/active/iccid/data/usage 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 "data": [ date : 2015-06-01, bytes_in : 102481, bytes_out : 402492, date : 2015-06-02, bytes_in : 104100, bytes_out : 78392 ] An hourly view is also available (for the last 30 days only) /v3/mvno/account/sim/active/iccid/data/usage/hourly Get usage date Date in format YYYY-MM-DD If not specified, defaults to the current date "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, ] 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. 19
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. /v3/mvno/account/sim/active/iccid/mwi PUT DELETE Set the MWI Remove the MWI indication 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. 20
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 Request the current data balance alert for the provided ICCID "data": alert_balance : 100000 PUT Update data alert configuration for the provided ICCID JSON request alert_balance Alert level (in bytes) JSON response alert_balance": 100000 "data": alert_balance : 100000 DELETE Remove the data balance alert for this ICCID 21
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. type parameter sim iccid Mobile ICCID The ICCID in form 8944xxxxxxxxxxxxxxxx of a Simwood Mobile SIM which should receive calls. 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; 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" ] ] 22
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 Request current inbound SMS configuration for the provided number "data": mode": direct, iccid": 8944xxxxxxxxxxxxxxx" "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 iccid Only where mode is http An HTTP URL that will receive a POST request for each SMS sent to this number. Only where mode is direct The ICCID of the SIM that should receive SMS to this number JSON response "mode": http, endpoint : http://api.yourdomain.com/path/to/mt" "success": true DELETE Delete SMS configuration for this number 23
Outbound SMS The conventional outbound SMS endpoint is extended as below; /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 flash [optional] replace [optional] concat [optional] Plain text message to send 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) 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. 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. 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. 24
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. 25
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 Operations Desk https://support.simwood.com/ 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. 26
Document History Date Revision Author 2015-11-04 1.5 RM Minor corrections 2015-10-27 1.4 RM Addition of L2TP Data Service 2015-09-23 1.3 RM Minor changes 2015-08-28 1.2 RM Initial public release 27