NAV Navbar
Shell Java

Introduction

Welcome to the TelQ Telecom API. You can use our REST API to obtain a list with our available networks, send tests and consult test results.

API Versions 1.0 through 1.5

Version 1.5 of the API Continue To be Supported.

Versions 1.0, 1.1, 1.2, 1.3 and 1.4 have been deprecated, This means no new development or bug fixes will occur on those versions, but they will continue to be supported by our app through 2021. We may stop supporting them at some point in the future but we will give ample warning to all our customers about it.

You can consult the technical specification for versions 1.1 through 1.5 at the following URL: https://app.swaggerhub.com/apis/TelQ/testing/v1.5

API Version 2.0

We are happy to announce the release of our new API Version 2.0. We have strived to simplify and standarized our models and provide additional information when available. Please review this document for instructions on how to use our new API v2.0

New TelQ Telecom Java SDK

We are happy to announce the release of a new SDK for Java that simplifies the integration of our new API v2.

All you need to do to start using it is import this maven dependency to your project. com.telqtele/sdk/1.0.0

Select the "Java" tab from the panel to the right for instructions on how to perform the different operations using our new Java SDK.

Select the "Java" tab above to see details about the Java SDK

<dependency>
    <groupId>com.telqtele</groupId>
    <artifactId>sdk</artifactId>
    <version>1.0.0</version>
</dependency>

Authentication

Authentication example:

# With shell, you can just pass the correct header with each request
curl -X POST "https://api.telqtele.com/v2/client/token"
    -H "accept: application/json"
    -H "Content-Type: application/json" -d "{ \"appId\": 000001, \"appKey\": \"keykeykeykey\"}"
# Make sure to replace `000001` with your appId and `keykeykeykey` with your appKey

/*
 With our Java SDK you simply need to initialise
 TelQTestClient with your app key and app id.
 */
TelQTestClient testClient = TelQTestClient.getInstance("<yourAppKey>", "<yourAppId>");
/*
  Make sure to put your app key and app id in the getInstance call.
  Furthermore, keep in mind that your token will be automatically requested, but if for any reason
  you destruct the test client, you will have to initialize it again with your app key and id.
*/

The above command returns:

  {
  "ttl": 86400,
  "value": "WDoskdWWDkdjsaSWWWSSsht/knEQGAE+MH+mwa9sqSD
      +ca3C9BbWvYDmSWWDDpppmdkdg6ilXwfGAfrjuBsW+ZFBpZAN1n+3
      oy40jnXLfsYYma8q2HBknEQGAE+MH0u+cxEQRxjiyN9y6lWmf75QJ
      oXmtE8cDIrFfShTcZ+kTHnp6rgjdd0ctwNimb07xyPQvOK0="
  }

  /*
  The code above will return an instance of TelQTestClient that has been initialized.
  */

TelQ uses API keys (appId, appKey) to allow access to the API. You can find your App Id and generate your App Key on the API Menu of the TelQ App.

In order to use our APIs, follow these steps:

Step 1: Obtain the Token using the appId and appKey through the /token REST endpoint. The Bearer Token is used for authorization purposes in all subsequent calls. The TTL (Time to live) of the token is 86400 seconds (24 hours), hence the new token has to be re-created upon the expiration.

Telq api menu

Step 2: When calling our /tests or /results endpoints, use the value returned from the /token endpoint as the Authorization header. (Bearer Token)

We expect for the Token to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer WDoskdWWDkdjsaSWWWSSsht/kn+ca3C9BbWvYDmSWWDDpppmdkdg6ilXwfGAfrjuBsW+ZFBpZAN14NhJjRbuCshZ/JsN5NKMNkdsadsaddaassssdds67Cp19q6rLgjdd0ctYmXyxh9bMiR8+B4q/nSOS3UPmScv9CsoRp7q9vqyOOT37GYHEyXTSifpK5e7/oy40jnXLfsYYma8q2HByPQvOK0=

Networks

Request Available Networks

curl -X GET "https://api.telqtele.com/v2/client/networks"
  -H "accept: application/json"

  /*
  Keep in mind that to use TelQTestClient,
  first you need to initialise it with your app key and app id.
  */
  List<Network> networks = testClient.getNetworks();

The above command returns:

[
  {
    "mcc": "262",
    "countryName": "Germany",
    "mnc": "02",
    "providerName": "Vodafone",
    "portedFromMnc": "07",
    "portedFromProviderName": "Provider"
  }
  {
    "mcc": "505",
    "countryName": "Australia",
    "mnc": "02",
    "providerName": "Optus"
  }
]

  /*
  This will return the list of all available networks at the current moment.
  Keep in mind, that this list updated frequently and it's not recommended to use this list to initiate tests after
  a long time has passed.
  */

This endpoint retrieves a list with all our currently available Networks. Please note that the list of available networks updates frequently and we recommend to retrieve the list every minute. The returned values (mcc, mnc, portedFromMnc) will be used in the /tests endpoint to request test numbers. Test messages should then be sent from your system to these numbers to perform the test.

mcc is the Mobile Country Code, as defined by The ITU-T Recommendation E.212. This value will always contain 3 digits.

mnc is the Mobile Network Code, as defined by The ITU-T Recommendation E.212. This value can be 2 to 3 digits long.

portedFromMnc indicates from which mnc the phone number has been ported. If this param is not present, the test number has not been ported and belongs to the original network.

HTTP Request

GET https://api.telqtele.com/v2/client/networks

Header Parameters

Parameter Default Description
Authorization null The Bearer Token for authorization

Tests

Request New Tests

Request example:

{
  "destinationNetworks": [
    {
      "mcc": "208",
      "mnc": "10",
      "portedFromMnc": "20"
    }
  ]
}

curl -X POST "https://api.telqtele.com/v2/client/tests" -H "accept: */*"
  -H "Content-Type: application/json" -d "{ \"destinationNetworks\": [ { \"mcc\": \"208\",
      \"mnc\": \"10\", \"portedFromMnc\": \"20\" } ] }"

  /*
  There are multiple parameters you can send to the initiateNewTests() method
  */

  /*
  After you have requested the list of networks that you want to use to init tests, you can call multiple methods
  to init tests.
  */

  /*
  This one will init the tests with you given networks and all other parameters on default.
  */
  List<Test> requestedTests = testClient.initiateNewTests(networks);

  /*
  This one takes the networks and a time to live for parameters. Note that the third parameter is a time unit,
  it takes seconds and hours as possibilities.
  */
  List<Test> requestedTests = testClient.initiateNewTests(networks, 1000, TimeUnit.SECONDS);

  /*
  This takes multiple parameters, they go in order: networks, maximum callback retries, callback url,
  callback token (if necessary), time to live and it's time unit format.
  */
  List<Test> requestedTests = testClient.initiateNewTests(networks,
                  2,
                  "https://thisIsOneCallbackUrl/callback", "CallbackToken",
                  2, TimeUnit.HOURS);

  /*
  This takes multiple parameters, they go in order: networks, maximum callback retries, callback url,
  callback token (if necessary). Time to live is taken as default value, 3600 seconds.
  */
  List<Test> requestedTest = testClient.initiateNewTests(networks,
                  5, "https://thisIsOneCallbackUrl/callback",
                  "callbackToken");

  /*
  This takes multiple parameters, they go in order: networks, callback url, callback token (if necessary).
  Maximum callback retries and time to live are taken by default. Maximum callback retries: 3; Default time to live: 3600 seconds
  */
  List<Test> requestTest = testClient.initiateNewTests(networks,
                  "https://thisIsOneCallbackUrl/callback", "CallbackToken");

  /*
  If you don't want to use a callback token, please don't send it as null, rather a empty String.
  */

The above command returns:

[
  {
    "id": 894562,
    "phoneNumber": "33611223344",
    "testIdText": "zlrtyrvdl",
    "errorMessage": "null",
    "destinationNetwork": {
      "mcc": "206",
      "mnc": "10",
      "portedFromMnc": "20"
    }
  }
]

  /*
  All of this test initiations return a List of Tests, test response consists of data describing a single test
  initialized. Careful not to lose your test id. Otherwise you won't be able to retrieve test results from our API.
  */

This Endpoint receives a list with the Destination Networks where you want to send your tests. For each requested network, a test will be created if the network is still available at the time of the test request. Keep in mind that networks can go offline sometimes after the results from the /networks endpoint have been returned.

HTTP Request

POST https://api.telqtele.com/v2/client/tests

Header Parameters

Parameter Default Description
Authorization null The Bearer Token for authorization
results-callback-token null If you would like to authenticate our Test Results Callbacks, you can send an authentication token in this parameter. It will be included as the Authorization bearer token of the callbacks we make to your server.

Request Details

A request body with all the optional values has the following structure:

{
  "destinationNetworks": [
    {
      "mcc": "206",
      "mnc": "10",
      "portedFromMnc": "20"
    },
    {
      "mcc": "716",
      "mnc": "06",
    }
  ],
  "resultsCallbackUrl": "https://some-callback-url.com/some-path",
  "maxCallbackRetries": 1,
  "testTimeToLiveInSeconds": 200
}

  List<Network> networks = new ArrayList<>();

  Network network_1 = Network.builder()
          .mcc("206")
          .mnc("10")
          .portedFromMnc("20")
          .build();

  Network network_2 = Network.builder()
          .mcc("716")
          .mnc("06")
          .build();

  networks.add(network_1);
  networks.add(network_2);

  int maxCallBackRetries = 1;
  String resultsCallbackUrl = "https://some-callback-url.com/some-path";
  int testTimeToLive = 200;
  String callBackToken = "peHWFdAXikjzmMgqPTwhpeHWFdAXikjzmMgqPTwhpeHWFdAXikjzmMgqPTwh";

  testClient.initiateNewTests(networks, maxCallBackRetries, resultsCallbackUrl, callBackToken, testTimeToLive, TimeUnit.SECONDS);

JSON Request Object Description

Object/Key Data Type Required Default Value Description
destinationNetworks array required null The list of networks you want to issue tests to. Empty or null value will return an error
mcc string required null The Mobile Country Code for the destination you requested a test to. This value will always contain 3 digits.
mnc string required null The Mobile Network Code for the destination you requested a test to. This value can be 2 to 3 digits long.
portedFromMnc string optional null The Mobile Network Code from which the number you requested was ported from
resultsCallbackUrl string optional null The callback URL where you would like to receive TestResult updates anytime your tests status changes
maxCallbackRetries integer optional 3 The maximum number of attemps you want us to try when calling your "callback url" with updates. Maximum is 5
testTimeToLiveInSeconds integer optional 3600 The maximum amount of time you want your tests to wait for a message. Default is 1 hour. (Minimum of 1 minute, maximum of 3 hours)

Response Details

The response has the following structure:

[
  {
    "id": 894562,
    "phoneNumber": "33611223344",
    "testIdText": "zlrtyrvdl",
    "errorMessage": "null",
    "destinationNetwork": {
      "mcc": "206",
      "mnc": "10",
      "portedFromMnc": "20"
    }
  },
  {
    "id": 894563,
    "phoneNumber": null,
    "testIdText": null,
    "errorMessage": "NETWORK_OFFLINE",
    "destinationNetwork": {
      "mcc": "716",
      "mnc": "06",
    }
  }
]

  /*
  This returns a list of all tests that have been initialized. They contain some basic data, and the most important
  parameter, test id. You need the test it to request test results.
  */
  List<Test> requestedTestResponse = testClient.initiateNewTests(networks);

  /*
  You can get the test id this way. (For example)
   */
  Long testId = requestedTestResponse.get(0).getId();

JSON Response Object Description

The Response consists of an array of Test objects, containing each a destinationNetwork and details about the test request. Here is a description of each of the keys contained by a Test object:

Object/Key Data Type Description
destinationNetwork object Includes the network details for a destination you requested, for your identification purposes
mcc string The Mobile Country Code for the destination you want to test. This value will always contain 3 digits.
mnc string The Mobile Network Code for the destination you want to test. This value can be 2 to 3 digits long.
portedFromMnc string The Mobile Network Code from which the number you requested was ported from
id integer (64) The id number of your test. You will need it to request your test results through our /test-results endpoint or identify results sent to your callback.
phoneNumber string The phone number you must use for performing your test. If null, it means the Network you requested was unavailable at the time of the test. The returned numbers it will always be in international format, without + or 00 in the beginning.
testIdText string The text you must send in the body of your test sms text, used by our systems to identify your test. The length of this string can vary.
errorMessage string A short description of any errors that prevented your test from being created.

Test Results

There are two ways to retrieve Test Results:

  1. Using the /results endpoint while providing the testId returned by the /tests endpoint response. Described in this section.

  2. By providing a callback URL that will receive test results each time a test status changes. Described in the next section Callbacks

Request Details

curl -X GET "https://api.telqtele.com/v2/client/results/23"
  -H "accept: */*"

  /*
  Getting your test result would look like this. Presuming that testId is a variable of type Long
  that contains a test id.
   */
  Result result = testClient.getTestResult(testId);

HTTP Request

GET https://api.telqtele.com/v2/client/results/<id>

Header Parameters

Parameter Default Description
Authorization null The Bearer Token for authorization

URL Path Parameters

Parameter Description
id The id of the Test

Response Details

The above command returns this:

{
  "id": 23,
  "testIdText":"irrgprny",
  "senderDelivered":"+4944557775544",
  "textDelivered":"irrgprny fgsfgsd",
  "testCreatedAt":"2020-02-13T17:01:54.352886Z","smsReceivedAt":"2020-02-13T17:05:27Z",
  "receiptDelay":213,
  "testStatus":"POSITIVE",
  "destinationNetworkDetails": {
    "mcc": "206",
    "mnc": "10",
    "portedFromMnc": "20",
    "countryName": "France",
    "providerName": "French Provider",
    "portedFromProviderName": "Ported French Provider"
  },
  "smscInfo":{
    "smscNumber":null,
    "countryName":"France",
    "countryCode":"FR",
    "mcc":null,
    "mnc":null,
    "providerName":null
    },
  "pdusDelivered":["07913348466110F3040D91945102131605F60880022032225771611165B93BBF0ECBDD7990F93C345FE764"]
}

  /*
  The rest result request returns a single test result. You can access it's parameters through the returned object.
  If you wish to retrieve more results please make more requests.
  */
Object/Key Data Type Description
id integer (64) The id of this test
testIdText string The text identifier you sent in the body of your test sms
senderDelivered string The sender id that was delivered with the test sms to the phone
textDelivered string The text delivered in the test sms to the phone
testCreatedAt string (ISO 8601) Timestamp for when the test request was created in UTC using the ISO 8601 standard (e.g., 2020-02-13T17:05:27Z)
smsReceivedAt string (ISO 8601) Timestamp for when our backend receives notification from our test app that the test sms was received in the phone. Time is UTC using the ISO 8601 standard (e.g., 2020-02-13T17:05:27Z)
receiptDelay integer The number of seconds elapsed between the test request creation and the receipt of the sms on the mobile device
testStatus string The current status of this test. Options are: WAIT, POSITIVE, NOT_DELIVERED, TEST_NUMBER_NOT_AVAILABLE, INTERNAL_ERROR,TEST_NUMBER_OFFLINE or NETWORK_OFFLINE. See detailed description here
destinationNetworkDetails object Includes the network details for a destination you requested, for your identification purposes
mcc string The Mobile Country Code for the destination you have tested. This value will always contain 3 digits.
mnc string The Mobile Network Code for the destination you have tested. This value can be 2 to 3 digits long
portedFromMnc string The Mobile Network Code from which the number you requested was ported from
countryName string The country name of the destination you have tested.
providerName string Provider name of the destination you have tested.
portedFromProviderName string In case the provider has been ported, the name of the provider it has been ported from.
smscInfo object This object contains details about the smsc that delivered the test sms to the mobile device. We make our best effort to retrieve this data from the supplier, but all the values in this object could be null if they were unavailable
smscNumber string The smsc number that delivered the test sms. Can be null if unavailable
countryName string The country name for the smsc that delivered the test sms. Can be null if unavailable
countryCode string The country code for the smsc that delivered the test sms (ISO Alpha-2). Can be null if unavailable
mcc string The Mobile Country Code for the smsc that delivered the test sms. This value will always contain 3 digits. Can be null if unavailable
mnc string The Mobile Network Code for the smsc that delivered the test sms. This value can be 2 to 3 digits long. Can be null if unavailable
providerName string The providerName of the smsc that delivered the test sms. Can be null if unavailable
pdusDelivered array[string] An array of strings containing the Hexadecimal PDUs received by the device

Test Status

Status Final Status Description
WAIT no This status means we are waiting to receive the test sms in the device with the test number provide. This is the default state of new tests until the sms is received, the TTL expires or the device/network became unavailable
POSITIVE yes Test results change to this status when the test sms you sent through your system has been delivered to the mobile device
NOT_DELIVERED yes Means the TTL of this test has expired and a test sms was never received ont he mobile device
TEST_NUMBER_NOT_AVAILABLE no This status is displayed when our test number has become unnavailable, we will attempt to contact the phone again
TEST_NUMBER_OFFLINE yes The test number we provided has gone offline indefinetly, this is a final state and you will not be billed for this test
NETWORK_OFFLINE yes The network has gone offline for testing. You will not be billed for this test
INTERNAL_ERROR yes This means our systems have suffered an internal error and your test could not be completed. Please contact TelQ Support if this happens. You will not be billed for this test

Callbacks

If you provided a valid callback URL in your /tests request, our system will send a POST request to said endpoint with a TestResult object each time the test status changes.

Header Parameters

Parameter Description
Authorization If a callback URL is present and you provided a value for the results-callback-token header parameter in your tests request, the results-callback-token value will be included as the Authorization value on the callbacks we make to to your system so your endpoint can validate the authenticity of the calls

Callback Request Details

The POST body of a callback contains JSON structured like this:

{
  "id": 23,
  "testIdText":"irrgprny",
  "senderDelivered":"+4944557775544",
  "textDelivered":"irrgprny fgsfgsd",
  "testCreatedAt":"2020-02-13T17:01:54.352886Z","smsReceivedAt":"2020-02-13T17:05:27Z",
  "receiptDelay":213,
  "testStatus":"POSITIVE",
  "destinationNetwork": {
    "mcc": "206",
    "mnc": "10",
    "portedFromMnc": "20"
  },
  "smscInfo":{
    "smscNumber":null,
    "countryName":"France",
    "countryCode":"FR",
    "mcc":null,
    "mnc":null,
    "providerName":null
    },
  "pdusDelivered":["07913348466110F3040D91945102131605F60880022032225771611165B93BBF0ECBDD7990F93C345FE764"]
}
Object/Key Data Type Description
id integer (64) The id of this test
testIdText string The text identifier you sent in the body of your test sms
senderDelivered string The sender id that was delivered with the test sms to the phone
textDelivered string The text delivered in the test sms to the phone
testCreatedAt string (ISO 8601) Timestamp for when the test request was created in UTC using the ISO 8601 standard (e.g., 2020-02-13T17:05:27Z)
smsReceivedAt string (ISO 8601) Timestamp for when our backend receives notification from our test app that the test sms was received in the phone. Time is UTC using the ISO 8601 standard (e.g., 2020-02-13T17:05:27Z)
receiptDelay integer The number of seconds elapsed between the test request creation and the receipt of the sms on the mobile device
testStatus string The current status of this test. Options are: WAIT, POSITIVE, NOT_DELIVERED, TEST_NUMBER_NOT_AVAILABLE, INTERNAL_ERROR,TEST_NUMBER_OFFLINE or NETWORK_OFFLINE. See detailed description here
destinationNetwork object Includes the network details for a destination you requested, for your identification purposes
mcc string The Mobile Country Code for the destination you want to test. This value will always contain 3 digits.
mnc string The Mobile Network Code for the destination you want to test. This value can be 2 to 3 digits long
portedFromMnc string The Mobile Network Code from which the number you requested was ported from
smscInfo object This object contains details about the smsc that delivered the test sms to the mobile device. We make our best effort to retrieve this data from the supplier, but all the values in this object could be null if they were unavailable
smscNumber string The smsc number that delivered the test sms. Can be null if unavailable
countryName string The country name for the smsc that delivered the test sms. Can be null if unavailable
countryCode string The country code for the smsc that delivered the test sms (ISO Alpha-2). Can be null if unavailable
mcc string The Mobile Country Code for the smsc that delivered the test sms. This value will always contain 3 digits. Can be null if unavailable
mnc string The Mobile Network Code for the smsc that delivered the test sms. This value can be 2 to 3 digits long. Can be null if unavailable
providerName string The providerName of the smsc that delivered the test sms. Can be null if unavailable
pdusDelivered array[string] An array of strings containing the Hexadecimal PDUs received by the device

Errors

The TelQ Telecom API version 2.0 uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your appId, appKey or token is incorrect.
404 Not Found -- The specified TestResult could not be found.
405 Method Not Allowed -- You tried to a method not supported by our API
406 Not Acceptable -- You requested a format that isn't json.
500 Internal Server Error -- We had a problem with our service. Please contact our support team for assistance.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
Shell Java