NAV

Shell Java Python PHP

Introduction

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

API Versions

API Version 2.1

New customers should use this version of the API.

We are happy to announce the release of our new API Version 2.1. We have introduced a new feature that gives our users fine control over the test-id-text to be used within tests. Please look at the /tests model for more details on how to use this powerful tool.

API Version 2.0

On this version we have strived to simplify and standarize our models and provide additional information when available. We provide new features like custom test TTL and callback tokens. Please review this document for instructions on how to use our new API v2.0

API Versions 1.0 through 1.5

Version 1.5 of the API continue to be supported.

You can find the relevant documentation for each version below:

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.

OpenAPI Specification

You can find the OpenAPI 2.0 Specification for our v2.1 API at our swagger hub page: https://app.swaggerhub.com/apis/TelQ/testing/v2.1

You can obtain autogenerated SDKs for many popular programing languages from this spec.

TelQ Telecom Java SDK

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

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

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

Select the "Java", "Python" or "PHP" tab above to see details about the respective SDKs.
<dependency>
    <groupId>com.telqtele</groupId>
    <artifactId>sdk</artifactId>
    <version>1.3.1</version>
</dependency>

TelQ Telecom Python SDK

We are happy to announce the release of SDK for Python that simplifies the integration of our API.

All you need to do to start using it is install our package in your project. telq

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

pip install telq

TelQ Telecom PHP SDK

We are happy to announce the release of SDK for PHP that simplifies the integration of our API.

All you need to do to start using it is install our package in your project. https://github.com/TelQ/sdk-php

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

composer require telq/sdk

Authentication

Authentication example:

# With shell, you can just pass the correct header with each request
curl -X POST "https://api.telqtele.com/v2.1/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.
*/
from telq import TelQTelecomAPI
telq_client = TelQTelecomAPI()

test_client.authenticate(api_id="<yourAppKey>", api_key="<yourAppId>")
###
#  Make sure to pass your app key and app id in the authenticate 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.
###
use TelQ\Sdk\Api;
use TelQ\Sdk\Http\HttpException;

$appId = <APPID>;
$appKey = <APPKEY>;

$api = new Api($appId, $appKey);
try {
    // call api
} catch (HttpException $exception) {
    echo 'Handle http exception', PHP_EOL;
    echo 'Response code ', $exception->getResponse()->getStatus(), PHP_EOL;
    echo 'Response body ', $exception->getResponse()->getBody(), PHP_EOL;
}

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.
  */
  ###
  # The code above will return an instance of TelQ API Client that has been initialized.
  ###
  /*
  The code above will return an instance of TelQTestClient that has been initialized.
  */

TelQ uses API keys (appId, appKey) to provide 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=

If you are testing via Swaggerhub, you can click on the "Authorize" button in the user interface, input the returned value and click on "Authorize".

Networks

Request Available Networks

curl -X GET "https://api.telqtele.com/v2.1/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();
available_networks = test_client.get_networks()

###
# Keep in mind that to use TelQTelecomAPI,
# first you need to initialise it with your app key and app id (step above).
###
$networks = $api->getNetworks();
foreach ($networks as $network) {
    echo 'Mcc: ', $network->getMcc(), PHP_EOL;
    echo 'Country name: ', $network->getCountryName(), PHP_EOL;
    echo 'Mnc: ', $network->getMnc(), PHP_EOL;
    echo 'Provider name: ', $network->getProviderName(), PHP_EOL;
    echo 'Ported from mnc: ', $network->getPortedFromMnc() ?: 'empty', PHP_EOL;
    echo 'Ported from provider name: ', $network->getPortedFromProviderName() ?: 'empty', PHP_EOL;
    echo PHP_EOL;
}
echo 'Networks: ', count($networks), PHP_EOL;

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 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 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 of all our currently available Networks. Please note that the list of available networks updates frequently and we recommend retrieving the list every minute. The returned values (mcc, mnc, portedFromMnc) will be used in the /test 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.

/networks

HTTP Request

GET https://api.telqtele.com/v2.1/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.1/client/tests" -H "accept: */*"
  -H "Content-Type: application/json" -d "{ \"destinationNetworks\": [ { \"mcc\": \"208\",
      \"mnc\": \"10\", \"portedFromMnc\": \"20\" } ] }"
TestRequest testRequest = TestRequest.builder()
    .networks(networks)
    .build();

List<Test> requestedTests = testClient.initiateNewTests(testRequest);
destinationNetworks = [
    {
        "mcc": "206",
        "mnc": "10",
        "portedFromMnc": "20"
    },
    {
        "mcc": "716",
        "mnc": "06"
    }
]

###
# A request with only the mandatory (networks) parameter set up within the test client
# object will have this structure:
###

requested_tests = test_client.initiate_new_tests(destinationNetworks=destinationNetworks)
use TelQ\Sdk\Models\Destination;
use TelQ\Sdk\Models\Tests;

// new Destination('mcc', 'mnc', 'ported from mnc')
$sendTests = Tests::fromArray([
    'destinationNetworks' => [
        new Destination('222', '36', '10'),
        new Destination('505', '01')
    ]
]);
$tests = $api->sendTests($sendTests);
foreach ($tests as $test) {
    echo 'Id: ', $test->getId(), PHP_EOL;
    echo 'PhoneNumber: ', $test->getPhoneNumber(), PHP_EOL;
    echo 'TestIdText: ', $test->getTestIdText(), PHP_EOL;
    echo 'Error message: ', $test->getErrorMessage() ?: 'empty', PHP_EOL;
    echo 'Destination:', PHP_EOL;
    echo '    Mcc: ', $test->getDestinationNetwork()->getMcc(), PHP_EOL;
    echo '    Mnc: ', $test->getDestinationNetwork()->getMnc(), PHP_EOL;
    echo '    Ported from mnc: ', $test->getDestinationNetwork()->getPortedFromMnc() ?: 'empty', PHP_EOL;
    echo PHP_EOL;
}

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.

New in 2.1: To use the dynamic test-id-text feature, you need to provide the testIdTextType with one of the options: "ALPHA", "ALPHA_NUMERIC", "NUMERIC" or "WHATSAPP_CODE". You can also specify the length and case (when applicable). Consult the parameters table for more details. Remember to include your token for Authorization. You can provide a callback URL to receive updates whenever the status of your tests changes. This is optional, as you can also view test results through the /results endpoint.

/tests

POST https://api.telqtele.com/v2.1/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",
  "testIdTextType": "ALPHA_NUMERIC",
  "testIdTextCase": "MIXED",
  "testIdTextLength": "6",
  "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";

  TestIdTextOptions testIdTextOptions = TestIdTextOptions.builder()
    .testIdTextType(TestIdTextType.ALPHA_NUMERIC)
    .testIdTextCase(TestIdTextCase.MIXED)
    .testIdTextLength(6)
    .build();

  TestRequest testRequest = TestRequest.builder()
    .networks(networks)
    .maxCallbackRetries(maxCallBackRetries)
    .callbackUrl(resultsCallbackUrl)
    .callbackToken(callBackToken)
    .testTimeToLive(testTimeToLive)
    .timeUnit(TimeUnit.MINUTES)
    .testIdTextOptions(testIdTextOptions)
    .build();

  List<Test> requestedTests = testClient.initiateNewTests(testRequest);

requested_tests = test_client.initiate_new_tests(
    destinationNetworks=destinationNetworks,
    resultsCallbackUrl="https://my-callback-url.com/telq_result",
    maxCallbackRetries=3,
    testIdTextType="ALPHA_NUMERIC",
    testIdTextCase="MIXED",
    testIdTextLength=7,
    testTimeToLiveInSeconds=3000
)
requested_tests = test_client.initiate_new_tests(destinationNetworks=destinationNetworks)

$sendTests = Tests::fromArray([
    'destinationNetworks' => [
        new Destination('222', '36', '10'),
        new Destination('505', '01')
    ],
    'resultsCallbackUrl' => 'https://my-domain.com/telq-callback',
    'maxCallbackRetries' => 3,
    'testIdTextType' => 'ALPHA',
    'testIdTextCase' => 'MIXED',
    'testIdTextLength' => 6,
    'testTimeToLiveInSeconds' => 3600
]);

The above command returns:

[
  {
    "id": 894562,
    "phoneNumber": "33611223344",
    "testIdText": "zlrtyrvdl",
    "errorMessage": "null",
    "destinationNetwork": {
      "mcc": "206",
      "mnc": "10",
      "portedFromMnc": "20"
    }
  }
]
###
#  This test initiation returns 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 test initiation returns 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.
  */

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 want to test. This value will always contain 3 digits.
mnc string required null The Mobile Network Code for the destination you want to test. This value can be 2 to 3 digits long.
portedFromMnc string optional null The Mobile Network Code from which the number you are requesting was ported from.
resultsCallbackUrl string optional null The callback URL where you would like to receive TestResult updates anytime the status of your tests changes.
maxCallbackRetries integer optional 3 The maximum number of attempts you want us to try when calling your "callback url" with updates. Maximum is 5.
testIdTextType string optional ALPHA The type of testIdText to use in this test. Options are: "ALPHA", "ALPHA_NUMERIC", "NUMERIC", "WHATSAPP_CODE".
testIdTextCase string optional MIXED The case to use for letters in the testIdText. Applies only to ALPHA and ALPHA_NUMERIC types. Options are: "UPPER", "LOWER", "MIXED".
testIdTextLength integer (32) optimal 10 The number of characters to use for generating the testIdText. default=10, minimum=4, maximum=20. Doesn't apply to WHATSAPP_CODE type, since it has a fixed length of 7.
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

[
  {
    "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> requestedTests = testClient.initiateNewTests(testRequest);
  /*
  You can get the test id this way. (For example)
   */
  Long testId = requestedTests.get(0).getId();
###
# Each test initiation returns a JSON response, containing the test details.
# Most importantly, it contains the phoneNumber, testIdText, and id.
# You will need the (test) id to request the test results.
###

###
# You can get the test id (of the first test) this way:
###

test_id = requested_tests[0].get('id')

// You can get the test result (of the test with id 13777294) this way:
$result = $api->getTestResult(13777294);
echo 'Id: ', $result->getId(), PHP_EOL;

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 requested a test to. This value will always contain 3 digits.
mnc string The Mobile Network Code for the destination you requested a test to. This value can be 2 to 3 digits long.
portedFromMnc string The Mobile Network Code from which the number you requested was ported from. This value can be 2 to 3 digits long and can be null
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.
testIdTextType string The type of testIdText used this test. Options are: "ALPHA", "ALPHA_NUMERIC", "NUMERIC", "WHATSAPP_CODE"
testIdTextCase string The case used for letters in the testIdText. Applies only to ALPHA and ALPHA_NUMERIC types. Options are: "UPPER", "LOWER", "MIXED"
testIdTextLength integer (32) The number of characters used for generating the testIdText. default=10, minimum=4, maximum=20. Doesn't apply to WHATSAPP_CODE type, since it has a fixed length of 7.
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

/results/<id>

curl -X GET "https://api.telqtele.com/v2.1/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);
###
# Getting your test result would look like this:
###

test_result = test_client.get_test_results(test_id)
$result = $api->getTestResult(13777294);
echo 'Id: ', $result->getId(), PHP_EOL;
echo 'TestIdText: ', $result->getTestIdText(), PHP_EOL;
echo 'Sender delivered: ', $result->getSenderDelivered() ?: 'empty', PHP_EOL;
echo 'Text delivered: ', $result->getTextDelivered() ?: 'empty', PHP_EOL;
echo 'Test created: ', $result->getTestCreatedAt()->format('Y-m-d H:i:s'), PHP_EOL; // return DateTime https://www.php.net/manual/en/class.datetime.php
echo 'Sms received: ', $result->getSmsReceivedAt() ? $result->getSmsReceivedAt()->format('Y-m-d H:i:s'): 'empty', PHP_EOL;
echo 'Receipt delay: ', $result->getReceiptDelay() ?: 'empty', PHP_EOL;
echo 'Test status: ', $result->getTestStatus(), PHP_EOL;
echo 'Network:', PHP_EOL;
if ($result->getDestinationNetworkDetails()) {
    echo '    Mcc: ', $result->getDestinationNetworkDetails()->getMcc(), PHP_EOL;
    echo '    Country name: ', $result->getDestinationNetworkDetails()->getCountryName(), PHP_EOL;
    echo '    Mnc: ', $result->getDestinationNetworkDetails()->getMnc(), PHP_EOL;
    echo '    Provider name: ', $result->getDestinationNetworkDetails()->getProviderName(), PHP_EOL;
    echo '    Ported from mnc: ', $result->getDestinationNetworkDetails()->getPortedFromMnc() ?: 'empty', PHP_EOL;
    echo '    Ported from provider name: ', $result->getDestinationNetworkDetails()->getPortedFromProviderName() ?: 'empty', PHP_EOL;
} else {
    echo '    empty', PHP_EOL;
}
echo 'Smsc info:', PHP_EOL;
if ($result->getSmscInfo()) {
    echo '    Smsc number: ', $result->getSmscInfo()->getSmscNumber() ?: 'empty', PHP_EOL;
    echo '    Country name: ', $result->getSmscInfo()->getCountryName() ?: 'empty', PHP_EOL;
    echo '    Country code: ', $result->getSmscInfo()->getCountryCode() ?: 'empty', PHP_EOL;
    echo '    Mcc: ', $result->getSmscInfo()->getMcc() ?: 'empty', PHP_EOL;
    echo '    Mnc: ', $result->getSmscInfo()->getMnc() ?: 'empty', PHP_EOL;
    echo '    Provider name: ', $result->getSmscInfo()->getProviderName() ?: 'empty', PHP_EOL;
} else {
    echo '    empty', PHP_EOL;
}
echo 'Pdu delivered: ', $result->getPdusDelivered() ? implode(', ', $result->getPdusDelivered()) : 'empty', PHP_EOL;

HTTP Request

GET https://api.telqtele.com/v2.1/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. This id is returned by the POST /tests endpoint.

Response Details

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 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 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.