TELUS is providing three services for the 2017 TM Forum Open Hack, allowing you to create robust applications with a subset of the features available on the TELUS network. These services will allow you to:
Using the Services
During the TM Forum Open Hack event, we are exposing these APIs through the IBM Bluemix platform as REST services. You will be using a pre-registered set of credentials, so ensure the following HTTP Header is set for all your REST calls:
X-IBM-Client-Id: c466530c-8489-4353-8cac-6c0babe8ff40
Get Location Service
This API allows you to look up the location of a device by its mobile phone number. This location service uses TELUS network triangulation to determine the GPS location of a device. In the event the device is not powered on or out of service area, this service will return its last known location.
GET https://api.us.apiconnect.ibmcloud.com/tmforum-apidev/telustmfcatalog/telustmfapilocation/location/{address}
Where {address} is the phone number of the device you want to locate. This service call is restricted and secured so that only whitelisted phone numbers can be accessed by a service account. For the purpose of this Open Hack event, you can use any of the following test numbers:
The response is a JSON object with the following attributes:
address | The device phone number |
timestamp | Last location timestamp |
latitude | Device network location latitude |
longitude | Device network location longitude |
altitude | Device network location altitude / elevation |
accuracy | Device network location accuracy (in meters) |
curl https://api.us.apiconnect.ibmcloud.com/tmforum-apidev/telustmfcatalog/telustmfapilocation/location/6045550000 \
-H "Content-type: application/json" \
-H "X-IBM-Client-Id: c466530c-8489-4353-8cac-6c0babe8ff40"
{
"address": "6045550000",
"timestamp": "Mon, 18 Sep 2017 03:39:36 +0000",
"latitude": "49.237774",
"longitude": "-123.017636",
"altitude": "22.0",
"accuracy": "182"
}
Client id is missing | Client credentials are missing (HTTP header X-IBM-Client-Id is missing) |
Client id not registered | Client credentials are invalid (invalid value for HTTP header X-IBM-Client-Id) |
Missing terminal address | Address / phone number parameter is missing |
Terminal address not authorized | Address / phone number is not whitelisted for use by your application |
Send SMS Service
This service allows you to send an SMS message through your application. For the TM Forum Open Hack, this service is sandboxed for security purposes. You can send an SMS to the test numbers (6045550000, 6045550001), or to your own number. Please contact a TELUS representative to whitelist your number.
POST https://api.us.apiconnect.ibmcloud.com/tmforum-apidev/telustmfcatalog/telustmfapisendsms/send
The post body is a JSON formatted object with 2 parameters:
address | The destination phone number (6045550000, 6045550001, or your own whitelisted number) |
message | The SMS message to deliver, up to a maximum length of 1000 characters |
The response is a JSON object containing the correlator, a unique identifier that you can use to look up the message delivery status at a later time.
curl https://api.us.apiconnect.ibmcloud.com/tmforum-apidev/telustmfcatalog/telustmfapisendsms/send \
-H "Content-type: application/json" \
-H "X-IBM-Client-Id: c466530c-8489-4353-8cac-6c0babe8ff40" \
-X POST -d '{"address": "6045550000", "message": "Sample SMS message"}'
{
"correlator": 90050000
}
Client id is missing | Client credentials are missing (HTTP header X-IBM-Client-Id is missing) |
Client id not registered | Client credentials are invalid (invalid value for HTTP header X-IBM-Client-Id) |
Missing recipient address | Address / phone number parameter is missing |
Invalid recipient address | Address / phone number is invalid, or not allowed |
Missing message body | Message body is missing |
Message exceeds 1000 characters | Message body is too long (exceeds 1000 characters) |
Get SMS Delivery Status
This service is to be used to retrieve the delivery status of an SMS message you previously sent.
Where {correlator} is the correlator ID returned from a successful SMS delivery API call.
The response is a JSON object with the following attributes:
address | The phone number the message was delivered to |
deliveryStatus | The status of the SMS (DeliveredToTerminal or Queued) |
curl https://api.us.apiconnect.ibmcloud.com/tmforum-apidev/telustmfcatalog/telustmfapistatussms/status/90050000 \
-H "Content-type: application/json" \
-H "X-IBM-Client-Id: c466530c-8489-4353-8cac-6c0babe8ff40"
{ "address": "6045550000", "deliveryStatus": "DeliveredToTerminal" }
Client id is missing | Client credentials are missing (HTTP header X-IBM-Client-Id is missing) |
Client id not registered | Client credentials are invalid (invalid value for HTTP header X-IBM-Client-Id) |
Missing correlator ID | Correlator parameter is missing |
Invalid correlator | Correlator ID is invalid or was not sent by your application |
The APIs provided for the TM Forum Open Hack are a subset of the programmable services available at TELUS. To learn more about the full set of APIs provided by TELUS, visit the TELUS Network APIs site.