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
Versions 1.0, 1.1, 1.2, 1.3, 1.4 and 1.5 of the API Continue To be Supported.
We will provide a deprecation plan by the end of 2020, but rest assured we will give ample time to upgrade after that.
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 will make it easier to integrating our new API v2.
All you need to do to start using it is import this maven dependency to your project.
Select the "Java" tab from the panel to the right for instructions on how to perform the different operations using our new Java SDK.
Maven Dependency for the new TelQ 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.
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 peform 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://my-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 peforming 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:
Using the /results endpoint while providing the testId returned by the /tests endpoint response. Described in this section.
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",
"destinationNetwork": {
"mcc": "206",
"mnc": "10",
"portedFromMnc": "20"
},
"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 |
| 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 effor 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 enpoint can validate the autenticity 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 effor 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. |