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:

  1. Get Location Service
  2. SMS Send Service
  3. Get SMS Delivery Status Service




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. 

REST API

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:

  • 6045550000
  • 6045550001
  • 6045550002
  • 6045550003
  • 6045550004
  • 6045550005
  • 6045550006
  • 6045550007
  • 6045550008
  • 6045550009

Response

The response is a JSON object with the following attributes: 


addressThe device phone number
timestampLast location timestamp
latitudeDevice network location latitude
longitudeDevice network location longitude
altitudeDevice network location altitude / elevation
accuracyDevice network location accuracy (in meters)


Sample Call

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"

Sample Response

{
"address": "6045550000",
"timestamp": "Mon, 18 Sep 2017 03:39:36 +0000",
"latitude": "49.237774",
"longitude": "-123.017636",
"altitude": "22.0",
"accuracy": "182"
}

Error Messages

Client id is missingClient credentials are missing (HTTP header X-IBM-Client-Id is missing)
Client id not registeredClient credentials are invalid (invalid value for HTTP header X-IBM-Client-Id)
Missing terminal addressAddress / phone number parameter is missing
Terminal address not authorizedAddress / 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.

REST API

POST  https://api.us.apiconnect.ibmcloud.com/tmforum-apidev/telustmfcatalog/telustmfapisendsms/send

The post body is a JSON formatted object with 2 parameters:

addressThe destination phone number (6045550000, 6045550001, or your own whitelisted number)
messageThe SMS message to deliver, up to a maximum length of 1000 characters


Response

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. 

Sample Call 

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"}'

Sample Response

{
"correlator": 90050000
}

Error Messages

Client id is missingClient credentials are missing (HTTP header X-IBM-Client-Id is missing)
Client id not registeredClient credentials are invalid (invalid value for HTTP header X-IBM-Client-Id)
Missing recipient addressAddress / phone number parameter is missing
Invalid recipient addressAddress / phone number is invalid, or not allowed
Missing message bodyMessage body is missing
Message exceeds 1000 charactersMessage 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.

REST API

GET https://api.us.apiconnect.ibmcloud.com/tmforum-apidev/telustmfcatalog/telustmfapistatussms/status/{correlator}

Where {correlator} is the correlator ID returned from a successful SMS delivery API call.

Response

The response is a JSON object with the following attributes: 


addressThe phone number the message was delivered to
deliveryStatusThe status of the SMS (DeliveredToTerminal or Queued)


Sample Call

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"

Sample Response

{
    "address": "6045550000",
    "deliveryStatus": "DeliveredToTerminal"
}

Error Messages

Client id is missingClient credentials are missing (HTTP header X-IBM-Client-Id is missing)
Client id not registeredClient credentials are invalid (invalid value for HTTP header X-IBM-Client-Id)
Missing correlator IDCorrelator parameter is missing
Invalid correlatorCorrelator 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.




  • No labels