API Documentation - TextKey APIs
TextKey API Calls
Here you can find details on each of our TextKey
The navigation menu on the left includes detailed views of each API Call and Testing pages that will allow you to test each API call interactively - either with your own API credentials or with a set of testing credentials.
-
doesRegistrationUserIdExist
Description
The doesRegistrationUserIdExist API call is used to check whether or not a user has been registered with TextKey
.
API Testing Page
To test the doesRegistrationUserIdExist API Call in a fully interactive environment, click here.
Input Parameters
Name Data Type Description Required apiKey String This is a unique key that is used to authenticate an API request. It should never be exposed. Yes userID Integer The unique identifier that was used when the user was registered with TextKey . This userID is stored within the TextKey registration database and is encrypted internally to ensure it is secure.Yes isHashed Integer True indicates if the userID was hashed before the user was registered. Yes
Output
Name Data Type Description cellNumberCount Integer The count of Cell Numbers on this account that match the input (normally 0 or 1). If an error is detected, the cellNumberCount will be -2. For the UserId calls, this is always 0. userIDCount Integer The count of UserIDs on this account that match the input (normally 0 or 1). If an error is detected, the userIDCount will be -2. For the Cell Number calls, this is always 0. errorDescr String If a error occurs, this is the error message. This will be blank if the call was successful.
REST Example
RESTful URL
The TextKey
Restful interface consists of the secure URL path followed by the appropriate CommandName.For instance:
https://secure.textkey.com/REST/TKRest.asmx/CommandName
The CommandName is the API call itself which in this case is doesRegistrationUserIdExist.
Here is what the complete URL for this API call would look like:
https://secure.textkey.com/REST/TKRest.asmx/doesRegistrationUserIdExist
All Restful calls must be made using the POST method and should be of the content type application/json.
Here is an example of what a request header should look like:
POST /REST/TKRest.asmx/doesRegistrationUserIdExist HTTP/1.1 Host: secure.textkey.com Accept: */* Content-Type:application/json Content-Length: 136
JSON Input Payload
All TextKey
Restful service commands take a JSON object as the input and return a JSON object as the resulting payload. Authentication is handled via an API key as one of the parameters in the JSON input.The JSON Input payload for the doesRegistrationUserIdExist API call should look something like this:
{ "DataIn": { "apiKey": "9021fa44-f1bc-4590-b975-42fee031e078", "userId": "Stan", "isHashed": "true" } }
JSON Output Payload
The JSON response should look something like this:
JSON Response with a valid payload
{ "d":{ "__type":"TextKeyCommon.TKStructures+RegistrationExistence", "cellNumberCount":-2, "userIDCount":1, "errorDescr":"" } }
__type: TextKeyCommon.TKStructures+RegistrationExistence cellNumberCount: -2 userIDCount: 1 errorDescr:
OR
JSON Response with an error
{ "d":{ "__type":"TextKeyCommon.TKStructures+RegistrationExistence", "cellNumberCount":0, "userIDCount":0, "errorDescr":"No GUID Validation Row: Guid should contain 32 digits with 4 dashes (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)." } }
Error: No GUID Validation Row: Guid should contain 32 digits with 4 dashes (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
REST Code Examples
PHP
Example 1 - Using the TextKey
PHP Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKey object to handle all of the heavy lifting.You will be returned a PHP object and can reference all of the payload values directly from that object.
// Include the TextKey classes include_once("textkey_rest.php"); // Setup the API call parameters $testuserid ="Stan"; $isHashed = TRUE; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Create a TK object $tk = new textKey($apikey); // Handle the operation $textkey_result = $tk->perform_DoesRegistrationUserIDExist($testuserid, $isHashed); // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } echo $results; } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; echo $results; }
Here is an example of the PHP object returned:
stdClass Object ( [__type] => TextKeyCommon.TKStructures+RegistrationExistence [cellNumberCount] => -2 [userIDCount] => 1 [errorDescr] => )
Example 2 - Using the REST API Call directly
In order to use the TextKey
REST API calls directly, you will need to setup the API payload using the appropriate parameters and the API key formatted as a JSON string and then make a CURL POST request.The POST header does need to be setup as a JSON request (i.e. an application/json header) or you will not get a response.
You will be returned a JSON string as the API call payload. That can be converted into a PHP object using the json_decode call.
// TextKey REST path define('TK_REST', 'https://secure.textkey.com/REST/TKRest.asmx/'); // Setup the API call parameters $testuserid ="Stan"; $isHashed = TRUE; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Build the REST API URL $url = TK_REST . 'doesRegistrationUserIdExist'; // Setup data $postdata = json_encode( array('DataIn' => array( 'apiKey' => urlencode($apikey), 'userID' => urlencode($testuserid), 'isHashed' => urlencode($isHashed?"true":"false"), ) ), JSON_PRETTY_PRINT); // Handle the API request via CURL $curl = curl_init($url); // Set the CURL params and make sure it is a JSON request curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); curl_setopt($curl, CURLOPT_POST, true); curl_setopt($curl, CURLOPT_POSTFIELDS, $postdata); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json')); curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0); // Wildcard certificate $response = curl_exec($curl); curl_close($curl); // Handle the payload $textkey_payload = json_decode($response); if ($textkey_payload->d) { $textkey_result = $textkey_payload->d; } else { $textkey_result = $textkey_payload; }; // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } echo $results; } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; echo $results; }
JAVA
Example - Using the TextKey
JAVA Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKeyRest object to handle all of the heavy lifting.You will be returned a JSON string.
package com.textkey.rest.examples; import org.json.JSONObject; import com.textkey.rest.TextKeyRest; public class TestDoesRegistrationUserIdExist { public static void main(String[] args) { /* Setup */ String TK_API = "9021fa44-f1bc-4590-b975-42fee031e078"; /* Create the TextKey object */ TextKeyRest textkey = new TextKeyRest(TK_API, false); /* Setup the API call parameters */ String UserID = "Stan"; String isHashed = "TRUE"; /* Make the REST API Call */ String JSONpayload = textkey.perform_DoesRegistrationUserIDExist(UserID, isHashed); /* Display the API Results */ try { JSONObject results = new JSONObject(JSONpayload).getJSONObject("d"); System.out.println("Test Results: \n" + TextKeyRest.toPrettyFormat(results.toString())); } catch(Exception pe){ pe.printStackTrace(); } } }
Here is an example of the JSON string with the d wrapper removed:
Test Results: { "__type": "TextKeyCommon.TKStructures+RegistrationExistence", "cellNumberCount": -2, "errorDescr": "", "userIDCount": 1 }
NOTE: For more detais on the JAVA Library object and methods, you can take a look at the online documentation at http://textpower.github.io/RESTLibrary-java/.
RUBY
Example - Using the TextKey
RUBY Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKeyRest object to handle all of the heavy lifting.You will be returned a JSON string.
NOTE: To install the textkey_rest gem you can run gem install textkey_rest from a command line. To build the testkey_rest gem locally, get the latest repository at github and follow the instructions.
require 'json' require 'textkey_rest' # Setup apiKey = "9021fa44-f1bc-4590-b975-42fee031e078" # Create the textkey object textkey = TextKeyRest.new(apiKey, false) # Setup the API parameters userID = "Stan" isHashed = "TRUE" # Make the API Call response = textkey.perform_DoesRegistrationUserIDExist(userID, isHashed) # Pull out the data from the response response_obj = JSON.parse(response) response_data = response_obj['d'] # Display the response puts "TextKey Results:" puts JSON.pretty_generate response_data
Here is an example of the JSON string with the d wrapper removed:
Test Results: { "__type": "TextKeyCommon.TKStructures+RegistrationExistence", "cellNumberCount": -2, "errorDescr": "", "userIDCount": 1 }
NOTE: For more detais on the RUBY Library object and methods, you can take a look at the online documentation at http://textpower.github.io/RESTLibrary-ruby/.
Javascript
All of the TextKey
REST API calls are CORS compliant so they can be called via an Ajax request with no cross domain issues.In order to user the TextKey
REST API calls via javascript, you will need to setup the API payload using the appropriate parameters and the API key formatted as a JSON string and then make an Ajax POST request. The POST header does need to be setup as a JSON request (i.e. an application/json header) or you will not get a response.You will be returned a JSON string as the API call payload.
NOTE: Exposing your API key via any client side code is not recommended. If you choose to use the TextKey
API calls via a Javascript call, make sure to create a temporary API Key using the getTempAPIKey API call server side and then use that temporary key during its lifespan on any client side API calls.<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script> <script type="text/javascript"> // Build a class to handle the API call input payload function textkeyPayload(apiKey, userID, isHashed) { this.apiKey = apiKey; this.userID = userID; this.isHashed = isHashed; this.toJsonString = function () { return JSON.stringify({ 'DataIn': this }); }; }; // Handle the API Request and response function textkeyAPIRequest(txtCommand, APIJSONData) { // Setup the API URL var urlAPI = 'http://www.textkey.com/REST/TKRest.asmx/'+txtCommand; // Make the API call via a JSON Ajax request $.ajax({ type: "POST", contentType: "application/json; charset=utf-8", url: urlAPI, data: APIJSONData, dataType: "json", success: function (APIResponse, textStatus) { document.write("textStatus: "+textStatus+ "<HR>"); document.write("API Response: "+JSON.stringify(APIResponse, null, 4) + "<HR>"); if (textStatus == 'success') { if (APIResponse.hasOwnProperty('d')) { APIPayload = APIResponse.d; } else { APIPayload = APIResponse; } document.write("API Payload: "+JSON.stringify(APIPayload, null, 4) + "<HR>"); if (APIPayload.errorDescr == "") { document.write("userIDCount: " + APIPayload.userIDCount); } else { document.write("Error: " + APIPayload.errorDescr); } } else { document.write("Error: " + textStatus); } }, error: function (jqXHR, textStatus, errorThrown) { document.write("Error: " + jqXHR.status); } }); } // Setup the API command var txtCommand = 'doesRegistrationUserIdExist'; // Build the API payload var DoesRegistrationUserIdExist = new textkeyPayload("9021fa44-f1bc-4590-b975-42fee031e078", "Stan", true); // Make the API Call textkeyAPIRequest(txtCommand, DoesRegistrationUserIdExist.toJsonString()); </script>
SOAP Example
- Step 1 - Authentication Settings
- Step 2 - Call Parameters
- Step 3 - SOAP Request
- Step 4 - SOAP Response
- Step 5 - Output Results
Authentication Settings
A SOAP header is required on all SOAP API calls using the _Key variant and the header information is identical on all calls.
doesRegistrationUserIdExist requires a SOAP header.
doesRegistrationUserIdExist_Key does not require a SOAP header but uses the API Key in the body of the SOAP request.Authentication Settings using an API Key
API Key: 9021fa44-f1bc-4590-b975-42fee031e078
OR
Authentication Settings using an UserID/Password Combination
userId: 1ed93006208f0540e452e3a37d8299bc
Password: Password12345
Campaign:
Keyword:The WSDL document for the TextKey
SOAP interface is located at: https://secure.textkey.com/ws/textkey.asmx?wsdl.The address for the SOAP calls on the TextKey
interface is: https://secure.textkey.com/ws/textkey.asmx.The name space for the SOAP calls on the TextKey
interface is: https://secure.textkey.com/services/.Call Parameters
The parameters should look something like this:
apiKey: 9021fa44-f1bc-4590-b975-42fee031e078
userID: Stan
isHashed: 1SOAP Request
The SOAP request should look something like this:
SOAP Request using the API Key
OR
SOAP Request using the UserID/Password
SOAP Response
The SOAP response should look something like this:
SOAP Response with an valid payload
OR
SOAP Response with an error
Output Results
The final results will need to be extracted from the XML response payload should look something like this:
SOAP Response with a valid payload
stdClass Object ( [cellNumberCount] => -2 [userIDCount] => 0 [errorDescr] => )
cellNumberCount: -2 userIDCount: 0 errorDescr:
OR
SOAP Response with an error
stdClass Object ( [cellNumberCount] => 0 [userIDCount] => 0 [errorDescr] => No GUID Validation Row: Guid should contain 32 digits with 4 dashes (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). )
Error: No GUID Validation Row: Guid should contain 32 digits with 4 dashes (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
SOAP Code Examples
PHP
The PHP Helper library contain a textkey class that makes calling TextKey
SOAP API functions simple. Just include the helper file textkey_soap.php in your PHP code, inititalize a textkey object using your credentials (i.e. either an API key or a UserID/Password), and then make the API call with the appropriate parameters. You will be returned an object with the API call payload.// Include the TextKey classes include_once("../textkey_soap.php"); // Setup the API call parameters $testuserid ="Stan"; $isHashed = TRUE; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Create a textkey object if ($apikey != "") { $tk = new textKey("", "", "", "", $apikey); } // Handle the operation $textkey_result = $tk->perform_DoesRegistrationUserIDExist($testuserid, $isHashed); // Show the textkey API payload object print_r($textkey_result); echo "<HR>"; // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; } echo $results;
CURL
From a command line, you can test the SOAP API calls using a CURL request:
The SOAP doesRegistrationUserIdExist Request is stored in a file called doesRegistrationUserIdExist.xml
<?xml version="1.0" encoding="UTF-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" > <soap:Body> <doesRegistrationUserIdExist_Key xmlns="https://secure.textkey.com/services/"> <apiKey>9021fa44-f1bc-4590-b975-42fee031e078</apiKey> <userID>Stan</userID> <isHashed>true</isHashed> </doesRegistrationUserIdExist_Key> </soap:Body> </soap:Envelope>
CURL command using doesRegistrationUserIdExist.xml
curl -H "Content-Type: text/xml; charset=utf-8" -H "SOAPAction:" -d @doesRegistrationUserIdExist.xml -X POST https://secure.textkey.com/ws/textkey.asmx
XML Response from API doesRegistrationUserIdExist Request
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Body> <doesRegistrationUserIdExist_KeyResponse xmlns="https://secure.textkey.com/services/"> <doesRegistrationUserIdExist_KeyResult> <cellNumberCount>-2</cellNumberCount> <userIDCount>1</userIDCount> <errorDescr /> </doesRegistrationUserIdExist_KeyResult> </doesRegistrationUserIdExist_KeyResponse> </soap:Body> </soap:Envelope>
-
doesRegistrationCellNumberExist
Description
The doesRegistrationCellNumberExist API call is used to check whether or not a cell number has been registered with TextKey
.
API Testing Page
To test the doesRegistrationCellNumberExist API Call in a fully interactive environment, click here.
Input Parameters
Name Data Type Description Required apiKey String This is a unique key that is used to authenticate an API request. It should never be exposed. Yes cellNumber String The Cell Number or Cell Number proxy that was used when the user was registered with TextKey .Yes
Output
Name Data Type Description cellNumberCount Integer The count of Cell Numbers on this account that match. This count is normally 0 or 1. ). If an error is detected, the cellNumberCount will be -2. errorDescr String If a error occurs, this is the error message. This will be blank if the call was successful.
REST Example
RESTful URL
The TextKey
Restful interface consists of the secure URL path followed by the appropriate CommandName.For instance:
https://secure.textkey.com/REST/TKRest.asmx/CommandName
The CommandName is the API call itself which in this case is doesRegistrationCellNumberExist.
Here is what the complete URL for this API call would look like:
https://secure.textkey.com/REST/TKRest.asmx/doesRegistrationCellNumberExist
All Restful calls must be made using the POST method and should be of the content type application/json.
Here is an example of what a request header should look like:
POST /REST/TKRest.asmx/doesRegistrationCellNumberExist HTTP/1.1 Host: secure.textkey.com Accept: */* Content-Type:application/json Content-Length: 118
JSON Input Payload
All TextKey
Restful service commands take a JSON object as the input and return a JSON object as the resulting payload. Authentication is handled via an API key as one of the parameters in the JSON input.The JSON Input payload for the doesRegistrationCellNumberExist API call should look something like this:
{ "DataIn": { "apiKey": "9021fa44-f1bc-4590-b975-42fee031e078", "cellNumber": "8181231234" } }
JSON Output Payload
The JSON response should look something like this:
JSON Response with a valid payload
{ "d":{ "__type":"TextKeyCommon.TKStructures+RegistrationExistence", "cellNumberCount":1, "userIDCount":-2, "errorDescr":"" } }
__type: TextKeyCommon.TKStructures+RegistrationExistence cellNumberCount: 1 userIDCount: -2 errorDescr:
OR
JSON Response with an error
{ "d":{ "__type":"TextKeyCommon.TKStructures+RegistrationExistence", "cellNumberCount":0, "userIDCount":0, "errorDescr":"No GUID Validation Row: Guid should contain 32 digits with 4 dashes (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)." } }
Error: No GUID Validation Row: Guid should contain 32 digits with 4 dashes (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
REST Code Examples
PHP
Example 1 - Using the TextKey
PHP Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKey object to handle all of the heavy lifting.You will be returned a PHP object and can reference all of the payload values directly from that object.
// Include the TextKey classes include_once("textkey_rest.php"); // Setup the API call parameters $cellnumber = "8181231234"; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Create a TK object $tk = new textKey($apikey); // Handle the operation $textkey_result = $tk->perform_DoesRegistrationCellNumberExist($cellnumber); // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { if (is_array($value)) { $results .= $key . ': ' . var_export($value, true) . "
";; } else if (is_object($value)) { $results .= $key . ': ' . print_r($value, true); } else { $results .= $key . ': ' . $value . "
";; } } echo $results; } else { $results = 'Error: ' . $textkey_result->errorDescr . "
"; echo $results; }Here is an example of the PHP object returned:
stdClass Object ( [__type] => TextKeyCommon.TKStructures+RegistrationExistence [cellNumberCount] => 1 [userIDCount] => -2 [errorDescr] => )
Example 2 - Using the REST API Call directly
In order to use the TextKey
REST API calls directly, you will need to setup the API payload using the appropriate parameters and the API key formatted as a JSON string and then make a CURL POST request.The POST header does need to be setup as a JSON request (i.e. an application/json header) or you will not get a response.
You will be returned a JSON string as the API call payload. That can be converted into a PHP object using the json_decode call.
// TextKey REST path define('TK_REST', 'https://secure.textkey.com/REST/TKRest.asmx/'); // Setup the API call parameters $cellnumber = "8181231234"; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Build the REST API URL $url = TK_REST . 'doesRegistrationCellNumberExist'; // Setup data $postdata = json_encode( array('DataIn' => array( 'apiKey' => urlencode($apikey), 'cellNumber' => urlencode($cellnumber) ) ), JSON_PRETTY_PRINT); // Handle the API request via CURL $curl = curl_init($url); // Set the CURL params and make sure it is a JSON request curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); curl_setopt($curl, CURLOPT_POST, true); curl_setopt($curl, CURLOPT_POSTFIELDS, $postdata); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json')); curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0); // Wildcard certificate $response = curl_exec($curl); curl_close($curl); // Handle the payload $textkey_payload = json_decode($response); if ($textkey_payload->d) { $textkey_result = $textkey_payload->d; } else { $textkey_result = $textkey_payload; }; // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { if (is_array($value)) { $results .= $key . ': ' . var_export($value, true) . "
";; } else if (is_object($value)) { $results .= $key . ': ' . print_r($value, true); } else { $results .= $key . ': ' . $value . "
";; } } echo $results; } else { $results = 'Error: ' . $textkey_result->errorDescr . "
"; echo $results; }JAVA
Example - Using the TextKey
JAVA Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKeyRest object to handle all of the heavy lifting.You will be returned a JSON string.
package com.textkey.rest.examples; import org.json.JSONObject; import com.textkey.rest.TextKeyRest; public class TestDoesRegistrationCellNumberExist { public static void main(String[] args) { /* Setup */ String TK_API = "9021fa44-f1bc-4590-b975-42fee031e078"; /* Create the TextKey object */ TextKeyRest textkey = new TextKeyRest(TK_API, false); /* Setup the API call parameters */ String CellNumber = "8181231234"; /* Make the REST API Call */ String JSONpayload = textkey.perform_DoesRegistrationCellNumberExist(CellNumber); /* Display the API Results */ try { JSONObject results = new JSONObject(JSONpayload).getJSONObject("d"); System.out.println("Test Results: \n" + TextKeyRest.toPrettyFormat(results.toString())); } catch(Exception pe){ pe.printStackTrace(); } } }
Here is an example of the JSON string with the d wrapper removed:
Test Results: { "__type": "TextKeyCommon.TKStructures+RegistrationExistence", "cellNumberCount": 1, "errorDescr": "", "userIDCount": -2 }
NOTE: For more detais on the JAVA Library object and methods, you can take a look at the online documentation at http://textpower.github.io/RESTLibrary-java/.
RUBY
Example - Using the TextKey
RUBY Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKeyRest object to handle all of the heavy lifting.You will be returned a JSON string.
NOTE: To install the textkey_rest gem you can run gem install textkey_rest from a command line. To build the testkey_rest gem locally, get the latest repository at github and follow the instructions.
require 'json' require 'textkey_rest' # Setup apiKey = "9021fa44-f1bc-4590-b975-42fee031e078" # Create the textkey object textkey = TextKeyRest.new(apiKey, false) # Setup the API parameters cellNumber = "8181231234" # Make the API Call response = textkey.perform_DoesRegistrationCellNumberExist(cellNumber) # Pull out the data from the response response_obj = JSON.parse(response) response_data = response_obj['d'] # Display the response puts "TextKey Results:" puts JSON.pretty_generate response_data
Here is an example of the JSON string with the d wrapper removed:
Test Results: { "__type": "TextKeyCommon.TKStructures+RegistrationExistence", "cellNumberCount": 1, "errorDescr": "", "userIDCount": -2 }
NOTE: For more detais on the RUBY Library object and methods, you can take a look at the online documentation at http://textpower.github.io/RESTLibrary-ruby/.
Javascript
All of the TextKey
REST API calls are CORS compliant so they can be called via an Ajax request with no cross domain issues.In order to user the TextKey
REST API calls via javascript, you will need to setup the API payload using the appropriate parameters and the API key formatted as a JSON string and then make an Ajax POST request. The POST header does need to be setup as a JSON request (i.e. an application/json header) or you will not get a response.You will be returned a JSON string as the API call payload.
NOTE: Exposing your API key via any client side code is not recommended. If you choose to use the TextKey
API calls via a Javascript call, make sure to create a temporary API Key using the getTempAPIKey API call server side and then use that temporary key during its lifespan on any client side API calls.<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script> <script type="text/javascript"> // Build a class to handle the API call input payload function textkeyPayload(apiKey, cellNumber) { this.apiKey = apiKey; this.cellNumber = cellNumber; this.toJsonString = function () { return JSON.stringify({ 'DataIn': this }); }; }; // Handle the API Request and response function textkeyAPIRequest(txtCommand, APIJSONData) { // Setup the API URL var urlAPI = 'http://www.textkey.com/REST/TKRest.asmx/'+txtCommand; // Make the API call via a JSON Ajax request $.ajax({ type: "POST", contentType: "application/json; charset=utf-8", url: urlAPI, data: APIJSONData, dataType: "json", success: function (APIResponse, textStatus) { document.write("textStatus: "+textStatus+ "<HR>"); document.write("API Response: "+JSON.stringify(APIResponse, null, 4) + "<HR>"); if (textStatus == 'success') { if (APIResponse.hasOwnProperty('d')) { APIPayload = APIResponse.d; } else { APIPayload = APIResponse; } document.write("API Payload: "+JSON.stringify(APIPayload, null, 4) + "<HR>"); if (APIPayload.errorDescr == "") { document.write("cellNumberCount: " + APIPayload.cellNumberCount); } else { document.write("Error: " + APIPayload.errorDescr); } } else { document.write("Error: " + textStatus); } }, error: function (jqXHR, textStatus, errorThrown) { document.write("Error: " + jqXHR.status); } }); } // Setup the API command var txtCommand = 'doesRegistrationCellNumberExist'; // Build the API payload var doesRegistrationCellNumberExist = new textkeyPayload("9021fa44-f1bc-4590-b975-42fee031e078", "8181231234"); // Make the API Call textkeyAPIRequest(txtCommand, doesRegistrationCellNumberExist.toJsonString()); </script>
SOAP Example
- Step 1 - Authentication Settings
- Step 2 - Call Parameters
- Step 3 - SOAP Request
- Step 4 - SOAP Response
- Step 5 - Output Results
Authentication Settings
A SOAP header is required on all SOAP API calls using the _Key variant and the header information is identical on all calls.
doesRegistrationCellNumberExist requires a SOAP header.
doesRegistrationCellNumberExist_Key does not require a SOAP header but uses the API Key in the body of the SOAP request.Authentication Settings using an API Key
API Key: 9021fa44-f1bc-4590-b975-42fee031e078
OR
Authentication Settings using an UserID/Password Combination
userId: 1ed93006208f0540e452e3a37d8299bc
Password: Password12345
Campaign:
Keyword:The WSDL document for the TextKey
SOAP interface is located at: https://secure.textkey.com/ws/textkey.asmx?wsdl.The address for the SOAP calls on the TextKey
interface is: https://secure.textkey.com/ws/textkey.asmx.The name space for the SOAP calls on the TextKey
interface is: https://secure.textkey.com/services/.Call Parameters
The parameters should look something like this:
apiKey: 9021fa44-f1bc-4590-b975-42fee031e078 cellNumber: 8181231234
SOAP Request
The SOAP request should look something like this:
SOAP Request using the API Key
OR
SOAP Request using the UserID/Password
SOAP Response
The SOAP response should look something like this:
SOAP Response with an valid payload
OR
SOAP Response with an error
Output Results
The final results will need to be extracted from the XML response payload should look something like this:
SOAP Response with a valid payload
stdClass Object ( [cellNumberCount] => 1 [userIDCount] => -2 [errorDescr] => )
cellNumberCount: -2 userIDCount: 0 errorDescr:
OR
SOAP Response with an error
stdClass Object ( [cellNumberCount] => 0 [userIDCount] => 0 [errorDescr] => No GUID Validation Row: Guid should contain 32 digits with 4 dashes (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). )
Error: No GUID Validation Row: Guid should contain 32 digits with 4 dashes (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
SOAP Code Examples
PHP
The PHP Helper library contain a textkey class that makes calling TextKey
SOAP API functions simple. Just include the helper file textkey_soap.php in your PHP code, inititalize a textkey object using your credentials (i.e. either an API key or a UserID/Password), and then make the API call with the appropriate parameters. You will be returned an object with the API call payload.// Include the TextKey classes include_once("../textkey_soap.php"); // Setup the API call parameters $cellnumber = "8181231234"; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Create a textkey object if ($apikey != "") { $tk = new textKey("", "", "", "", $apikey); } // Handle the operation $textkey_result = $tk->perform_DoesRegistrationCellNumberExist($cellnumber); // Show the textkey API payload object print_r($textkey_result); echo "<HR>"; // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; } echo $results;
CURL
From a command line, you can test the SOAP API calls using a CURL request:
The SOAP doesRegistrationCellNumberExist Request is stored in a file called doesRegistrationCellNumberExist.xml
<?xml version="1.0" encoding="UTF-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" > <soap:Body> <doesRegistrationCellNumberExist_Key xmlns="https://secure.textkey.com/services/"> <apiKey>9021fa44-f1bc-4590-b975-42fee031e078</apiKey> <cellNumber>8181231234</cellNumber> </doesRegistrationCellNumberExist_Key> </soap:Body> </soap:Envelope>
CURL command using doesRegistrationCellNumberExist.xml
curl -H "Content-Type: text/xml; charset=utf-8" -H "SOAPAction:" -d @doesRegistrationCellNumberExist.xml -X POST https://secure.textkey.com/ws/textkey.asmx
XML Response from API doesRegistrationCellNumberExist Request
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Body> <doesRegistrationCellNumberExist_KeyResponse xmlns="https://secure.textkey.com/services/"> <doesRegistrationCellNumberExist_KeyResult> <cellNumberCount>1</cellNumberCount> <userIDCount>-2</userIDCount> <errorDescr /> </doesRegistrationCellNumberExist_KeyResult> </doesRegistrationCellNumberExist_KeyResponse> </soap:Body> </soap:Envelope>
-
createNewCellNumberProxy
Description
The createNewCellNumberProxy API call is used to create a Cell Number Proxy for use in insecure environments such as a browser.
API Testing Page
To test the createNewCellNumberProxy API Call in a fully interactive environment, click here.
Input Parameters
Name Data Type Description Required apiKey String This is a unique key that is used to authenticate an API request. It should never be exposed. Yes trueCellNumber String The actual Cell Number that will be used to create a Cell Number Proxy. Yes
Output
Name Data Type Description cellNumberProxy String The cellNumberProxy to be used in subsequent calls that require a cellNumber parameter. errorDescr String If a error occurs, this is the error message. This will be blank if the call was successful.
REST Example
RESTful URL
The TextKey
Restful interface consists of the secure URL path followed by the appropriate CommandName.For instance:
https://secure.textkey.com/REST/TKRest.asmx/CommandName
The CommandName is the API call itself which in this case is createNewCellNumberProxy.
Here is what the complete URL for this API call would look like:
https://secure.textkey.com/REST/TKRest.asmx/createNewCellNumberProxy
All Restful calls must be made using the POST method and should be of the content type application/json.
Here is an example of what a request header should look like:
POST /REST/TKRest.asmx/createNewCellNumberProxy HTTP/1.1 Host: secure.textkey.com Accept: */* Content-Type:application/json Content-Length: 122
JSON Input Payload
All TextKey
Restful service commands take a JSON object as the input and return a JSON object as the resulting payload. Authentication is handled via an API key as one of the parameters in the JSON input.The JSON Input payload for the createNewCellNumberProxy API call should look something like this:
{ "DataIn": { "apiKey": "9021fa44-f1bc-4590-b975-42fee031e078", "trueCellNumber": "8181231234" } }
JSON Output Payload
The JSON response should look something like this:
JSON Response with a valid payload
{ "d":{ "__type":"TextKeyCommon.TKStructures+CreateCellNumberProxyReturn", "cellNumberProxy":"638DFA40-C6E6-4B73-95F4-A70F53B2C3FC", "errorDescr":"" } }
__type: TextKeyCommon.TKStructures+CreateCellNumberProxyReturn cellNumberProxy: 638DFA40-C6E6-4B73-95F4-A70F53B2C3FC errorDescr:
OR
JSON Response with an error
{ "d":{ "__type":"TextKeyCommon.TKStructures+CreateCellNumberProxyReturn", "cellNumberProxy":"", "errorDescr":"Invalid Login" } }
Error: Invalid Login.
REST Code Examples
PHP
Example 1 - Using the TextKey
PHP Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKey object to handle all of the heavy lifting.You will be returned a PHP object and can reference all of the payload values directly from that object.
// Include the TextKey classes include_once("textkey_rest.php"); // Setup the API call parameters $cellnumber = "8181231234"; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Create a TK object $tk = new textKey($apikey); // Handle the operation $textkey_result = $tk->perform_CreateNewCellNumberProxy($cellnumber); // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } echo $results; } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; echo $results; }
Here is an example of the PHP object returned:
stdClass Object ( [__type] => TextKeyCommon.TKStructures+CreateCellNumberProxyReturn [cellNumberProxy] => BFE51175-56A0-4A47-98FF-739FDB479CD4 [errorDescr] => )
Example 2 - Using the REST API Call directly
In order to use the TextKey
REST API calls directly, you will need to setup the API payload using the appropriate parameters and the API key formatted as a JSON string and then make a CURL POST request.The POST header does need to be setup as a JSON request (i.e. an application/json header) or you will not get a response.
You will be returned a JSON string as the API call payload. That can be converted into a PHP object using the json_decode call.
// TextKey REST path define('TK_REST', 'https://secure.textkey.com/REST/TKRest.asmx/'); // Setup the API call parameters $cellnumber = "8181231234"; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Build the REST API URL $url = TK_REST . 'createNewCellNumberProxy'; // Setup data $postdata = json_encode( array('DataIn' => array( 'apiKey' => urlencode($apikey), 'trueCellNumber' => urlencode($cellnumber) ) ), JSON_PRETTY_PRINT); // Handle the API request via CURL $curl = curl_init($url); // Set the CURL params and make sure it is a JSON request curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); curl_setopt($curl, CURLOPT_POST, true); curl_setopt($curl, CURLOPT_POSTFIELDS, $postdata); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json')); curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0); // Wildcard certificate $response = curl_exec($curl); curl_close($curl); // Handle the payload $textkey_payload = json_decode($response); if ($textkey_payload->d) { $textkey_result = $textkey_payload->d; } else { $textkey_result = $textkey_payload; }; // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { if (is_array($value)) { $results .= $key . ': ' . var_export($value, true) . "
";; } else if (is_object($value)) { $results .= $key . ': ' . print_r($value, true); } else { $results .= $key . ': ' . $value . "
";; } } echo $results; } else { $results = 'Error: ' . $textkey_result->errorDescr . "
"; echo $results; }JAVA
Example - Using the TextKey
JAVA Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKeyRest object to handle all of the heavy lifting.You will be returned a JSON string.
package com.textkey.rest.examples; import org.json.JSONObject; import com.textkey.rest.TextKeyRest; public class TestCreateNewCellNumberProxy { public static void main(String[] args) { /* Setup */ String TK_API = "9021fa44-f1bc-4590-b975-42fee031e078"; /* Create the TextKey object */ TextKeyRest textkey = new TextKeyRest(TK_API, false); /* Setup the API call parameters */ String CellNumber = "8181231234"; /* Make the REST API Call */ String JSONpayload = textkey.perform_CreateNewCellNumberProxy(CellNumber); /* Display the API Results */ try { JSONObject results = new JSONObject(JSONpayload).getJSONObject("d"); System.out.println("Test Results: \n" + TextKeyRest.toPrettyFormat(results.toString())); } catch(Exception pe){ pe.printStackTrace(); } } }
Here is an example of the JSON string with the d wrapper removed:
Test Results: { "__type": "TextKeyCommon.TKStructures+CreateCellNumberProxyReturn", "errorDescr": "", "cellNumberProxy": "C4BFB569-2525-4103-B5C7-507AF7402E31" }
NOTE: For more detais on the JAVA Library object and methods, you can take a look at the online documentation at http://textpower.github.io/RESTLibrary-java/.
RUBY
Example - Using the TextKey
RUBY Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKeyRest object to handle all of the heavy lifting.You will be returned a JSON string.
NOTE: To install the textkey_rest gem you can run gem install textkey_rest from a command line. To build the testkey_rest gem locally, get the latest repository at github and follow the instructions.
require 'json' require 'textkey_rest' # Setup apiKey = "9021fa44-f1bc-4590-b975-42fee031e078" # Create the textkey object textkey = TextKeyRest.new(apiKey, false) # Setup the API parameters cellNumber = "8181231234" # Make the API Call response = textkey.perform_CreateNewCellNumberProxy(cellNumber) # Pull out the data from the response response_obj = JSON.parse(response) response_data = response_obj['d'] # Display the response puts "TextKey Results:" puts JSON.pretty_generate response_data
Here is an example of the JSON string with the d wrapper removed:
Test Results: { "__type": "TextKeyCommon.TKStructures+CreateCellNumberProxyReturn", "errorDescr": "", "cellNumberProxy": "C4BFB569-2525-4103-B5C7-507AF7402E31" }
NOTE: For more detais on the RUBY Library object and methods, you can take a look at the online documentation at http://textpower.github.io/RESTLibrary-ruby/.
Javascript
All of the TextKey
REST API calls are CORS compliant so they can be called via an Ajax request with no cross domain issues.In order to user the TextKey
REST API calls via javascript, you will need to setup the API payload using the appropriate parameters and the API key formatted as a JSON string and then make an Ajax POST request. The POST header does need to be setup as a JSON request (i.e. an application/json header) or you will not get a response.You will be returned a JSON string as the API call payload.
NOTE: Exposing your API key via any client side code is not recommended. If you choose to use the TextKey
API calls via a Javascript call, make sure to create a temporary API Key using the getTempAPIKey API call server side and then use that temporary key during its lifespan on any client side API calls.<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script> <script type="text/javascript"> // Build a class to handle the API call input payload function textkeyPayload(apiKey, cellNumber) { this.apiKey = apiKey; this.trueCellNumber = cellNumber; this.toJsonString = function () { return JSON.stringify({ 'DataIn': this }); }; }; // Handle the API Request and response function textkeyAPIRequest(txtCommand, APIJSONData) { // Setup the API URL var urlAPI = 'http://www.textkey.com/REST/TKRest.asmx/'+txtCommand; // Make the API call via a JSON Ajax request $.ajax({ type: "POST", contentType: "application/json; charset=utf-8", url: urlAPI, data: APIJSONData, dataType: "json", success: function (APIResponse, textStatus) { document.write("textStatus: "+textStatus+ "<HR>"); document.write("API Response: "+JSON.stringify(APIResponse, null, 4) + "<HR>"); if (textStatus == 'success') { if (APIResponse.hasOwnProperty('d')) { APIPayload = APIResponse.d; } else { APIPayload = APIResponse; } document.write("API Payload: "+JSON.stringify(APIPayload, null, 4) + "<HR>"); if (APIPayload.errorDescr == "") { document.write("cellNumberProxy: " + APIPayload.cellNumberProxy); } else { document.write("Error: " + APIPayload.errorDescr); } } else { document.write("Error: " + textStatus); } }, error: function (jqXHR, textStatus, errorThrown) { document.write("Error: " + jqXHR.status); } }); } // Setup the API command var txtCommand = 'createNewCellNumberProxy'; // Build the API payload var createNewCellNumberProxy = new textkeyPayload("9021fa44-f1bc-4590-b975-42fee031e078", "8181231234"); // Make the API Call textkeyAPIRequest(txtCommand, createNewCellNumberProxy.toJsonString()); </script>
SOAP Example
- Step 1 - Authentication Settings
- Step 2 - Call Parameters
- Step 3 - SOAP Request
- Step 4 - SOAP Response
- Step 5 - Output Results
Authentication Settings
A SOAP header is required on all SOAP API calls using the _Key variant and the header information is identical on all calls.
createNewCellNumberProxy requires a SOAP header.
createNewCellNumberProxy_Key does not require a SOAP header but uses the API Key in the body of the SOAP request.Authentication Settings using an API Key
API Key: 9021fa44-f1bc-4590-b975-42fee031e078
OR
Authentication Settings using an UserID/Password Combination
userId: 1ed93006208f0540e452e3a37d8299bc
Password: Password12345
Campaign:
Keyword:The WSDL document for the TextKey
SOAP interface is located at: https://secure.textkey.com/ws/textkey.asmx?wsdl.The address for the SOAP calls on the TextKey
interface is: https://secure.textkey.com/ws/textkey.asmx.The name space for the SOAP calls on the TextKey
interface is: https://secure.textkey.com/services/.Call Parameters
The parameters should look something like this:
apiKey: 9021fa44-f1bc-4590-b975-42fee031e078
trueCellNumber: 8181231234SOAP Request
The SOAP request should look something like this:
SOAP Request using the API Key
OR
SOAP Request using the UserID/Password
SOAP Response
The SOAP response should look something like this:
SOAP Response with an valid payload
OR
SOAP Response with an error
Output Results
The final results will need to be extracted from the XML response payload should look something like this:
SOAP Response with a valid payload
stdClass Object ( [cellNumberProxy] => 2D76BD40-B0F3-4A6A-AD9D-B4B700763F7F [errorDescr] => )
cellNumberProxy: 2D76BD40-B0F3-4A6A-AD9D-B4B700763F7F errorDescr:
OR
SOAP Response with an error
stdClass Object ( [cellNumberProxy] => [errorDescr] => Invalid Login )
Error: Invalid Login.
SOAP Code Examples
PHP
The PHP Helper library contain a textkey class that makes calling TextKey
SOAP API functions simple. Just include the helper file textkey_soap.php in your PHP code, inititalize a textkey object using your credentials (i.e. either an API key or a UserID/Password), and then make the API call with the appropriate parameters. You will be returned an object with the API call payload.// Include the TextKey classes include_once("../textkey_soap.php"); // Setup the API call parameters $cellnumber = "8181231234"; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Create a textkey object if ($apikey != "") { $tk = new textKey("", "", "", "", $apikey); } // Handle the operation $textkey_result = $tk->perform_CreateNewCellNumberProxy($cellnumber); // Show the textkey API payload object print_r($textkey_result); echo "<HR>"; // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; } echo $results;
CURL
From a command line, you can test the SOAP API calls using a CURL request:
The SOAP createNewCellNumberProxy Request is stored in a file called createNewCellNumberProxy.xml
<?xml version="1.0" encoding="UTF-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" > <soap:Body> <createNewCellNumberProxy_Key xmlns="https://secure.textkey.com/services/"> <apiKey>9021fa44-f1bc-4590-b975-42fee031e078</apiKey> <trueCellNumber>8181231234</trueCellNumber> </createNewCellNumberProxy_Key> </soap:Body> </soap:Envelope>
CURL command using createNewCellNumberProxy.xml
curl -H "Content-Type: text/xml; charset=utf-8" -H "SOAPAction:" -d @createNewCellNumberProxy.xml -X POST https://secure.textkey.com/ws/textkey.asmx
XML Response from API createNewCellNumberProxy Request
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Body> <createNewCellNumberProxy_KeyResponse xmlns="https://secure.textkey.com/services/"> <createNewCellNumberProxy_KeyResult> <cellNumberProxy>5D82FBAF-C5E2-4F2B-8639-81F835AB1382</cellNumberProxy> <errorDescr /> </createNewCellNumberProxy_KeyResult> </createNewCellNumberProxy_KeyResponse> </soap:Body> </soap:Envelope>
-
getTempAPIKey
Description
The getTempAPIKey API call is used to obtain a temporary API Key and has a limited lifetime to provide security.
API Testing Page
To test the getTempAPIKey API Call in a fully interactive environment, click here.
Input Parameters
Name Data Type Description Required apiKey String This is a unique key that is used to authenticate an API request. It should never be exposed. Yes minutesDuration Integer The number of minutes that this API key will be valid.
MinutesDuration must be between 1 and 9.
If the client functions are not completed within this time limit, a new temporary API key must be obtained.Yes
Output
Name Data Type Description apiKey String The temporary API Key that is valid for MinutesDuration minutes. errorDescr String If a error occurs, this is the error message. This will be blank if the call was successful.
REST Example
RESTful URL
The TextKey
Restful interface consists of the secure URL path followed by the appropriate CommandName.For instance:
https://secure.textkey.com/REST/TKRest.asmx/CommandName
The CommandName is the API call itself which in this case is getTempAPIKey.
Here is what the complete URL for this API call would look like:
https://secure.textkey.com/REST/TKRest.asmx/getTempAPIKey
All Restful calls must be made using the POST method and should be of the content type application/json.
Here is an example of what a request header should look like:
POST /REST/TKRest.asmx/getTempAPIKey HTTP/1.1 Host: secure.textkey.com Accept: */* Content-Type:application/json Content-Length: 114
JSON Input Payload
All TextKey
Restful service commands take a JSON object as the input and return a JSON object as the resulting payload. Authentication is handled via an API key as one of the parameters in the JSON input.The JSON Input payload for the getTempAPIKey API call should look something like this:
{ "DataIn": { "apiKey": "9021fa44-f1bc-4590-b975-42fee031e078", "minutesDuration": "2" } }
JSON Output Payload
The JSON response should look something like this:
JSON Response with a valid payload
{ "d":{ "__type":"TextKeyCommon.TKStructures+TempAPIKeyReturn", "apiKey":"E6E74FB8-FA2A-4F50-A335-5AB74570CA20", "errorDescr":"" } }
__type: TextKeyCommon.TKStructures+TempAPIKeyReturn apiKey: E6E74FB8-FA2A-4F50-A335-5AB74570CA20 errorDescr:
OR
JSON Response with an error
{ "d":{ "__type":"TextKeyCommon.TKStructures+TempAPIKeyReturn", "apiKey":"", "errorDescr":"Invalid Login" } }
Error: Invalid Login.
REST Code Examples
PHP
Example 1 - Using the TextKey
PHP Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKey object to handle all of the heavy lifting.You will be returned a PHP object and can reference all of the payload values directly from that object.
// Include the TextKey classes include_once("textkey_rest.php"); // Setup the API call parameters $minutesDuration = 2; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Create a TK object $tk = new textKey($apikey); // Handle the operation $textkey_result = $tk->perform_GetTempAPI_Key($minutesDuration); // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } echo $results; } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; echo $results; }
Here is an example of the PHP object returned:
stdClass Object ( [__type] => TextKeyCommon.TKStructures+TempAPIKeyReturn [apiKey] => FE68EAE2-C0A0-48E1-837B-9486A1CA7037 [errorDescr] => )
Example 2 - Using the REST API Call directly
In order to use the TextKey
REST API calls directly, you will need to setup the API payload using the appropriate parameters and the API key formatted as a JSON string and then make a CURL POST request.The POST header does need to be setup as a JSON request (i.e. an application/json header) or you will not get a response.
You will be returned a JSON string as the API call payload. That can be converted into a PHP object using the json_decode call.
// TextKey REST path define('TK_REST', 'https://secure.textkey.com/REST/TKRest.asmx/'); // Setup the API call parameters $minutesDuration = 2; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Build the REST API URL $url = TK_REST . 'getTempAPIKey'; // Setup data $postdata = json_encode( array('DataIn' => array( 'apiKey' => urlencode($apikey), 'minutesDuration' => urlencode($minutesDuration) ) ), JSON_PRETTY_PRINT); // Handle the API request via CURL $curl = curl_init($url); // Set the CURL params and make sure it is a JSON request curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); curl_setopt($curl, CURLOPT_POST, true); curl_setopt($curl, CURLOPT_POSTFIELDS, $postdata); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json')); curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0); // Wildcard certificate $response = curl_exec($curl); curl_close($curl); // Handle the payload $textkey_payload = json_decode($response); if ($textkey_payload->d) { $textkey_result = $textkey_payload->d; } else { $textkey_result = $textkey_payload; }; // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } echo $results; } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; echo $results; }
JAVA
Example - Using the TextKey
JAVA Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKeyRest object to handle all of the heavy lifting.You will be returned a JSON string.
package com.textkey.rest.examples; import org.json.JSONObject; import com.textkey.rest.TextKeyRest; public class TestGetTempAPIKey { public static void main(String[] args) { /* Setup */ String TK_API = "9021fa44-f1bc-4590-b975-42fee031e078"; /* Create the TextKey object */ TextKeyRest textkey = new TextKeyRest(TK_API, false); /* Setup the API call parameters */ Integer minutesDuration = 2; /* Make the REST API Call */ String JSONpayload = textkey.perform_GetTempAPI_Key(minutesDuration); /* Display the API Results */ try { JSONObject results = new JSONObject(JSONpayload).getJSONObject("d"); System.out.println("Test Results: \n" + TextKeyRest.toPrettyFormat(results.toString())); } catch(Exception pe){ pe.printStackTrace(); } } }
Here is an example of the JSON string with the d wrapper removed:
Test Results: { "__type": "TextKeyCommon.TKStructures+TempAPIKeyReturn", "errorDescr": "", "apiKey": "6A648863-6818-4B41-AECE-34471D5D9DC1" }
NOTE: For more detais on the JAVA Library object and methods, you can take a look at the online documentation at http://textpower.github.io/RESTLibrary-java/.
RUBY
Example - Using the TextKey
RUBY Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKeyRest object to handle all of the heavy lifting.You will be returned a JSON string.
NOTE: To install the textkey_rest gem you can run gem install textkey_rest from a command line. To build the testkey_rest gem locally, get the latest repository at github and follow the instructions.
require 'json' require 'textkey_rest' # Setup apiKey = "9021fa44-f1bc-4590-b975-42fee031e078" # Create the textkey object textkey = TextKeyRest.new(apiKey, false) # Setup the API parameters minutesDuration = 2 # Make the API Call response = textkey.perform_GetTempAPI_Key(minutesDuration) # Pull out the data from the response response_obj = JSON.parse(response) response_data = response_obj['d'] # Display the response puts "TextKey Results:" puts JSON.pretty_generate response_data
Here is an example of the JSON string with the d wrapper removed:
Test Results: { "__type": "TextKeyCommon.TKStructures+TempAPIKeyReturn", "errorDescr": "", "apiKey": "6A648863-6818-4B41-AECE-34471D5D9DC1" }
NOTE: For more detais on the RUBY Library object and methods, you can take a look at the online documentation at http://textpower.github.io/RESTLibrary-ruby/.
Javascript
All of the TextKey
REST API calls are CORS compliant so they can be called via an Ajax request with no cross domain issues.In order to user the TextKey
REST API calls via javascript, you will need to setup the API payload using the appropriate parameters and the API key formatted as a JSON string and then make an Ajax POST request. The POST header does need to be setup as a JSON request (i.e. an application/json header) or you will not get a response.You will be returned a JSON string as the API call payload.
NOTE: Exposing your API key via any client side code is not recommended. If you choose to use the TextKey
API calls via a Javascript call, make sure to create a temporary API Key using the getTempAPIKey API call server side and then use that temporary key during its lifespan on any client side API calls.<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script> <script type="text/javascript"> // Build a class to handle the API call input payload function textkeyPayload(apiKey, minutesDuration) { this.apiKey = apiKey; this.minutesDuration = minutesDuration; this.toJsonString = function () { return JSON.stringify({ 'DataIn': this }); }; }; // Handle the API Request and response function textkeyAPIRequest(txtCommand, APIJSONData) { // Setup the API URL var urlAPI = 'http://www.textkey.com/REST/TKRest.asmx/'+txtCommand; // Make the API call via a JSON Ajax request $.ajax({ type: "POST", contentType: "application/json; charset=utf-8", url: urlAPI, data: APIJSONData, dataType: "json", success: function (APIResponse, textStatus) { document.write("textStatus: "+textStatus+ "<HR>"); document.write("API Response: "+JSON.stringify(APIResponse, null, 4) + "<HR>"); if (textStatus == 'success') { if (APIResponse.hasOwnProperty('d')) { APIPayload = APIResponse.d; } else { APIPayload = APIResponse; } document.write("API Payload: "+JSON.stringify(APIPayload, null, 4) + "<HR>"); if (APIPayload.errorDescr == "") { document.write("apiKey: " + APIPayload.apiKey); } else { document.write("Error: " + APIPayload.errorDescr); } } else { document.write("Error: " + textStatus); } }, error: function (jqXHR, textStatus, errorThrown) { document.write("Error: " + jqXHR.status); } }); } // Setup the API command var txtCommand = 'getTempAPIKey'; // Build the API payload var getTempAPIKey = new textkeyPayload("9021fa44-f1bc-4590-b975-42fee031e078", 2); // Make the API Call textkeyAPIRequest(txtCommand, getTempAPIKey.toJsonString()); </script>
SOAP Example
- Step 1 - Authentication Settings
- Step 2 - Call Parameters
- Step 3 - SOAP Request
- Step 4 - SOAP Response
- Step 5 - Output Results
Authentication Settings
A SOAP header is required on all SOAP API calls using the _Key variant and the header information is identical on all calls.
getTempAPIKey requires a SOAP header.
getTempAPIKey_Key does not require a SOAP header but uses the API Key in the body of the SOAP request.Authentication Settings using an API Key
API Key: 9021fa44-f1bc-4590-b975-42fee031e078
OR
Authentication Settings using an UserID/Password Combination
userId: 1ed93006208f0540e452e3a37d8299bc
Password: Password12345
Campaign:
Keyword:The WSDL document for the TextKey
SOAP interface is located at: https://secure.textkey.com/ws/textkey.asmx?wsdl.The address for the SOAP calls on the TextKey
interface is: https://secure.textkey.com/ws/textkey.asmx.The name space for the SOAP calls on the TextKey
interface is: https://secure.textkey.com/services/.Call Parameters
The parameters should look something like this:
apiKey: 9021fa44-f1bc-4590-b975-42fee031e078 minutesDuration: 2
SOAP Request
The SOAP request should look something like this:
SOAP Request using the API Key
OR
SOAP Request using the UserID/Password
SOAP Response
The SOAP response should look something like this:
SOAP Response with an valid payload
OR
SOAP Response with an error
Output Results
The final results will need to be extracted from the XML response payload should look something like this:
SOAP Response with a valid payload
stdClass Object ( [apiKey] => 45B2A49F-F70B-42E9-8AC4-0256C0CAAD04 [errorDescr] => )
apiKey: 45B2A49F-F70B-42E9-8AC4-0256C0CAAD04 errorDescr:
OR
SOAP Response with an error
stdClass Object ( [apiKey] => [errorDescr] => Invalid Login )
Error: Invalid Login.
SOAP Code Examples
PHP
The PHP Helper library contain a textkey class that makes calling TextKey
SOAP API functions simple. Just include the helper file textkey_soap.php in your PHP code, inititalize a textkey object using your credentials (i.e. either an API key or a UserID/Password), and then make the API call with the appropriate parameters. You will be returned an object with the API call payload.// Include the TextKey classes include_once("../textkey_soap.php"); // Setup the API call parameters $minutesDuration = 2; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Create a textkey object if ($apikey != "") { $tk = new textKey("", "", "", "", $apikey); } // Handle the operation $textkey_result = $tk->perform_GetTempAPI_Key($minutesDuration); // Show the textkey API payload object print_r($textkey_result); echo "<HR>"; // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; } echo $results;
CURL
From a command line, you can test the SOAP API calls using a CURL request:
The SOAP getTempAPIKey Request is stored in a file called getTempAPIKey.xml
<?xml version="1.0" encoding="UTF-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" > <soap:Body> <getTempAPIKey_Key xmlns="https://secure.textkey.com/services/"> <apiKey>9021fa44-f1bc-4590-b975-42fee031e078</apiKey> <minutesDuration>2</minutesDuration> </getTempAPIKey_Key> </soap:Body> </soap:Envelope>
CURL command using getTempAPIKey.xml
curl -H "Content-Type: text/xml; charset=utf-8" -H "SOAPAction:" -d @getTempAPIKey.xml -X POST https://secure.textkey.com/ws/textkey.asmx
XML Response from API getTempAPIKey Request
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Body> <getTempAPIKey_KeyResponse xmlns="https://secure.textkey.com/services/"> <getTempAPIKey_KeyResult> <apiKey>82F5D309-02CC-4231-9D45-25EE012E2805</apiKey> <errorDescr /> </getTempAPIKey_KeyResult> </getTempAPIKey_KeyResponse> </soap:Body> </soap:Envelope>
-
removeTempAPIKey
Description
The removeTempAPIKey API call is used to remove a temporary created API Key.
API Testing Page
To test the removeTempAPIKey API Call in a fully interactive environment, click here.
Input Parameters
Name Data Type Description Required apiKey String This is a unique key that is used to authenticate an API request. It should never be exposed. Yes minutesDuration Integer This parameter is ignored but still must still be passed in with an integer value. Yes
Output
Name Data Type Description apiKey String This value will be an empty string. errorDescr String If a error occurs, this is the error message. This will be blank if the call was successful.
REST Example
RESTful URL
The TextKey
Restful interface consists of the secure URL path followed by the appropriate CommandName.For instance:
https://secure.textkey.com/REST/TKRest.asmx/CommandName
The CommandName is the API call itself which in this case is removeTempAPIKey.
Here is what the complete URL for this API call would look like:
https://secure.textkey.com/REST/TKRest.asmx/removeTempAPIKey
All Restful calls must be made using the POST method and should be of the content type application/json.
Here is an example of what a request header should look like:
POST /REST/TKRest.asmx/removeTempAPIKey HTTP/1.1 Host: secure.textkey.com Accept: */* Content-Type:application/json Content-Length: 113
JSON Input Payload
All TextKey
Restful service commands take a JSON object as the input and return a JSON object as the resulting payload. Authentication is handled via an API key as one of the parameters in the JSON input.The JSON Input payload for the removeTempAPIKey API call should look something like this:
{ "DataIn": { "apiKey": "E6E22018-2D1B-4302-A12D-5660B0EE27BD", "minutesDuration": "" } }
JSON Output Payload
The JSON response should look something like this:
JSON Response with a valid payload
{ "d":{ "__type":"TextKeyCommon.TKStructures+TempAPIKeyReturn", "apiKey":"E6E22018-2D1B-4302-A12D-5660B0EE27BD", "errorDescr":"" } }
__type: TextKeyCommon.TKStructures+TempAPIKeyReturn apiKey: E6E22018-2D1B-4302-A12D-5660B0EE27BD errorDescr:
OR
JSON Response with an error
{ "d":{ "__type":"TextKeyCommon.TKStructures+TempAPIKeyReturn", "apiKey":"", "errorDescr":"Invalid Login" } }
Error: Invalid Login.
REST Code Examples
PHP
Example 1 - Using the TextKey
PHP Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKey object to handle all of the heavy lifting.You will be returned a PHP object and can reference all of the payload values directly from that object.
// Include the TextKey classes include_once("textkey_rest.php"); // Setup the API call parameters $tempapikey = "E4E334BA-0A8F-4DA0-9E2B-08F77B380E60"; $minutesDuration = 2; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Create a TK object $tk = new textKey($apikey); // Handle the operation $textkey_result = $tk->perform_RemoveTempAPIKey($tempapikey, $minutesDuration); // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } echo $results; } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; echo $results; }
Here is an example of the PHP object returned:
stdClass Object ( [__type] => TextKeyCommon.TKStructures+TempAPIKeyReturn [apiKey] => E4E334BA-0A8F-4DA0-9E2B-08F77B380E60 [errorDescr] => )
Example 2 - Using the REST API Call directly
In order to use the TextKey
REST API calls directly, you will need to setup the API payload using the appropriate parameters and the API key formatted as a JSON string and then make a CURL POST request.The POST header does need to be setup as a JSON request (i.e. an application/json header) or you will not get a response.
You will be returned a JSON string as the API call payload. That can be converted into a PHP object using the json_decode call.
// TextKey REST path define('TK_REST', 'https://secure.textkey.com/REST/TKRest.asmx/'); // Setup the API call parameters $tempapikey = "E4E334BA-0A8F-4DA0-9E2B-08F77B380E60"; $minutesDuration = 2; // Build the REST API URL $url = TK_REST . 'removeTempAPIKey'; // Setup data $postdata = json_encode( array('DataIn' => array( 'apiKey' => urlencode($tempapikey), 'minutesDuration' => urlencode($minutesDuration) ) ), JSON_PRETTY_PRINT); // Handle the API request via CURL $curl = curl_init($url); // Set the CURL params and make sure it is a JSON request curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); curl_setopt($curl, CURLOPT_POST, true); curl_setopt($curl, CURLOPT_POSTFIELDS, $postdata); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json')); curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0); // Wildcard certificate $response = curl_exec($curl); curl_close($curl); // Handle the payload $textkey_payload = json_decode($response); if ($textkey_payload->d) { $textkey_result = $textkey_payload->d; } else { $textkey_result = $textkey_payload; }; // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } echo $results; } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; echo $results; }
JAVA
Example - Using the TextKey
JAVA Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKeyRest object to handle all of the heavy lifting.You will be returned a JSON string.
package com.textkey.rest.examples; import org.json.JSONObject; import com.textkey.rest.TextKeyRest; public class TestRemoveTempAPIKey { public static void main(String[] args) { /* Setup */ String TK_API = "9021fa44-f1bc-4590-b975-42fee031e078"; /* Create the TextKey object */ TextKeyRest textkey = new TextKeyRest(TK_API, false); /* Setup the API call parameters */ Integer minutesDuration = 2; /* Make the REST API Call to get a Temp API Key */ String JSONpayloadGet = textkey.perform_GetTempAPI_Key(minutesDuration); /* Get the tempAPI Key and remove it */ try { JSONObject getAPI = new JSONObject(JSONpayloadGet); String tempAPI = getAPI.getJSONObject("d").getString("apiKey"); /* Make the REST API Call to remove the Temp API Key */ String JSONpayload = textkey.perform_RemoveTempAPIKey(tempAPI, minutesDuration); /* Display the API Results */ try { JSONObject results = new JSONObject(JSONpayload).getJSONObject("d"); System.out.println("Test Results: \n" + TextKeyRest.toPrettyFormat(results.toString())); } catch(Exception pe){ pe.printStackTrace(); } } catch(Exception pe){ pe.printStackTrace(); } } }
Here is an example of the JSON string with the d wrapper removed:
Test Results: { "__type": "TextKeyCommon.TKStructures+TempAPIKeyReturn", "errorDescr": "", "apiKey": "5DC7D7AB-4DBA-4804-9576-ACD42352638B" }
NOTE: For more detais on the JAVA Library object and methods, you can take a look at the online documentation at http://textpower.github.io/RESTLibrary-java/.
RUBY
Example - Using the TextKey
RUBY Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKeyRest object to handle all of the heavy lifting.You will be returned a JSON string.
NOTE: To install the textkey_rest gem you can run gem install textkey_rest from a command line. To build the testkey_rest gem locally, get the latest repository at github and follow the instructions.
require 'json' require 'textkey_rest' # Setup apiKey = "9021fa44-f1bc-4590-b975-42fee031e078" # Create the textkey object textkey = TextKeyRest.new(apiKey, false) # Setup the API parameters minutesDuration = 2 # Make the API Call to get an API Key response = textkey.perform_GetTempAPI_Key(minutesDuration) # If show flag is set show the return payload if response # Pull out the data from the response response_obj = JSON.parse(response) tempAPI = response_obj['d']['apiKey'] if response # Make the API Call to release the API Key response = textkey.perform_RemoveTempAPIKey(tempAPI, minutesDuration) # Pull out the data from the response response_obj = JSON.parse(response) response_data = response_obj['d'] end end # Display the response puts "TextKey Results:" puts JSON.pretty_generate response_data
Here is an example of the JSON string with the d wrapper removed:
Test Results: { "__type": "TextKeyCommon.TKStructures+TempAPIKeyReturn", "errorDescr": "", "apiKey": "5DC7D7AB-4DBA-4804-9576-ACD42352638B" }
NOTE: For more detais on the RUBY Library object and methods, you can take a look at the online documentation at http://textpower.github.io/RESTLibrary-ruby/.
Javascript
All of the TextKey
REST API calls are CORS compliant so they can be called via an Ajax request with no cross domain issues.In order to user the TextKey
REST API calls via javascript, you will need to setup the API payload using the appropriate parameters and the API key formatted as a JSON string and then make an Ajax POST request. The POST header does need to be setup as a JSON request (i.e. an application/json header) or you will not get a response.You will be returned a JSON string as the API call payload.
NOTE: Exposing your API key via any client side code is not recommended. If you choose to use the TextKey
API calls via a Javascript call, make sure to create a temporary API Key using the getTempAPIKey API call server side and then use that temporary key during its lifespan on any client side API calls.<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script> <script type="text/javascript"> // Build a class to handle the API call input payload function textkeyPayload(apiKey, minutesDuration) { this.apiKey = apiKey; this.minutesDuration = minutesDuration; this.toJsonString = function () { return JSON.stringify({ 'DataIn': this }); }; }; // Handle the API Request and response function textkeyAPIRequest(txtCommand, APIJSONData) { // Setup the API URL var urlAPI = 'http://www.textkey.com/REST/TKRest.asmx/'+txtCommand; // Make the API call via a JSON Ajax request $.ajax({ type: "POST", contentType: "application/json; charset=utf-8", url: urlAPI, data: APIJSONData, dataType: "json", success: function (APIResponse, textStatus) { document.write("textStatus: "+textStatus+ "<HR>"); document.write("API Response: "+JSON.stringify(APIResponse, null, 4) + "<HR>"); if (textStatus == 'success') { if (APIResponse.hasOwnProperty('d')) { APIPayload = APIResponse.d; } else { APIPayload = APIResponse; } document.write("API Payload: "+JSON.stringify(APIPayload, null, 4) + "<HR>"); if (APIPayload.errorDescr == "") { document.write("apiKey: " + APIPayload.apiKey); } else { document.write("Error: " + APIPayload.errorDescr); } } else { document.write("Error: " + textStatus); } }, error: function (jqXHR, textStatus, errorThrown) { document.write("Error: " + jqXHR.status); } }); } // Setup the API command var txtCommand = 'removeTempAPIKey'; // Build the API payload var removeTempAPIKey = new textkeyPayload("E6E22018-2D1B-4302-A12D-5660B0EE27BD", 2); // Make the API Call textkeyAPIRequest(txtCommand, removeTempAPIKey.toJsonString()); </script>
SOAP Example
- Step 1 - Authentication Settings
- Step 2 - Call Parameters
- Step 3 - SOAP Request
- Step 4 - SOAP Response
- Step 5 - Output Results
Authentication Settings
A SOAP header is required on all SOAP API calls using the _Key variant and the header information is identical on all calls.
removeTempAPIKey requires a SOAP header.
removeTempAPIKey_Key does not require a SOAP header but uses the API Key in the body of the SOAP request.Authentication Settings using an API Key
OR
Authentication Settings using an UserID/Password Combination
userId: 1ed93006208f0540e452e3a37d8299bc
Password: Password12345
Campaign:
Keyword:The WSDL document for the TextKey
SOAP interface is located at: https://secure.textkey.com/ws/textkey.asmx?wsdl.The address for the SOAP calls on the TextKey
interface is: https://secure.textkey.com/ws/textkey.asmx.The name space for the SOAP calls on the TextKey
interface is: https://secure.textkey.com/services/.Call Parameters
The parameters should look something like this:
apiKey: E6E22018-2D1B-4302-A12D-5660B0EE27BD minutesDuration: 2
SOAP Request
The SOAP request should look something like this:
SOAP Request using the API Key
OR
SOAP Request using the UserID/Password
SOAP Response
The SOAP response should look something like this:
SOAP Response with an valid payload
OR
SOAP Response with an error
Output Results
The final results will need to be extracted from the XML response payload should look something like this:
SOAP Response with a valid payload
stdClass Object ( [apiKey] => E6E22018-2D1B-4302-A12D-5660B0EE27BD [errorDescr] => )
apiKey: E6E22018-2D1B-4302-A12D-5660B0EE27BD errorDescr:
OR
SOAP Response with an error
stdClass Object ( [apiKey] => [errorDescr] => Invalid Login )
Error: Invalid Login.
SOAP Code Examples
PHP
The PHP Helper library contain a textkey class that makes calling TextKey
SOAP API functions simple. Just include the helper file textkey_soap.php in your PHP code, inititalize a textkey object using your credentials (i.e. either an API key or a UserID/Password), and then make the API call with the appropriate parameters. You will be returned an object with the API call payload.// Include the TextKey classes include_once("../textkey_soap.php"); // Setup the API call parameters $tempapikey = "E4E334BA-0A8F-4DA0-9E2B-08F77B380E60"; $minutesDuration = 2; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Create a textkey object if ($apikey != "") { $tk = new textKey("", "", "", "", $apikey); } // Handle the operation $textkey_result = $tk->perform_RemoveTempAPIKey($tempapikey, $minutesDuration); // Show the textkey API payload object print_r($textkey_result); echo "<HR>"; // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; } echo $results;
CURL
From a command line, you can test the SOAP API calls using a CURL request:
The SOAP removeTempAPIKey Request is stored in a file called removeTempAPIKey.xml
<?xml version="1.0" encoding="UTF-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" > <soap:Body> <removeTempAPIKey_Key xmlns="https://secure.textkey.com/services/"> <apiKey>E4E334BA-0A8F-4DA0-9E2B-08F77B380E60</apiKey> <minutesDuration>2</minutesDuration> </removeTempAPIKey_Key> </soap:Body> </soap:Envelope>
CURL command using removeTempAPIKey.xml
curl -H "Content-Type: text/xml; charset=utf-8" -H "SOAPAction:" -d @removeTempAPIKey.xml -X POST https://secure.textkey.com/ws/textkey.asmx
XML Response from API removeTempAPIKey Request
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Body> <removeTempAPIKey_KeyResponse xmlns="https://secure.textkey.com/services/"> <removeTempAPIKey_KeyResult> <apiKey>82F5D309-02CC-4231-9D45-25EE012E2805</apiKey> <errorDescr /> </removeTempAPIKey_KeyResult> </removeTempAPIKey_KeyResponse> </soap:Body> </soap:Envelope>
-
issueTextKeyFromUserId
Description
The issueTextKeyFromUserId API call is used to issue a TextKey using the TextPower registration database. This call takes a userID and returns a TextKey value that can be used with that users device (i.e. their specific cell phone) for secure authentication.
API Testing Page
To test the issueTextKeyFromUserId API Call in a fully interactive environment, click here.
Input Parameters
Name Data Type Description Required apiKey String This is a unique key that is used to authenticate an API request. It should never be exposed. With the _Key function userID String The user id that the end user has entered on the web site login page. This userID must be registered in the TextPower registration database. Yes IsHashed Boolean If the IsHashed parameter is false, TextPower will create the MD5 hash of the userID and use this hash to match the proper record in the TextPower registration database.
If the IsHashed parameter is true, TextPower will match the stored hash directly from the provided userID.Yes
Output
Name Data Type Description textKey String The TextKey that was issued. status Boolean True if a valid TextKey issued. validationCode String A validation code that must be passed to the subsequent call to one of the validateTextKey functions. mode Integer The TextKey validation method to be used on this TextKey.
Option Value TextKeyOnly 0 PinCodeOnly 1 TextKeyPlusPin 2 Anything 3 receiveMode Integer The ReceiveMode to be used to validate the incoming code.
Option Value AnyCode 0 SpecificCodeDisplay 1 SpecificCodeNoDisplay 2 RandomCode 3 UseDefault 4 useLink Boolean True if the TextKey element contains a link for retrieving a code.
False if the textKey element contains an actual code.cellNumberProxy String A non-repeating proxy string for the Cell Number that the TextKey belongs to. errorDescr String If a error occurs, this is the error message. This will be blank if the call was successful.
REST Example
RESTful URL
The TextKey
Restful interface consists of the secure URL path followed by the appropriate CommandName.For instance:
https://secure.textkey.com/REST/TKRest.asmx/CommandName
The CommandName is the API call itself which in this case is issueTextKeyFromUserId.
Here is what the complete URL for this API call would look like:
https://secure.textkey.com/REST/TKRest.asmx/issueTextKeyFromUserId
All Restful calls must be made using the POST method and should be of the content type application/json.
Here is an example of what a request header should look like:
POST /REST/TKRest.asmx/issueTextKeyFromUserId HTTP/1.1 Host: secure.textkey.com Accept: */* Content-Type:application/json Content-Length: 115
JSON Input Payload
All TextKey
Restful service commands take a JSON object as the input and return a JSON object as the resulting payload. Authentication is handled via an API key as one of the parameters in the JSON input.The JSON Input payload for the issueTextKeyFromUserId API call should look something like this:
{ "DataIn": { "apiKey": "9021fa44-f1bc-4590-b975-42fee031e078", "userID": "Stan", "isHashed": "true" } }
JSON Output Payload
The JSON response should look something like this:
JSON Response with a valid payload
{ "d":{ "__type":"TextKeyCommon.TKStructures+IssueTextKeyReturn", "textKey":"3809802", "status":true, "validationCode":"2H46D", "mode":0, "receiveMode":0, "useLink":false, "textToCode":"", "cellNumberProxy":"", "errorDescr":"" } }
__type: TextKeyCommon.TKStructures+IssueTextKeyReturn textKey: 3809802 status: 1 validationCode: 2H46D mode: 0 receiveMode: 0 useLink: textToCode: cellNumberProxy: errorDescr:
OR
JSON Response with an error
{ "d":{ "__type":"TextKeyCommon.TKStructures+IssueTextKeyReturn", "textKey":"", "status":false, "validationCode":"0", "mode":0, "receiveMode":0, "useLink":false, "textToCode":"", "cellNumberProxy":"", "errorDescr":"Invalid Login" } }
Error: Invalid Login.
REST Code Examples
PHP
Example 1 - Using the TextKey
PHP Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKey object to handle all of the heavy lifting.You will be returned a PHP object and can reference all of the payload values directly from that object.
// Include the TextKey classes include_once("textkey_rest.php"); // Setup the API call parameters $testuserid ="Stan"; $isHashed = TRUE; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Create a TK object $tk = new textKey($apikey); // Handle the operation $textkey_result = $tk->perform_IssueTextKeyFromUserId($testuserid, $isHashed); // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } echo $results; } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; echo $results; }
Here is an example of the PHP object returned:
stdClass Object ( [__type] => TextKeyCommon.TKStructures+IssueTextKeyReturn [textKey] => 3437467 [status] => 1 [validationCode] => G145 [mode] => 0 [receiveMode] => 0 [useLink] => [textToCode] => [cellNumberProxy] => [errorDescr] => )
Example 2 - Using the REST API Call directly
In order to use the TextKey
REST API calls directly, you will need to setup the API payload using the appropriate parameters and the API key formatted as a JSON string and then make a CURL POST request.The POST header does need to be setup as a JSON request (i.e. an application/json header) or you will not get a response.
You will be returned a JSON string as the API call payload. That can be converted into a PHP object using the json_decode call.
// TextKey REST path define('TK_REST', 'https://secure.textkey.com/REST/TKRest.asmx/'); // Setup the API call parameters $testuserid ="Stan"; $isHashed = TRUE; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Build the REST API URL $url = TK_REST . 'issueTextKeyFromUserId'; // Setup data $postdata = json_encode( array('DataIn' => array( 'apiKey' => urlencode($apikey), 'userID' => urlencode($testuserid), 'isHashed' => urlencode($isHashed?"true":"false"), ) ), JSON_PRETTY_PRINT); // Handle the API request via CURL $curl = curl_init($url); // Set the CURL params and make sure it is a JSON request curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); curl_setopt($curl, CURLOPT_POST, true); curl_setopt($curl, CURLOPT_POSTFIELDS, $postdata); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json')); curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0); // Wildcard certificate $response = curl_exec($curl); curl_close($curl); // Handle the payload $textkey_payload = json_decode($response); if ($textkey_payload->d) { $textkey_result = $textkey_payload->d; } else { $textkey_result = $textkey_payload; }; // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } echo $results; } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; echo $results; }
JAVA
Example - Using the TextKey
JAVA Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKeyRest object to handle all of the heavy lifting.You will be returned a JSON string.
package com.textkey.rest.examples; import org.json.JSONObject; import com.textkey.rest.TextKeyRest; public class TestIssueTextKeyFromUserId { public static void main(String[] args) { /* Setup */ String TK_API = "9021fa44-f1bc-4590-b975-42fee031e078"; /* Create the TextKey object */ TextKeyRest textkey = new TextKeyRest(TK_API, false); /* Setup the API call parameters */ String UserID = "Stan"; String isHashed = "TRUE"; /* Make the REST API Call */ String JSONpayload = textkey.perform_IssueTextKeyFromUserId(UserID, isHashed); /* Display the API Results */ try { JSONObject results = new JSONObject(JSONpayload).getJSONObject("d"); System.out.println("Test Results: \n" + TextKeyRest.toPrettyFormat(results.toString())); } catch(Exception pe){ pe.printStackTrace(); } } }
Here is an example of the JSON string with the d wrapper removed:
Test Results: { "textToCode": "", "__type": "TextKeyCommon.TKStructures+IssueTextKeyReturn", "receiveMode": 0, "validationCode": "1F752", "useLink": false, "status": true, "errorDescr": "", "cellNumberProxy": "", "textKey": "6610943", "mode": 0 }
NOTE: For more detais on the JAVA Library object and methods, you can take a look at the online documentation at http://textpower.github.io/RESTLibrary-java/.
RUBY
Example - Using the TextKey
RUBY Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKeyRest object to handle all of the heavy lifting.You will be returned a JSON string.
NOTE: To install the textkey_rest gem you can run gem install textkey_rest from a command line. To build the testkey_rest gem locally, get the latest repository at github and follow the instructions.
require 'json' require 'textkey_rest' # Setup apiKey = "9021fa44-f1bc-4590-b975-42fee031e078" # Create the textkey object textkey = TextKeyRest.new(apiKey, false) # Setup the API parameters userID = "Stan" isHashed = "TRUE" # Make the API Call response = textkey.perform_IssueTextKeyFromUserId(userID, isHashed) # Pull out the data from the response response_obj = JSON.parse(response) response_data = response_obj['d'] # Display the response puts "TextKey Results:" puts JSON.pretty_generate response_data
Here is an example of the JSON string with the d wrapper removed:
Test Results: { "textToCode": "", "__type": "TextKeyCommon.TKStructures+IssueTextKeyReturn", "receiveMode": 0, "validationCode": "1F752", "useLink": false, "status": true, "errorDescr": "", "cellNumberProxy": "", "textKey": "6610943", "mode": 0 }
NOTE: For more detais on the RUBY Library object and methods, you can take a look at the online documentation at http://textpower.github.io/RESTLibrary-ruby/.
Javascript
All of the TextKey
REST API calls are CORS compliant so they can be called via an Ajax request with no cross domain issues.In order to user the TextKey
REST API calls via javascript, you will need to setup the API payload using the appropriate parameters and the API key formatted as a JSON string and then make an Ajax POST request. The POST header does need to be setup as a JSON request (i.e. an application/json header) or you will not get a response.You will be returned a JSON string as the API call payload.
NOTE: Exposing your API key via any client side code is not recommended. If you choose to use the TextKey
API calls via a Javascript call, make sure to create a temporary API Key using the getTempAPIKey API call server side and then use that temporary key during its lifespan on any client side API calls.<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script> <script type="text/javascript"> // Build a class to handle the API call input payload function textkeyPayload(apiKey, userID, isHashed) { this.apiKey = apiKey; this.userID = userID; this.isHashed = isHashed; this.toJsonString = function () { return JSON.stringify({ 'DataIn': this }); }; }; // Handle the API Request and response function textkeyAPIRequest(txtCommand, APIJSONData) { // Setup the API URL var urlAPI = 'http://www.textkey.com/REST/TKRest.asmx/'+txtCommand; // Make the API call via a JSON Ajax request $.ajax({ type: "POST", contentType: "application/json; charset=utf-8", url: urlAPI, data: APIJSONData, dataType: "json", success: function (APIResponse, textStatus) { document.write("textStatus: "+textStatus+ "<HR>"); document.write("API Response: "+JSON.stringify(APIResponse, null, 4) + "<HR>"); if (textStatus == 'success') { if (APIResponse.hasOwnProperty('d')) { APIPayload = APIResponse.d; } else { APIPayload = APIResponse; } document.write("API Payload: "+JSON.stringify(APIPayload, null, 4) + "<HR>"); if (APIPayload.errorDescr == "") { document.write("textKey: " + APIPayload.textKey); } else { document.write("Error: " + APIPayload.errorDescr); } } else { document.write("Error: " + textStatus); } }, error: function (jqXHR, textStatus, errorThrown) { document.write("Error: " + jqXHR.status); } }); } // Setup the API command var txtCommand = 'issueTextKeyFromUserId'; // Build the API payload var issueTextKeyFromUserId = new textkeyPayload("9021fa44-f1bc-4590-b975-42fee031e078", "Stan", true); // Make the API Call textkeyAPIRequest(txtCommand, issueTextKeyFromUserId.toJsonString()); </script>
SOAP Example
- Step 1 - Authentication Settings
- Step 2 - Call Parameters
- Step 3 - SOAP Request
- Step 4 - SOAP Response
- Step 5 - Output Results
Authentication Settings
A SOAP header is required on all SOAP API calls using the _Key variant and the header information is identical on all calls.
issueTextKeyFromUserId requires a SOAP header.
issueTextKeyFromUserId_Key does not require a SOAP header but uses the API Key in the body of the SOAP request.Authentication Settings using an API Key
API Key: 9021fa44-f1bc-4590-b975-42fee031e078
OR
Authentication Settings using an UserID/Password Combination
userId: 1ed93006208f0540e452e3a37d8299bc
Password: Password12345
Campaign:
Keyword:The WSDL document for the TextKey
SOAP interface is located at: https://secure.textkey.com/ws/textkey.asmx?wsdl.The address for the SOAP calls on the TextKey
interface is: https://secure.textkey.com/ws/textkey.asmx.The name space for the SOAP calls on the TextKey
interface is: https://secure.textkey.com/services/.Call Parameters
The parameters should look something like this:
apiKey: 9021fa44-f1bc-4590-b975-42fee031e078 userID: Stan isHashed: 1
SOAP Request
The SOAP request should look something like this:
SOAP Request using the API Key
OR
SOAP Request using the UserID/Password
SOAP Response
The SOAP response should look something like this:
SOAP Response with an valid payload
OR
SOAP Response with an error
Output Results
The final results will need to be extracted from the XML response payload should look something like this:
SOAP Response with a valid payload
stdClass Object ( [textKey] => 4982315 [status] => 1 [validationCode] => 1A557 [mode] => TextKeyOnly [receiveMode] => AnyCode [useLink] => [textToCode] => [cellNumberProxy] => [errorDescr] => )
textKey: 4982315 status: 1 validationCode: 1A557 mode: TextKeyOnly receiveMode: AnyCode useLink: textToCode: cellNumberProxy: errorDescr:
OR
SOAP Response with an error
stdClass Object ( [textKey] => [status] => [validationCode] => 0 [mode] => TextKeyOnly [receiveMode] => AnyCode [useLink] => [textToCode] => [cellNumberProxy] => [errorDescr] => Invalid Login )
Error: Invalid Login.
SOAP Code Examples
PHP
The PHP Helper library contain a textkey class that makes calling TextKey
SOAP API functions simple. Just include the helper file textkey_soap.php in your PHP code, inititalize a textkey object using your credentials (i.e. either an API key or a UserID/Password), and then make the API call with the appropriate parameters. You will be returned an object with the API call payload.// Include the TextKey classes include_once("../textkey_soap.php"); // Setup the API call parameters $testuserid ="Stan"; $isHashed = TRUE; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Create a textkey object if ($apikey != "") { $tk = new textKey("", "", "", "", $apikey); } // Handle the operation $textkey_result = $tk->perform_IssueTextKeyFromUserId($testuserid, $isHashed); // Show the textkey API payload object print_r($textkey_result); echo "<HR>"; // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; } echo $results;
CURL
From a command line, you can test the SOAP API calls using a CURL request:
The SOAP issueTextKeyFromUserId Request is stored in a file called issueTextKeyFromUserId.xml
<?xml version="1.0" encoding="UTF-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" > <soap:Body> <issueTextKeyFromUserId_Key xmlns="https://secure.textkey.com/services/"> <apiKey>9021fa44-f1bc-4590-b975-42fee031e078</apiKey> <userID>Stan</userID> <isHashed>true</isHashed> </issueTextKeyFromUserId_Key> </soap:Body> </soap:Envelope>
CURL command using issueTextKeyFromUserId.xml
curl -H "Content-Type: text/xml; charset=utf-8" -H "SOAPAction:" -d @issueTextKeyFromUserId.xml -X POST https://secure.textkey.com/ws/textkey.asmx
XML Response from API issueTextKeyFromUserId Request
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Body> <issueTextKeyFromUserId_KeyResponse xmlns="https://secure.textkey.com/services/"> <issueTextKeyFromUserId_KeyResult> <textKey>3976837</textKey> <status>true</status> <validationCode>C0CE</validationCode> <mode>TextKeyOnly</mode> <receiveMode>AnyCode</receiveMode> <useLink>false</useLink> <textToCode /> <cellNumberProxy /> <errorDescr /> </issueTextKeyFromUserId_KeyResult> </issueTextKeyFromUserId_KeyResponse> </soap:Body> </soap:Envelope>
-
issueTextKeyFromCellNumber
Description
The issueTextKeyFromCellNumber API call is used to issue a TextKey using the TextPower registration database. This call takes a Cell Number and returns a TextKey value that can be used with that users device (i.e. their specific cell phone) for secure authentication.
API Testing Page
To test the issueTextKeyFromCellNumber API Call in a fully interactive environment, click here.
Input Parameters
Name Data Type Description Required apiKey String This is a unique key that is used to authenticate an API request. It should never be exposed. With the _Key function cellNumber String The cell number or the cell number proxy to be used. Yes
Output
Name Data Type Description textKey String The TextKey that was issued. status Boolean True if a valid TextKey issued. validationCode String A validation code that must be passed to the subsequent call to one of the validateTextKey functions. mode Integer The TextKey validation method to be used on this TextKey.
Option Value TextKeyOnly 0 PinCodeOnly 1 TextKeyPlusPin 2 Anything 3 receiveMode Integer The ReceiveMode to be used to validate the incoming code.
Option Value AnyCode 0 SpecificCodeDisplay 1 SpecificCodeNoDisplay 2 RandomCode 3 UseDefault 4 useLink Boolean True if the TextKey element contains a link for retrieving a code.
False if the textKey element contains an actual code.cellNumberProxy String A non-repeating proxy string for the Cell Number that the TextKey belongs to. errorDescr String If a error occurs, this is the error message. This will be blank if the call was successful.
REST Example
RESTful URL
The TextKey
Restful interface consists of the secure URL path followed by the appropriate CommandName.For instance:
https://secure.textkey.com/REST/TKRest.asmx/CommandName
The CommandName is the API call itself which in this case is issueTextKeyFromCellNumber.
Here is what the complete URL for this API call would look like:
https://secure.textkey.com/REST/TKRest.asmx/issueTextKeyFromCellNumber
All Restful calls must be made using the POST method and should be of the content type application/json.
Here is an example of what a request header should look like:
POST /REST/TKRest.asmx/issueTextKeyFromCellNumber HTTP/1.1 Host: secure.textkey.com Accept: */* Content-Type:application/json Content-Length: 118
JSON Input Payload
All TextKey
Restful service commands take a JSON object as the input and return a JSON object as the resulting payload. Authentication is handled via an API key as one of the parameters in the JSON input.The JSON Input payload for the issueTextKeyFromCellNumber API call should look something like this:
{ "DataIn": { "apiKey": "9021fa44-f1bc-4590-b975-42fee031e078", "cellNumber": "8181231234" } }
JSON Output Payload
The JSON response should look something like this:
JSON Response with a valid payload
{ "d":{ "__type":"TextKeyCommon.TKStructures+IssueTextKeyReturn", "textKey":"3809802", "status":true, "validationCode":"2H46D", "mode":0, "receiveMode":0, "useLink":false, "textToCode":"", "cellNumberProxy":"", "errorDescr":"" } }
__type: TextKeyCommon.TKStructures+IssueTextKeyReturn textKey: 3809802 status: 1 validationCode: 2H46D mode: 0 receiveMode: 0 useLink: textToCode: cellNumberProxy: errorDescr:
OR
JSON Response with an error
{ "d":{ "__type":"TextKeyCommon.TKStructures+IssueTextKeyReturn", "textKey":"", "status":false, "validationCode":"0", "mode":0, "receiveMode":0, "useLink":false, "textToCode":"", "cellNumberProxy":"", "errorDescr":"Invalid Login" } }
Error: Invalid Login.
REST Code Examples
PHP
Example 1 - Using the TextKey
PHP Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKey object to handle all of the heavy lifting.You will be returned a PHP object and can reference all of the payload values directly from that object.
// Include the TextKey classes include_once("textkey_rest.php"); // Setup the API call parameters $RegCellNumber = "8181231234"; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Create a TK object $tk = new textKey($apikey); // Handle the operation $textkey_result = $tk->perform_IssueTextKeyFromCellNumber($RegCellNumber); // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } echo $results; } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; echo $results; }
Here is an example of the PHP object returned:
stdClass Object ( [__type] => TextKeyCommon.TKStructures+IssueTextKeyReturn [textKey] => 3493241 [status] => 1 [validationCode] => 270D4 [mode] => 0 [receiveMode] => 0 [useLink] => [textToCode] => [cellNumberProxy] => [errorDescr] => )
Example 2 - Using the REST API Call directly
In order to use the TextKey
REST API calls directly, you will need to setup the API payload using the appropriate parameters and the API key formatted as a JSON string and then make a CURL POST request.The POST header does need to be setup as a JSON request (i.e. an application/json header) or you will not get a response.
You will be returned a JSON string as the API call payload. That can be converted into a PHP object using the json_decode call.
// TextKey REST path define('TK_REST', 'https://secure.textkey.com/REST/TKRest.asmx/'); // Setup the API call parameters $CellNumber = "8181231234"; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Build the REST API URL $url = TK_REST . 'issueTextKeyFromCellNumber'; // Setup data $postdata = json_encode( array('DataIn' => array( 'apiKey' => urlencode($apikey), 'cellNumber' => urlencode($CellNumber) ) ), JSON_PRETTY_PRINT); // Handle the API request via CURL $curl = curl_init($url); // Set the CURL params and make sure it is a JSON request curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); curl_setopt($curl, CURLOPT_POST, true); curl_setopt($curl, CURLOPT_POSTFIELDS, $postdata); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json')); curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0); // Wildcard certificate $response = curl_exec($curl); curl_close($curl); // Handle the payload $textkey_payload = json_decode($response); if ($textkey_payload->d) { $textkey_result = $textkey_payload->d; } else { $textkey_result = $textkey_payload; }; // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } echo $results; } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; echo $results; }
JAVA
Example - Using the TextKey
JAVA Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKeyRest object to handle all of the heavy lifting.You will be returned a JSON string.
package com.textkey.rest.examples; import org.json.JSONObject; import com.textkey.rest.TextKeyRest; public class TestIssueTextKeyFromCellNumber { public static void main(String[] args) { /* Setup */ String TK_API = "9021fa44-f1bc-4590-b975-42fee031e078"; /* Create the TextKey object */ TextKeyRest textkey = new TextKeyRest(TK_API, false); /* Setup the API call parameters */ String CellNumber = "8181231234"; /* Make the REST API Call */ String JSONpayload = textkey.perform_IssueTextKeyFromCellNumber(CellNumber); /* Display the API Results */ try { JSONObject results = new JSONObject(JSONpayload).getJSONObject("d"); System.out.println("Test Results: \n" + TextKeyRest.toPrettyFormat(results.toString())); } catch(Exception pe){ pe.printStackTrace(); } } }
Here is an example of the JSON string with the d wrapper removed:
Test Results: { "textToCode": "", "__type": "TextKeyCommon.TKStructures+IssueTextKeyReturn", "receiveMode": 0, "validationCode": "3A3G8", "useLink": false, "status": true, "errorDescr": "", "cellNumberProxy": "", "textKey": "0531261", "mode": 0 }
NOTE: For more detais on the JAVA Library object and methods, you can take a look at the online documentation at http://textpower.github.io/RESTLibrary-java/.
RUBY
Example - Using the TextKey
RUBY Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKeyRest object to handle all of the heavy lifting.You will be returned a JSON string.
NOTE: To install the textkey_rest gem you can run gem install textkey_rest from a command line. To build the testkey_rest gem locally, get the latest repository at github and follow the instructions.
require 'json' require 'textkey_rest' # Setup apiKey = "9021fa44-f1bc-4590-b975-42fee031e078" # Create the textkey object textkey = TextKeyRest.new(apiKey, false) # Setup the API parameters cellNumber = "8181231234" # Make the API Call response = textkey.perform_IssueTextKeyFromCellNumber(cellNumber) # Pull out the data from the response response_obj = JSON.parse(response) response_data = response_obj['d'] # Display the response puts "TextKey Results:" puts JSON.pretty_generate response_data
Here is an example of the JSON string with the d wrapper removed:
Test Results: { "textToCode": "", "__type": "TextKeyCommon.TKStructures+IssueTextKeyReturn", "receiveMode": 0, "validationCode": "3A3G8", "useLink": false, "status": true, "errorDescr": "", "cellNumberProxy": "", "textKey": "0531261", "mode": 0 }
NOTE: For more detais on the RUBY Library object and methods, you can take a look at the online documentation at http://textpower.github.io/RESTLibrary-ruby/.
Javascript
All of the TextKey
REST API calls are CORS compliant so they can be called via an Ajax request with no cross domain issues.In order to user the TextKey
REST API calls via javascript, you will need to setup the API payload using the appropriate parameters and the API key formatted as a JSON string and then make an Ajax POST request. The POST header does need to be setup as a JSON request (i.e. an application/json header) or you will not get a response.You will be returned a JSON string as the API call payload.
NOTE: Exposing your API key via any client side code is not recommended. If you choose to use the TextKey
API calls via a Javascript call, make sure to create a temporary API Key using the getTempAPIKey API call server side and then use that temporary key during its lifespan on any client side API calls.<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script> <script type="text/javascript"> // Build a class to handle the API call input payload function textkeyPayload(apiKey, cellNumber) { this.apiKey = apiKey; this.cellNumber = cellNumber; this.toJsonString = function () { return JSON.stringify({ 'DataIn': this }); }; }; // Handle the API Request and response function textkeyAPIRequest(txtCommand, APIJSONData) { // Setup the API URL var urlAPI = 'http://www.textkey.com/REST/TKRest.asmx/'+txtCommand; // Make the API call via a JSON Ajax request $.ajax({ type: "POST", contentType: "application/json; charset=utf-8", url: urlAPI, data: APIJSONData, dataType: "json", success: function (APIResponse, textStatus) { document.write("textStatus: "+textStatus+ "<HR>"); document.write("API Response: "+JSON.stringify(APIResponse, null, 4) + "<HR>"); if (textStatus == 'success') { if (APIResponse.hasOwnProperty('d')) { APIPayload = APIResponse.d; } else { APIPayload = APIResponse; } document.write("API Payload: "+JSON.stringify(APIPayload, null, 4) + "<HR>"); if (APIPayload.errorDescr == "") { document.write("textKey: " + APIPayload.textKey); } else { document.write("Error: " + APIPayload.errorDescr); } } else { document.write("Error: " + textStatus); } }, error: function (jqXHR, textStatus, errorThrown) { document.write("Error: " + jqXHR.status); } }); } // Setup the API command var txtCommand = 'issueTextKeyFromCellNumber'; // Build the API payload var issueTextKeyFromCellNumber = new textkeyPayload("9021fa44-f1bc-4590-b975-42fee031e078", "8181231234"); // Make the API Call textkeyAPIRequest(txtCommand, issueTextKeyFromCellNumber.toJsonString()); </script>
SOAP Example
- Step 1 - Authentication Settings
- Step 2 - Call Parameters
- Step 3 - SOAP Request
- Step 4 - SOAP Response
- Step 5 - Output Results
Authentication Settings
A SOAP header is required on all SOAP API calls using the _Key variant and the header information is identical on all calls.
issueTextKeyFromCellNumber requires a SOAP header.
issueTextKeyFromCellNumber_Key does not require a SOAP header but uses the API Key in the body of the SOAP request.Authentication Settings using an API Key
API Key: 9021fa44-f1bc-4590-b975-42fee031e078
OR
Authentication Settings using an UserID/Password Combination
userId: 1ed93006208f0540e452e3a37d8299bc
Password: Password12345
Campaign:
Keyword:The WSDL document for the TextKey
SOAP interface is located at: https://secure.textkey.com/ws/textkey.asmx?wsdl.The address for the SOAP calls on the TextKey
interface is: https://secure.textkey.com/ws/textkey.asmx.The name space for the SOAP calls on the TextKey
interface is: https://secure.textkey.com/services/.Call Parameters
The parameters should look something like this:
apiKey: 9021fa44-f1bc-4590-b975-42fee031e078 cellNumber: 8181231234
SOAP Request
The SOAP request should look something like this:
SOAP Request using the API Key
OR
SOAP Request using the UserID/Password
SOAP Response
The SOAP response should look something like this:
SOAP Response with an valid payload
OR
SOAP Response with an error
Output Results
The final results will need to be extracted from the XML response payload should look something like this:
SOAP Response with a valid payload
stdClass Object ( [textKey] => 1849791 [status] => 1 [validationCode] => 41F13 [mode] => TextKeyOnly [receiveMode] => AnyCode [useLink] => [textToCode] => [cellNumberProxy] => [errorDescr] => )
textKey: 1849791 status: 1 validationCode: 41F13 mode: TextKeyOnly receiveMode: AnyCode useLink: textToCode: cellNumberProxy: errorDescr:
OR
SOAP Response with an error
stdClass Object ( [textKey] => [status] => [validationCode] => 0 [mode] => TextKeyOnly [receiveMode] => AnyCode [useLink] => [textToCode] => [cellNumberProxy] => [errorDescr] => Invalid Login )
Error: Invalid Login.
SOAP Code Examples
PHP
The PHP Helper library contain a textkey class that makes calling TextKey
SOAP API functions simple. Just include the helper file textkey_soap.php in your PHP code, inititalize a textkey object using your credentials (i.e. either an API key or a UserID/Password), and then make the API call with the appropriate parameters. You will be returned an object with the API call payload.// Include the TextKey classes include_once("../textkey_soap.php"); // Setup the API call parameters $RegCellNumber = "8181231234"; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Create a textkey object if ($apikey != "") { $tk = new textKey("", "", "", "", $apikey); } // Handle the operation $textkey_result = $tk->perform_IssueTextKeyFromCellNumber($RegCellNumber); // Show the textkey API payload object print_r($textkey_result); echo "<HR>"; // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; } echo $results;
CURL
From a command line, you can test the SOAP API calls using a CURL request:
The SOAP issueTextKeyFromCellNumber Request is stored in a file called issueTextKeyFromCellNumber.xml
<?xml version="1.0" encoding="UTF-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" > <soap:Body> <issueTextKeyFromCellNumber_Key xmlns="https://secure.textkey.com/services/"> <apiKey>9021fa44-f1bc-4590-b975-42fee031e078</apiKey> <cellNumber>8181231234</cellNumber> </issueTextKeyFromCellNumber_Key> </soap:Body> </soap:Envelope>
CURL command using issueTextKeyFromCellNumber.xml
curl -H "Content-Type: text/xml; charset=utf-8" -H "SOAPAction:" -d @issueTextKeyFromCellNumber.xml -X POST https://secure.textkey.com/ws/textkey.asmx
XML Response from API issueTextKeyFromCellNumber Request
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Body> <issueTextKeyFromCellNumber_KeyResponse xmlns="https://secure.textkey.com/services/"> <issueTextKeyFromCellNumber_KeyResult> <textKey>0255595</textKey> <status>true</status> <validationCode>2C44D</validationCode> <mode>TextKeyOnly</mode> <receiveMode>AnyCode</receiveMode> <useLink>false</useLink> <textToCode /> <cellNumberProxy /> <errorDescr /> </issueTextKeyFromCellNumber_KeyResult> </issueTextKeyFromCellNumber_KeyResponse> </soap:Body> </soap:Envelope>
-
pollForIncomingTextKey
Description
The pollForIncomingTextKey API call looks for an incoming TextKey. Polling for an incoming TextKey should happen no more than once every 5 seconds and for a total maximum interval of about 90 seconds.
API Testing Page
To test the pollForIncomingTextKey API Call in a fully interactive environment, click here.
Input Parameters
Name Data Type Description Required apiKey String This is a unique key that is used to authenticate an API request. It should never be exposed. With the _Key function textKey String The TextKey to look for. If you are using a textKey option that does not utilize the textKey itself, send a zero length string. Yes
Output
Name Data Type Description activityDetected Boolean An input has been received. You may proceed to validate if this is set to true. timeExpired Boolean True if the TextKey being checked on has expired. If true then no need to continue polling. errorDescr String If a error occurs, this is the error message. This will be blank if the call was successful.
REST Example
RESTful URL
The TextKey
Restful interface consists of the secure URL path followed by the appropriate CommandName.For instance:
https://secure.textkey.com/REST/TKRest.asmx/CommandName
The CommandName is the API call itself which in this case is pollForIncomingTextKey.
Here is what the complete URL for this API call would look like:
https://secure.textkey.com/REST/TKRest.asmx/pollForIncomingTextKey
All Restful calls must be made using the POST method and should be of the content type application/json.
Here is an example of what a request header should look like:
POST /REST/TKRest.asmx/pollForIncomingTextKey HTTP/1.1 Host: secure.textkey.com Accept: */* Content-Type:application/json Content-Length: 112
JSON Input Payload
All TextKey
Restful service commands take a JSON object as the input and return a JSON object as the resulting payload. Authentication is handled via an API key as one of the parameters in the JSON input.The JSON Input payload for the pollForIncomingTextKey API call should look something like this:
{ "DataIn": { "apiKey": "9021fa44-f1bc-4590-b975-42fee031e078", "textKey": "5868199" } }
JSON Output Payload
The JSON response should look something like this:
JSON Response with a valid payload
{ "d":{ "__type":"TextKeyCommon.TKStructures+PolledTextKey", "ActivityDetected":false, "TimeExpired":true, "errorDescr":"" } }
__type: TextKeyCommon.TKStructures+PolledTextKey ActivityDetected: TimeExpired: 1 errorDescr:
OR
JSON Response with an error
{ "d":{ "__type":"TextKeyCommon.TKStructures+PolledTextKey", "ActivityDetected":false, "TimeExpired":true, "errorDescr":"Invalid Login" } }
Error: Invalid Login.
REST Code Examples
PHP
Example 1 - Using the TextKey
PHP Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKey object to handle all of the heavy lifting.You will be returned a PHP object and can reference all of the payload values directly from that object.
// Include the TextKey classes include_once("textkey_rest.php"); // Setup the API call parameters $textkey = "5868199"; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Create a TK object $tk = new textKey($apikey); // Handle the operation $textkey_result = $tk->perform_PollForIncomingTextKey($textkey); // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } echo $results; } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; echo $results; }
Here is an example of the PHP object returned:
stdClass Object ( [__type] => TextKeyCommon.TKStructures+PolledTextKey [ActivityDetected] => 1 [TimeExpired] => 1 [errorDescr] => )
Example 2 - Using the REST API Call directly
In order to use the TextKey
REST API calls directly, you will need to setup the API payload using the appropriate parameters and the API key formatted as a JSON string and then make a CURL POST request.The POST header does need to be setup as a JSON request (i.e. an application/json header) or you will not get a response.
You will be returned a JSON string as the API call payload. That can be converted into a PHP object using the json_decode call.
// TextKey REST path define('TK_REST', 'https://secure.textkey.com/REST/TKRest.asmx/'); // Setup the API call parameters $textkey = "5868199"; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Build the REST API URL $url = TK_REST . 'pollForIncomingTextKey'; // Setup data $postdata = json_encode( array('DataIn' => array( 'apiKey' => urlencode($apikey), 'textKey' => urlencode($textkey) ) ), JSON_PRETTY_PRINT); // Handle the API request via CURL $curl = curl_init($url); // Set the CURL params and make sure it is a JSON request curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); curl_setopt($curl, CURLOPT_POST, true); curl_setopt($curl, CURLOPT_POSTFIELDS, $postdata); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json')); curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0); // Wildcard certificate $response = curl_exec($curl); curl_close($curl); // Handle the payload $textkey_payload = json_decode($response); if ($textkey_payload->d) { $textkey_result = $textkey_payload->d; } else { $textkey_result = $textkey_payload; }; // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } echo $results; } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; echo $results; }
JAVA
Example - Using the TextKey
JAVA Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKeyRest object to handle all of the heavy lifting.You will be returned a JSON string.
package com.textkey.rest.examples; import org.json.JSONObject; import com.textkey.rest.TextKeyRest; public class TestPollForIncomingTextKey { public static void main(String[] args) { /* Setup */ String TK_API = "9021fa44-f1bc-4590-b975-42fee031e078"; /* Create the TextKey object */ TextKeyRest textkey = new TextKeyRest(TK_API, false); /* Setup the API call parameters */ String TextKey = "5347788"; /* Make the REST API Call */ String JSONpayload = textkey.perform_PollForIncomingTextKey(TextKey); /* Display the API Results */ try { JSONObject results = new JSONObject(JSONpayload).getJSONObject("d"); System.out.println("Test Results: \n" + TextKeyRest.toPrettyFormat(results.toString())); } catch(Exception pe){ pe.printStackTrace(); } } }
Here is an example of the JSON string with the d wrapper removed:
Test Results: { "__type": "TextKeyCommon.TKStructures+PolledTextKey", "ActivityDetected": true, "errorDescr": "", "TimeExpired": true }
NOTE: For more detais on the JAVA Library object and methods, you can take a look at the online documentation at http://textpower.github.io/RESTLibrary-java/.
RUBY
Example - Using the TextKey
RUBY Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKeyRest object to handle all of the heavy lifting.You will be returned a JSON string.
NOTE: To install the textkey_rest gem you can run gem install textkey_rest from a command line. To build the testkey_rest gem locally, get the latest repository at github and follow the instructions.
require 'json' require 'textkey_rest' # Setup apiKey = "9021fa44-f1bc-4590-b975-42fee031e078" # Create the textkey object textkey = TextKeyRest.new(apiKey, false) # Setup the API parameters textKey = "5347788" # Make the API Call response = textkey.perform_PollForIncomingTextKey(textKey) # Pull out the data from the response response_obj = JSON.parse(response) response_data = response_obj['d'] # Display the response puts "TextKey Results:" puts JSON.pretty_generate response_data
Here is an example of the JSON string with the d wrapper removed:
Test Results: { "__type": "TextKeyCommon.TKStructures+PolledTextKey", "ActivityDetected": true, "errorDescr": "", "TimeExpired": true }
NOTE: For more detais on the RUBY Library object and methods, you can take a look at the online documentation at http://textpower.github.io/RESTLibrary-ruby/.
Javascript
All of the TextKey
REST API calls are CORS compliant so they can be called via an Ajax request with no cross domain issues.In order to user the TextKey
REST API calls via javascript, you will need to setup the API payload using the appropriate parameters and the API key formatted as a JSON string and then make an Ajax POST request. The POST header does need to be setup as a JSON request (i.e. an application/json header) or you will not get a response.You will be returned a JSON string as the API call payload.
NOTE: Exposing your API key via any client side code is not recommended. If you choose to use the TextKey
API calls via a Javascript call, make sure to create a temporary API Key using the getTempAPIKey API call server side and then use that temporary key during its lifespan on any client side API calls.<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script> <script type="text/javascript"> // Build a class to handle the API call input payload function textkeyPayload(apiKey, textKey) { this.apiKey = apiKey; this.textKey = textKey; this.toJsonString = function () { return JSON.stringify({ 'DataIn': this }); }; }; // Handle the API Request and response function textkeyAPIRequest(txtCommand, APIJSONData) { // Setup the API URL var urlAPI = 'http://www.textkey.com/REST/TKRest.asmx/'+txtCommand; // Make the API call via a JSON Ajax request $.ajax({ type: "POST", contentType: "application/json; charset=utf-8", url: urlAPI, data: APIJSONData, dataType: "json", success: function (APIResponse, textStatus) { document.write("textStatus: "+textStatus+ "<HR>"); document.write("API Response: "+JSON.stringify(APIResponse, null, 4) + "<HR>"); if (textStatus == 'success') { if (APIResponse.hasOwnProperty('d')) { APIPayload = APIResponse.d; } else { APIPayload = APIResponse; } document.write("API Payload: "+JSON.stringify(APIPayload, null, 4) + "<HR>"); if (APIPayload.errorDescr == "") { document.write("ActivityDetected: " + APIPayload.ActivityDetected); } else { document.write("Error: " + APIPayload.errorDescr); } } else { document.write("Error: " + textStatus); } }, error: function (jqXHR, textStatus, errorThrown) { document.write("Error: " + jqXHR.status); } }); } // Setup the API command var txtCommand = 'pollForIncomingTextKey'; // Build the API payload var pollForIncomingTextKey = new textkeyPayload("9021fa44-f1bc-4590-b975-42fee031e078", "5868199"); // Make the API Call textkeyAPIRequest(txtCommand, pollForIncomingTextKey.toJsonString()); </script>
SOAP Example
- Step 1 - Authentication Settings
- Step 2 - Call Parameters
- Step 3 - SOAP Request
- Step 4 - SOAP Response
- Step 5 - Output Results
Authentication Settings
A SOAP header is required on all SOAP API calls using the _Key variant and the header information is identical on all calls.
pollForIncomingTextKey requires a SOAP header.
pollForIncomingTextKey_Key does not require a SOAP header but uses the API Key in the body of the SOAP request.Authentication Settings using an API Key
API Key: 9021fa44-f1bc-4590-b975-42fee031e078
OR
Authentication Settings using an UserID/Password Combination
userId: 1ed93006208f0540e452e3a37d8299bc
Password: Password12345
Campaign:
Keyword:The WSDL document for the TextKey
SOAP interface is located at: https://secure.textkey.com/ws/textkey.asmx?wsdl.The address for the SOAP calls on the TextKey
interface is: https://secure.textkey.com/ws/textkey.asmx.The name space for the SOAP calls on the TextKey
interface is: https://secure.textkey.com/services/.Call Parameters
The parameters should look something like this:
apiKey: 9021fa44-f1bc-4590-b975-42fee031e078 textKey: 5868199
SOAP Request
The SOAP request should look something like this:
SOAP Request using the API Key
OR
SOAP Request using the UserID/Password
SOAP Response
The SOAP response should look something like this:
SOAP Response with an valid payload
OR
SOAP Response with an error
Output Results
The final results will need to be extracted from the XML response payload should look something like this:
SOAP Response with a valid payload
stdClass Object ( [ActivityDetected] => [TimeExpired] => 1 [errorDescr] => )
ActivityDetected: TimeExpired: 1 errorDescr:
OR
SOAP Response with an error
stdClass Object ( [ActivityDetected] => [TimeExpired] => 1 [errorDescr] => Invalid Login )
Error: Invalid Login.
SOAP Code Examples
PHP
The PHP Helper library contain a textkey class that makes calling TextKey
SOAP API functions simple. Just include the helper file textkey_soap.php in your PHP code, inititalize a textkey object using your credentials (i.e. either an API key or a UserID/Password), and then make the API call with the appropriate parameters. You will be returned an object with the API call payload.// Include the TextKey classes include_once("../textkey_soap.php"); // Setup the API call parameters $textkey = "5868199"; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Create a textkey object if ($apikey != "") { $tk = new textKey("", "", "", "", $apikey); } // Handle the operation $textkey_result = $tk->perform_PollForIncomingTextKey($textkey); // Show the textkey API payload object print_r($textkey_result); echo "<HR>"; // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; } echo $results;
CURL
From a command line, you can test the SOAP API calls using a CURL request:
The SOAP pollForIncomingTextKey Request is stored in a file called pollForIncomingTextKey.xml
<?xml version="1.0" encoding="UTF-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" > <soap:Body> <pollForIncomingTextKey_Key xmlns="https://secure.textkey.com/services/"> <apiKey>9021fa44-f1bc-4590-b975-42fee031e078</apiKey> <textKey>5868199</textKey> </pollForIncomingTextKey_Key> </soap:Body> </soap:Envelope>
CURL command using pollForIncomingTextKey.xml
curl -H "Content-Type: text/xml; charset=utf-8" -H "SOAPAction:" -d @pollForIncomingTextKey.xml -X POST https://secure.textkey.com/ws/textkey.asmx
XML Response from API pollForIncomingTextKey Request
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Body> <pollForIncomingTextKey_KeyResponse xmlns="https://secure.textkey.com/services/"> <pollForIncomingTextKey_KeyResult> <ActivityDetected>false</ActivityDetected> <TimeExpired>true</TimeExpired> <errorDescr /> </pollForIncomingTextKey_KeyResult> </pollForIncomingTextKey_KeyResponse> </soap:Body> </soap:Envelope>
-
validateTextKeyFromUserId
Description
The validateTextKeyFromUserId API call is used for a final server side check of the TextKey validity. This call takes the issued TextKey, User ID, whether the User ID is hashed or not and the Validation Code that was issued with the textKey and returns a status based on whether or not all of the information matches.
API Testing Page
To test the validateTextKeyFromUserId API Call in a fully interactive environment, click here.
Input Parameters
Name Data Type Description Required apiKey String This is a unique key that is used to authenticate an API request. It should never be exposed. With the _Key function textKey String The TextKey that was issued at the start of login process. Yes userID String The UserID that is associated with the issued TextKey. Yes isHashed Boolean If the UserID was hashed when the user was registered, then the isHashed flag should be set to true. Yes validationCode String The Validation Code that was issued when the TextKey was created. Yes
Output
Name Data Type Description validated Boolean True if validated. validationCode Array Based on the combination of information passsed into the call, this field contains the validation state/error(s).
Status Returned Value textKeyNoError 0 textKeyNotFound 1 textKeyNotReceived 2 textKeyFraudDetect 3 noRegistrationFound 4 validationCodeInvalid 5 textKeyTooOld 6 textKeyError 7 textKeyNotValidated 8 pinCodeError 9 errorDescr String If a error occurs, this is the error message. This will be blank if the call was successful.
REST Example
RESTful URL
The TextKey
Restful interface consists of the secure URL path followed by the appropriate CommandName.For instance:
https://secure.textkey.com/REST/TKRest.asmx/CommandName
The CommandName is the API call itself which in this case is validateTextKeyFromUserId.
Here is what the complete URL for this API call would look like:
https://secure.textkey.com/REST/TKRest.asmx/validateTextKeyFromUserId
All Restful calls must be made using the POST method and should be of the content type application/json.
Here is an example of what a request header should look like:
POST /REST/TKRest.asmx/validateTextKeyFromuserID HTTP/1.1 Host: secure.textkey.com Accept: */* Content-Type:application/json Content-Length: 202
JSON Input Payload
All TextKey
Restful service commands take a JSON object as the input and return a JSON object as the resulting payload. Authentication is handled via an API key as one of the parameters in the JSON input.The JSON Input payload for the validateTextKeyFromUserId API call should look something like this:
{ "DataIn": { "apiKey": "9021fa44-f1bc-4590-b975-42fee031e078", "textkey": "4898697", "userID": "Stan", "isHashed": "true", "validationCode": "537ED" } }
JSON Output Payload
The JSON response should look something like this:
JSON Response with a valid payload
{ "d":{ "__type":"TextKeyCommon.TKStructures+ValidateTextKeyReturn", "validated":true, "validationErrors":["textKeyNoError"], "errorDescr":"" } }
__type: TextKeyCommon.TKStructures+ValidateTextKeyReturn validated: 1 validationErrors: Array ( [0] => textKeyNoError ) errorDescr:
OR
JSON Response with an error
{ "d":{ "__type":"TextKeyCommon.TKStructures+ValidateTextKeyReturn", "validated":false, "validationErrors":["noRegistrationFound"], "errorDescr":"" } }
Error: Invalid Login.
REST Code Examples
PHP
Example 1 - Using the TextKey
PHP Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKey object to handle all of the heavy lifting.You will be returned a PHP object and can reference all of the payload values directly from that object.
// Include the TextKey classes include_once("textkey_rest.php"); // Setup the API call parameters $userid = "Stan"; $ishashed = TRUE; $textkey = "4898697"; $textkeyvc = "537ED"; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Create a TK object $tk = new textKey($apikey); // Handle the operation $textkey_result = $tk->perform_ValidateTextKeyFromUserId($userid, $textkey, $textkeyvc, $ishashed); // Handle the results if ($textkey_result->errorDescr == "") { // Handle the payload $tkResultsArr = get_object_vars($textkey_result); foreach($tkResultsArr as $key => $value) { if (is_array($value)) { $results .= $key . ': ' . print_r($value, true) . "<BR>"; } else if (is_object($value)) { $results .= $key . ': ' . print_r($value, true); } else { $results .= $key . ': ' . $value . "<BR>"; } } echo $results; } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; echo $results; }
Here is an example of the PHP object returned:
__type: TextKeyCommon.TKStructures+ValidateTextKeyReturn validated: validationErrors: Array ( [0] => noRegistrationFound ) errorDescr:
Example 2 - Using the REST API Call directly
In order to use the TextKey
REST API calls directly, you will need to setup the API payload using the appropriate parameters and the API key formatted as a JSON string and then make a CURL POST request.The POST header does need to be setup as a JSON request (i.e. an application/json header) or you will not get a response.
You will be returned a JSON string as the API call payload. That can be converted into a PHP object using the json_decode call.
// TextKey REST path define('TK_REST', 'https://secure.textkey.com/REST/TKRest.asmx/'); // Setup the API call parameters $userid = "Stan"; $ishashed = TRUE; $textkey = "4898697"; $textkeyvc = "537ED"; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Build the REST API URL $url = TK_REST . 'validateTextKeyFromUserId'; // Setup data $postdata = json_encode( array('DataIn' => array( 'apiKey' => urlencode($apikey), 'textKey' => urlencode($textkey), 'userID' => urlencode($userid), 'isHashed' => urlencode($ishashed?"true":"false"), 'validationCode' => urlencode($textkeyvc) ) ), JSON_PRETTY_PRINT); // Handle the API request via CURL $curl = curl_init($url); // Set the CURL params and make sure it is a JSON request curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); curl_setopt($curl, CURLOPT_POST, true); curl_setopt($curl, CURLOPT_POSTFIELDS, $postdata); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json')); curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0); // Wildcard certificate $response = curl_exec($curl); curl_close($curl); // Handle the payload $textkey_payload = json_decode($response); if ($textkey_payload->d) { $textkey_result = $textkey_payload->d; } else { $textkey_result = $textkey_payload; }; // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } echo $results; } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; echo $results; }
JAVA
Example - Using the TextKey
JAVA Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKeyRest object to handle all of the heavy lifting.You will be returned a JSON string.
package com.textkey.rest.examples; import org.json.JSONObject; import com.textkey.rest.TextKeyRest; public class TestValidateTextKeyFromUserId { public static void main(String[] args) { /* Setup */ String TK_API = "9021fa44-f1bc-4590-b975-42fee031e078"; /* Create the TextKey object */ TextKeyRest textkey = new TextKeyRest(TK_API, false); /* Setup the API call parameters */ String UserID = "Stan"; String isHashed = "TRUE"; String TextKey = "5233019"; String TextKeyVC = "4DE30"; /* Make the REST API Call */ String JSONpayload = textkey.perform_ValidateTextKeyFromUserId(UserID, TextKey, TextKeyVC, isHashed); /* Display the API Results */ try { JSONObject results = new JSONObject(JSONpayload).getJSONObject("d"); System.out.println("Test Results: \n" + TextKeyRest.toPrettyFormat(results.toString())); } catch(Exception pe){ pe.printStackTrace(); } } }
Here is an example of the JSON string with the d wrapper removed:
Test Results: { "validationErrors": [ "textKeyTooOld", "textKeyAlreadyUsed" ], "__type": "TextKeyCommon.TKStructures+ValidateTextKeyReturn", "errorDescr": "", "validated": false }
NOTE: For more detais on the JAVA Library object and methods, you can take a look at the online documentation at http://textpower.github.io/RESTLibrary-java/.
RUBY
Example - Using the TextKey
RUBY Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKeyRest object to handle all of the heavy lifting.You will be returned a JSON string.
NOTE: To install the textkey_rest gem you can run gem install textkey_rest from a command line. To build the testkey_rest gem locally, get the latest repository at github and follow the instructions.
require 'json' require 'textkey_rest' # Setup apiKey = "9021fa44-f1bc-4590-b975-42fee031e078" # Create the textkey object textkey = TextKeyRest.new(apiKey, false) # Setup the API parameters userID = "Stan" isHashed = "TRUE" textKey = "5233019" textKeyVC = "4DE30" # Make the API Call response = textkey.perform_ValidateTextKeyFromUserId(userID, textKey, textKeyVC, isHashed) # Pull out the data from the response response_obj = JSON.parse(response) response_data = response_obj['d'] # Display the response puts "TextKey Results:" puts JSON.pretty_generate response_data
Here is an example of the JSON string with the d wrapper removed:
Test Results: { "validationErrors": [ "textKeyTooOld", "textKeyAlreadyUsed" ], "__type": "TextKeyCommon.TKStructures+ValidateTextKeyReturn", "errorDescr": "", "validated": false }
NOTE: For more detais on the RUBY Library object and methods, you can take a look at the online documentation at http://textpower.github.io/RESTLibrary-ruby/.
Javascript
All of the TextKey
REST API calls are CORS compliant so they can be called via an Ajax request with no cross domain issues.In order to user the TextKey
REST API calls via javascript, you will need to setup the API payload using the appropriate parameters and the API key formatted as a JSON string and then make an Ajax POST request. The POST header does need to be setup as a JSON request (i.e. an application/json header) or you will not get a response.You will be returned a JSON string as the API call payload.
NOTE: Exposing your API key via any client side code is not recommended. If you choose to use the TextKey
API calls via a Javascript call, make sure to create a temporary API Key using the getTempAPIKey API call server side and then use that temporary key during its lifespan on any client side API calls.<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script> <script type="text/javascript"> // Build a class to handle the API call input payload function textkeyPayload(apiKey, userID, isHashed, textKey, validationCode) { this.apiKey = apiKey; this.userID = userID; this.isHashed = isHashed; this.textKey = textKey; this.validationCode = validationCode; this.toJsonString = function () { return JSON.stringify({ 'DataIn': this }); }; }; // Handle the API Request and response function textkeyAPIRequest(txtCommand, APIJSONData) { // Setup the API URL var urlAPI = 'http://www.textkey.com/REST/TKRest.asmx/'+txtCommand; // Make the API call via a JSON Ajax request $.ajax({ type: "POST", contentType: "application/json; charset=utf-8", url: urlAPI, data: APIJSONData, dataType: "json", success: function (APIResponse, textStatus) { document.write("textStatus: "+textStatus+ "<HR>"); document.write("API Response: "+JSON.stringify(APIResponse, null, 4) + "<HR>"); if (textStatus == 'success') { if (APIResponse.hasOwnProperty('d')) { APIPayload = APIResponse.d; } else { APIPayload = APIResponse; } document.write("API Payload: "+JSON.stringify(APIPayload, null, 4) + "<HR>"); if (APIPayload.errorDescr == "") { document.write("validated: " + APIPayload.validated); } else { document.write("Error: " + APIPayload.errorDescr); } } else { document.write("Error: " + textStatus); } }, error: function (jqXHR, textStatus, errorThrown) { document.write("Error: " + jqXHR.status); } }); } // Setup the API command var txtCommand = 'validateTextKeyFromUserId'; // Build the API payload var validateTextKeyFromUserId = new textkeyPayload("9021fa44-f1bc-4590-b975-42fee031e078", "Stan", true, "4898697", "537ED"); // Make the API Call textkeyAPIRequest(txtCommand, validateTextKeyFromUserId.toJsonString()); </script>
SOAP Example
- Step 1 - Authentication Settings
- Step 2 - Call Parameters
- Step 3 - SOAP Request
- Step 4 - SOAP Response
- Step 5 - Output Results
Authentication Settings
A SOAP header is required on all SOAP API calls using the _Key variant and the header information is identical on all calls.
validateTextKeyFromUserId requires a SOAP header.
validateTextKeyFromUserId_Key does not require a SOAP header but uses the API Key in the body of the SOAP request.Authentication Settings using an API Key
API Key: 9021fa44-f1bc-4590-b975-42fee031e078
OR
Authentication Settings using an UserID/Password Combination
userId: 1ed93006208f0540e452e3a37d8299bc
Password: Password12345
Campaign:
Keyword:The WSDL document for the TextKey
SOAP interface is located at: https://secure.textkey.com/ws/textkey.asmx?wsdl.The address for the SOAP calls on the TextKey
interface is: https://secure.textkey.com/ws/textkey.asmx.The name space for the SOAP calls on the TextKey
interface is: https://secure.textkey.com/services/.Call Parameters
The parameters should look something like this:
apiKey: 9021fa44-f1bc-4590-b975-42fee031e078 userID: Stan isHashed: 1 textKey: 4898697 validationCode: 537ED
SOAP Request
The SOAP request should look something like this:
SOAP Request using the API Key
OR
SOAP Request using the UserID/Password
SOAP Response
The SOAP response should look something like this:
SOAP Response with an valid payload
OR
SOAP Response with an error
Output Results
The final results will need to be extracted from the XML response payload should look something like this:
SOAP Response with a valid payload
stdClass Object ( [validated] => false [validationError] => textKeyNotValidated [errorDescr] => )
validated: false validationError: textKeyNotValidated errorDescr:
OR
SOAP Response with an error
stdClass Object ( [validated] => false [validationError] => textKeyError [errorDescr] => Invalid Login )
Error: Invalid Login.
SOAP Code Examples
PHP
The PHP Helper library contain a textkey class that makes calling TextKey
SOAP API functions simple. Just include the helper file textkey_soap.php in your PHP code, inititalize a textkey object using your credentials (i.e. either an API key or a UserID/Password), and then make the API call with the appropriate parameters. You will be returned an object with the API call payload.// Include the TextKey classes include_once("../textkey_soap.php"); // Setup the API call parameters $userid = "Stan"; $ishashed = TRUE; $textkey = "4898697"; $textkeyvc = "537ED"; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Create a textkey object if ($apikey != "") { $tk = new textKey("", "", "", "", $apikey); } // Handle the operation $textkey_result = $tk->perform_ValidateTextKeyFromUserId($userid, $textkey, $textkeyvc, $ishashed); // Show the textkey API payload object print_r($textkey_result); echo "<HR>"; // Handle the results if ($textkey_result->errorDescr == "") { // Handle the payload $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { if (is_array($value)) { $results .= $key . ': ' . print_r($value, true) . "<BR>"; } else if (is_object($value)) { $results .= $key . ': ' . print_r($value, true); } else { $results .= $key . ': ' . $value . "<BR>"; } } } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; } echo $results;
CURL
From a command line, you can test the SOAP API calls using a CURL request:
The SOAP validateTextKeyFromUserId Request is stored in a file called validateTextKeyFromUserId.xml
<?xml version="1.0" encoding="UTF-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" > <soap:Body> <validateTextKeyFromUserID_Key xmlns="https://secure.textkey.com/services/"> <apiKey>9021fa44-f1bc-4590-b975-42fee031e078</apiKey> <textKey>4898697</textKey> <userID>Stan</userID> <isHashed>true</isHashed> <validationCode>537ED</validationCode> </validateTextKeyFromUserID_Key> </soap:Body> </soap:Envelope>
CURL command using validateTextKeyFromUserId.xml
curl -H "Content-Type: text/xml; charset=utf-8" -H "SOAPAction:" -d @validateTextKeyFromUserId.xml -X POST https://secure.textkey.com/ws/textkey.asmx
XML Response from API validateTextKeyFromUserId Request
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Body> <validateTextKeyFromUserID_KeyResponse xmlns="https://secure.textkey.com/services/"> <validateTextKeyFromUserID_KeyResult> <validated>false</validated> <validationError>textKeyNotValidated</validationError> <errorDescr /> </validateTextKeyFromUserID_KeyResult> </validateTextKeyFromUserID_KeyResponse> </soap:Body> </soap:Envelope>
-
validateTextKeyFromCellNumber
Description
The validateTextKeyFromCellNumber API call is used for a final server side check of the TextKey validity. This call takes the issued TextKey, Cell Number and the Validation Code that was issued with the TextKey and returns a status based on whether or not all of the information matches.
API Testing Page
To test the validateTextKeyFromCellNumber API Call in a fully interactive environment, click here.
Input Parameters
Name Data Type Description Required apiKey String This is a unique key that is used to authenticate an API request. It should never be exposed. With the _Key function textKey String The TextKey that was issued at the start of login process. Yes cellNumber String The Cell Number or the Cell Number Proxy to be used. Yes validationCode String The Validation Code that was issued when the TextKey was created. Yes
Output
Name Data Type Description validated Boolean True if validated. validationCode Array Based on the combination of information passsed into the call, this field contains the validation state/error(s).
Status Returned Value textKeyNoError 0 textKeyNotFound 1 textKeyNotReceived 2 textKeyFraudDetect 3 noRegistrationFound 4 validationCodeInvalid 5 textKeyTooOld 6 textKeyError 7 textKeyNotValidated 8 pinCodeError 9 errorDescr String If a error occurs, this is the error message. This will be blank if the call was successful.
REST Example
RESTful URL
The TextKey
Restful interface consists of the secure URL path followed by the appropriate CommandName.For instance:
https://secure.textkey.com/REST/TKRest.asmx/CommandName
The CommandName is the API call itself which in this case is validateTextKeyFromCellNumber.
Here is what the complete URL for this API call would look like:
https://secure.textkey.com/REST/TKRest.asmx/validateTextKeyFromCellNumber
All Restful calls must be made using the POST method and should be of the content type application/json.
Here is an example of what a request header should look like:
POST /REST/TKRest.asmx/validateTextKeyFromCellNumber HTTP/1.1 Host: secure.textkey.com Accept: */* Content-Type:application/json Content-Length: 183
JSON Input Payload
All TextKey
Restful service commands take a JSON object as the input and return a JSON object as the resulting payload. Authentication is handled via an API key as one of the parameters in the JSON input.The JSON Input payload for the validateTextKeyFromCellNumber API call should look something like this:
{ "DataIn": { "apiKey": "9021fa44-f1bc-4590-b975-42fee031e078", "textKey": "4898697", "cellNumber": "8181231234", "validationCode": "537ED" } }
JSON Output Payload
The JSON response should look something like this:
JSON Response with a valid payload
{ "d":{ "__type":"TextKeyCommon.TKStructures+ValidateTextKeyReturn", "validated":true, "validationErrors":["textKeyNoError"], "errorDescr":"" } }
__type: TextKeyCommon.TKStructures+ValidateTextKeyReturn validated: 1 validationErrors: Array ( [0] => textKeyNoError ) errorDescr:
OR
JSON Response with an error
{ "d":{ "__type":"TextKeyCommon.TKStructures+ValidateTextKeyReturn", "validated":false, "validationErrors":["textKeyNotFound"], "errorDescr":"" } }
Error: Invalid Login.
REST Code Examples
PHP
Example 1 - Using the TextKey
PHP Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKey object to handle all of the heavy lifting.You will be returned a PHP object and can reference all of the payload values directly from that object.
// Include the TextKey classes include_once("textkey_rest.php"); // Setup the API call parameters $cellnumber = "8181231234"; $textkey = "4898697"; $textkeyvc = "537ED"; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Create a TK object $tk = new textKey($apikey); // Handle the operation $textkey_result = $tk->perform_ValidateTextKeyFromCellNumber($cellnumber, $textkey, $textkeyvc); // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } echo $results; } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; echo $results; }
Here is an example of the PHP object returned:
__type: TextKeyCommon.TKStructures+ValidateTextKeyReturn validated: validationErrors: Array ( [0] => textKeyNotFound ) errorDescr:
Example 2 - Using the REST API Call directly
In order to use the TextKey
REST API calls directly, you will need to setup the API payload using the appropriate parameters and the API key formatted as a JSON string and then make a CURL POST request.The POST header does need to be setup as a JSON request (i.e. an application/json header) or you will not get a response.
You will be returned a JSON string as the API call payload. That can be converted into a PHP object using the json_decode call.
// TextKey REST path define('TK_REST', 'https://secure.textkey.com/REST/TKRest.asmx/'); // Setup the API call parameters $cellnumber = "8181231234"; $textkey = "4898697"; $textkeyvc = "537ED"; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Build the REST API URL $url = TK_REST . 'validateTextKeyFromCellNumber'; // Setup data $postdata = json_encode( array('DataIn' => array( 'apiKey' => urlencode($apikey), 'textKey' => urlencode($textkey), 'cellNumber' => urlencode($cellnumber), 'validationCode' => urlencode($textkeyvc) ) ), JSON_PRETTY_PRINT); // Handle the API request via CURL $curl = curl_init($url); // Set the CURL params and make sure it is a JSON request curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); curl_setopt($curl, CURLOPT_POST, true); curl_setopt($curl, CURLOPT_POSTFIELDS, $postdata); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json')); curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0); // Wildcard certificate $response = curl_exec($curl); curl_close($curl); // Handle the payload $textkey_payload = json_decode($response); if ($textkey_payload->d) { $textkey_result = $textkey_payload->d; } else { $textkey_result = $textkey_payload; }; // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } echo $results; } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; echo $results; }
JAVA
Example - Using the TextKey
JAVA Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKeyRest object to handle all of the heavy lifting.You will be returned a JSON string.
package com.textkey.rest.examples; import org.json.JSONObject; import com.textkey.rest.TextKeyRest; public class TestValidateTextKeyFromCellNumber { public static void main(String[] args) { /* Setup */ String TK_API = "9021fa44-f1bc-4590-b975-42fee031e078"; /* Create the TextKey object */ TextKeyRest textkey = new TextKeyRest(TK_API, false); /* Setup the API call parameters */ String CellNumber = "8181231234"; String TextKey = "4819399"; String TextKeyVC = "57G14"; /* Make the REST API Call */ String JSONpayload = textkey.perform_ValidateTextKeyFromCellNumber(CellNumber, TextKey, TextKeyVC); /* Display the API Results */ try { JSONObject results = new JSONObject(JSONpayload).getJSONObject("d"); System.out.println("Test Results: \n" + TextKeyRest.toPrettyFormat(results.toString())); } catch(Exception pe){ pe.printStackTrace(); } } }
Here is an example of the JSON string with the d wrapper removed:
Test Results: { "validationErrors": [ "textKeyTooOld", "textKeyAlreadyUsed" ], "__type": "TextKeyCommon.TKStructures+ValidateTextKeyReturn", "errorDescr": "", "validated": false }
NOTE: For more detais on the JAVA Library object and methods, you can take a look at the online documentation at http://textpower.github.io/RESTLibrary-java/.
RUBY
Example - Using the TextKey
RUBY Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKeyRest object to handle all of the heavy lifting.You will be returned a JSON string.
NOTE: To install the textkey_rest gem you can run gem install textkey_rest from a command line. To build the testkey_rest gem locally, get the latest repository at github and follow the instructions.
require 'json' require 'textkey_rest' # Setup apiKey = "9021fa44-f1bc-4590-b975-42fee031e078" # Create the textkey object textkey = TextKeyRest.new(apiKey, false) # Setup the API parameters cellNumber = "8054100577" textKey = "4819399" textKeyVC = "57G14" # Make the API Call response = textkey.perform_ValidateTextKeyFromCellNumber(cellNumber, textKey, textKeyVC) # Pull out the data from the response response_obj = JSON.parse(response) response_data = response_obj['d'] # Display the response puts "TextKey Results:" puts JSON.pretty_generate response_data
Here is an example of the JSON string with the d wrapper removed:
Test Results: { "validationErrors": [ "textKeyTooOld", "textKeyAlreadyUsed" ], "__type": "TextKeyCommon.TKStructures+ValidateTextKeyReturn", "errorDescr": "", "validated": false }
NOTE: For more detais on the RUBY Library object and methods, you can take a look at the online documentation at http://textpower.github.io/RESTLibrary-ruby/.
Javascript
All of the TextKey
REST API calls are CORS compliant so they can be called via an Ajax request with no cross domain issues.In order to user the TextKey
REST API calls via javascript, you will need to setup the API payload using the appropriate parameters and the API key formatted as a JSON string and then make an Ajax POST request. The POST header does need to be setup as a JSON request (i.e. an application/json header) or you will not get a response.You will be returned a JSON string as the API call payload.
NOTE: Exposing your API key via any client side code is not recommended. If you choose to use the TextKey
API calls via a Javascript call, make sure to create a temporary API Key using the getTempAPIKey API call server side and then use that temporary key during its lifespan on any client side API calls.<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script> <script type="text/javascript"> // Build a class to handle the API call input payload function textkeyPayload(apiKey, cellNumber, textKey, validationCode) { this.apiKey = apiKey; this.cellNumber = cellNumber; this.textKey = textKey; this.validationCode = validationCode; this.toJsonString = function () { return JSON.stringify({ 'DataIn': this }); }; }; // Handle the API Request and response function textkeyAPIRequest(txtCommand, APIJSONData) { // Setup the API URL var urlAPI = 'http://www.textkey.com/REST/TKRest.asmx/'+txtCommand; // Make the API call via a JSON Ajax request $.ajax({ type: "POST", contentType: "application/json; charset=utf-8", url: urlAPI, data: APIJSONData, dataType: "json", success: function (APIResponse, textStatus) { document.write("textStatus: "+textStatus+ "<HR>"); document.write("API Response: "+JSON.stringify(APIResponse, null, 4) + "<HR>"); if (textStatus == 'success') { if (APIResponse.hasOwnProperty('d')) { APIPayload = APIResponse.d; } else { APIPayload = APIResponse; } document.write("API Payload: "+JSON.stringify(APIPayload, null, 4) + "<HR>"); if (APIPayload.errorDescr == "") { document.write("validated: " + APIPayload.validated); } else { document.write("Error: " + APIPayload.errorDescr); } } else { document.write("Error: " + textStatus); } }, error: function (jqXHR, textStatus, errorThrown) { document.write("Error: " + jqXHR.status); } }); } // Setup the API command var txtCommand = 'validateTextKeyFromCellNumber'; // Build the API payload var validateTextKeyFromCellNumber = new textkeyPayload("9021fa44-f1bc-4590-b975-42fee031e078", "8181231234", "4898697", "537ED"); // Make the API Call textkeyAPIRequest(txtCommand, validateTextKeyFromCellNumber.toJsonString()); </script>
SOAP Example
- Step 1 - Authentication Settings
- Step 2 - Call Parameters
- Step 3 - SOAP Request
- Step 4 - SOAP Response
- Step 5 - Output Results
Authentication Settings
A SOAP header is required on all SOAP API calls using the _Key variant and the header information is identical on all calls.
validateTextKeyFromCellNumber requires a SOAP header.
validateTextKeyFromCellNumber_Key does not require a SOAP header but uses the API Key in the body of the SOAP request.Authentication Settings using an API Key
API Key: 9021fa44-f1bc-4590-b975-42fee031e078
OR
Authentication Settings using an UserID/Password Combination
userId: 1ed93006208f0540e452e3a37d8299bc
Password: Password12345
Campaign:
Keyword:The WSDL document for the TextKey
SOAP interface is located at: https://secure.textkey.com/ws/textkey.asmx?wsdl.The address for the SOAP calls on the TextKey
interface is: https://secure.textkey.com/ws/textkey.asmx.The name space for the SOAP calls on the TextKey
interface is: https://secure.textkey.com/services/.Call Parameters
The parameters should look something like this:
apiKey: 9021fa44-f1bc-4590-b975-42fee031e078 textKey: 4898697 cellNumber: 8181231234 validationCode: 537ED
SOAP Request
The SOAP request should look something like this:
SOAP Request using the API Key
OR
SOAP Request using the UserID/Password
SOAP Response
The SOAP response should look something like this:
SOAP Response with an valid payload
OR
SOAP Response with an error
Output Results
The final results will need to be extracted from the XML response payload should look something like this:
SOAP Response with a valid payload
stdClass Object ( [validated] => false [validationError] => textKeyNotValidated [errorDescr] => )
validated: false validationError: textKeyNotValidated errorDescr:
OR
SOAP Response with an error
stdClass Object ( [validated] => false [validationError] => textKeyError [errorDescr] => Invalid Login )
Error: Invalid Login.
SOAP Code Examples
PHP
The PHP Helper library contain a textkey class that makes calling TextKey
SOAP API functions simple. Just include the helper file textkey_soap.php in your PHP code, inititalize a textkey object using your credentials (i.e. either an API key or a UserID/Password), and then make the API call with the appropriate parameters. You will be returned an object with the API call payload.// Include the TextKey classes include_once("../textkey_soap.php"); // Setup the API call parameters $cellnumber = "8181231234"; $textkey = "4898697"; $textkeyvc = "537ED"; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Create a textkey object if ($apikey != "") { $tk = new textKey("", "", "", "", $apikey); } // Handle the operation $textkey_result = $tk->perform_ValidateTextKeyFromCellNumber($cellnumber, $textkey, $textkeyvc); // Show the textkey API payload object print_r($textkey_result); echo "<HR>"; // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; } echo $results;
CURL
From a command line, you can test the SOAP API calls using a CURL request:
The SOAP validateTextKeyFromCellNumber Request is stored in a file called validateTextKeyFromCellNumber.xml
<?xml version="1.0" encoding="UTF-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" > <soap:Body> <validateTextKeyFromCellNumber_Key xmlns="https://secure.textkey.com/services/"> <apiKey>9021fa44-f1bc-4590-b975-42fee031e078</apiKey> <textKey>4898697</textKey> <cellNumber>8181231234</cellNumber> <validationCode>537ED</validationCode> </validateTextKeyFromCellNumber_Key> </soap:Body> </soap:Envelope>
CURL command using validateTextKeyFromCellNumber.xml
curl -H "Content-Type: text/xml; charset=utf-8" -H "SOAPAction:" -d @validateTextKeyFromCellNumber.xml -X POST https://secure.textkey.com/ws/textkey.asmx
XML Response from API validateTextKeyFromCellNumber Request
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Body> <validateTextKeyFromCellNumber_KeyResponse xmlns="https://secure.textkey.com/services/"> <validateTextKeyFromCellNumber_KeyResult> <validated>false</validated> <validationError>textKeyNotValidated</validationError> <errorDescr /> </validateTextKeyFromCellNumber_KeyResult> </validateTextKeyFromCellNumber_KeyResponse> </soap:Body> </soap:Envelope>
-
registerTextKeyUser
Description
The registerTextKeyUser API call allows you to add a new user registration, modify an existing registration, delete a registration or query an existing registration.
API Testing Page
To test the registerTextKeyUser API Call in a fully interactive environment, click here.
Input Parameters
Name Data Type Description Required apiKey String This is a unique key that is used to authenticate an API request. It should never be exposed. With the _Key function command Integer Defines the type of operation to be applied to the registered user.
Option Value Query 0 AddChange 1 Delete 2 Yes cellNumber String The Cell Number that you are registering Yes ownerFName String User's First Name. This parameter is only used to assist the customer's administrator. It may be blank. Yes ownerLName String User's Last Name. This parameter is only used to assist the customer's administrator. It may be blank. Yes suppl1 String An additional identifier chosen by the customer. Examples might be the department number, payroll ID number, etc. This parameter is only used to assist the customer's administrator. It may be blank. Yes suppl2 String Another additional identifier chosen by the customer. Examples might be the department number, payroll ID number, etc. This parameter is only used to assist the customer's administrator. It may be blank. Yes textKeyMode Integer The TextKey validation mode.
Option Value TextKeyOnly 0 PinCodeOnly 1 TextKeyPlusPin 2 Anything 3 Yes receiveMode Integer The TextKey receive mode.
The UseDefault option is valid only on registration API calls. It indicates that the option will be taken from the customer default.
Option Value AnyCode 0 SpecificCodeDisplay 1 SpecificCodeNoDisplay 2 RandomCode 3 UseDefault 4 Yes pinCode String The numeric Pin Code as a string. Empty String indicates no Pin Code. Yes distressPinCode String The numeric Distress Pin Code as a string. Empty String indicates no Distress Pin Code. Yes
Output
Name Data Type Description action Integer Defines the type of operation applied to the registered user.
Status Returned Value Query 0 AddChange 1 Delete 2 cellNumber String The Cell Number the operation was applied to ownerFName String The User's First Name. ownerLName String The User's Last Name. suppl1 String An additional identifier chosen by the customer. suppl2 String Another additional identifier chosen by the customer. textKeyMode Integer The TextKey validation mode.
Status Returned Value TextKeyOnly 0 PinCodeOnly 1 TextKeyPlusPin 2 Anything 3 receiveMode Integer The TextKey receive validation mode.
Status Returned Value AnyCode 0 SpecificCodeDisplay 1 SpecificCodeNoDisplay 2 RandomCode 3 UseDefault 4 pinCode String The numeric Pin Code. distressPinCode String The numeric Distress Pin Code. ownerBirthDate String The users birth date. The format should be MM/DD/YYYY (i.e. 12/25/1984). ownerGender String The users gender. The values should be either M or F. q1 String The first user profile question. a1 String The answer to the first user question. q2 String The second user profile question. a2 String The answer to the second user question. q3 String The third user profile question. a3 String The answer to the third user question.
REST Example
RESTful URL
The TextKey
Restful interface consists of the secure URL path followed by the appropriate CommandName.For instance:
https://secure.textkey.com/REST/TKRest.asmx/CommandName
The CommandName is the API call itself which in this case is registerTextKeyUser.
Here is what the complete URL for this API call would look like:
https://secure.textkey.com/REST/TKRest.asmx/registerTextKeyUser
All Restful calls must be made using the POST method and should be of the content type application/json.
Here is an example of what a request header should look like:
POST /REST/TKRest.asmx/registerTextKeyUser HTTP/1.1 Host: secure.textkey.com Accept: */* Content-Type:application/json Content-Length: 418
JSON Input Payload
All TextKey
Restful service commands take a JSON object as the input and return a JSON object as the resulting payload. Authentication is handled via an API key as one of the parameters in the JSON input.The JSON Input payload for the registerTextKeyUser API call should look something like this:
{ "DataIn": { "apiKey": "9021fa44-f1bc-4590-b975-42fee031e078", "command": "Query", "cellNumber": "8181231234", "ownerFName": "", "ownerLName": "", "suppl1": "", "suppl2": "", "userID": "", "isHashed": "true", "pinCode": "", "distressPinCode": "", "TextKeyMode": "TextKeyOnly", "ReceiveMode": "AnyCode" } }
JSON Output Payload
The JSON response should look something like this:
JSON Response with a valid payload
{ "d":{ "__type":"TextKeyCommon.TKStructures+RegisterTextKeyUserCSAReturn", "action":"0", "cellNumber":"8181231234", "ownerFName":"Stan", "ownerLName":"Steamer", "suppl1":"No", "suppl2":"Yes", "userID":"Stan", "textKeyMode":0, "receiveMode":0, "pinCode":"123", "distressPinCode":"1234", "ownerBirthDate":"12/25/1984", "ownerGender":"M", "q1":"q1", "a1":"a1", "q2":"q2", "a2":"a2", "q3":"q3", "a3":"a3", "errorDescr":"" } }
__type: TextKeyCommon.TKStructures+RegisterTextKeyUserCSAReturn action: 0 cellNumber: 8181231234 ownerFName: Stan ownerLName: Steamer suppl1: No suppl2: Yes userID: Stan textKeyMode: 0 receiveMode: 0 pinCode: 123 distressPinCode: 1234 ownerBirthDate: 12/25/1984 ownerGender: M q1: q1 a1: a1 q2: q2 a2: a2 q3: q3 a3: a3 errorDescr:
OR
JSON Response with an error
{ "d":{ "__type":"TextKeyCommon.TKStructures+RegisterTextKeyUserCSAReturn", "action":, "cellNumber":, "ownerFName":, "ownerLName":, "suppl1":, "suppl2":, "userID":, "textKeyMode":0, "receiveMode":0, "pinCode":, "distressPinCode":, "ownerBirthDate":, "ownerGender":, "q1":, "a1":, "q2":, "a2":, "q3":, "a3":, "errorDescr":"Invalid Login" } }
Error: Invalid Login.
REST Code Examples
PHP
Example 1 - Using the TextKey
PHP Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKey object to handle all of the heavy lifting.You will be returned a PHP object and can reference all of the payload values directly from that object.
// Include the TextKey classes include_once("textkey_rest.php"); // Setup the API call parameters $Command = "Query"; $CellNumber = "8181231234"; $OwnerFName = ""; $OwnerLName = ""; $Suppl1 = ""; $Suppl2 = ""; $RegUserID = ""; $isHashed = TRUE; $PinCode = ""; $DistressPinCode = ""; $TextKeyMode = "TextKeyOnly"; $ReceiveMode = "AnyCode"; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Create a TK object $tk = new textKey($apikey); // Handle the operation $textkey_result = $tk->perform_registerTextKeyUser($Command, $CellNumber, $OwnerFName, $OwnerLName, $Suppl1, $Suppl2, $RegUserID, $isHashed, $PinCode, $DistressPinCode, $TextKeyMode, $ReceiveMode); // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } echo $results; } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; echo $results; }
Here is an example of the PHP object returned:
stdClass Object ( [__type] => TextKeyCommon.TKStructures+RegisterTextKeyUserCSAReturn [action] => 0 [cellNumber] => 8181231234 [ownerFName] => Stan [ownerLName] => Steamer [suppl1] => No [suppl2] => Yes [userID] => Stan [textKeyMode] => 0 [receiveMode] => 0 [pinCode] => 123 [distressPinCode] => 1234 [ownerBirthDate] => 12/25/1984 [ownerGender] => M [q1] => q1 [a1] => a1 [q2] => q2 [a2] => a2 [q3] => q3 [a3] => a3 [errorDescr] => )
Example 2 - Using the REST API Call directly
In order to use the TextKey
REST API calls directly, you will need to setup the API payload using the appropriate parameters and the API key formatted as a JSON string and then make a CURL POST request.The POST header does need to be setup as a JSON request (i.e. an application/json header) or you will not get a response.
You will be returned a JSON string as the API call payload. That can be converted into a PHP object using the json_decode call.
// TextKey REST path define('TK_REST', 'https://secure.textkey.com/REST/TKRest.asmx/'); // Setup the API call parameters $Command = "Query"; $CellNumber = "8181231234"; $OwnerFName = ""; $OwnerLName = ""; $Suppl1 = ""; $Suppl2 = ""; $RegUserID = ""; $isHashed = TRUE; $PinCode = ""; $DistressPinCode = ""; $TextKeyMode = "TextKeyOnly"; $ReceiveMode = "AnyCode"; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Build the REST API URL $url = TK_REST . 'registerTextKeyUser'; // Setup data $postdata = json_encode( array('DataIn' => array( 'apiKey' => urlencode($apikey), 'command' => urlencode($Command), 'cellNumber' => urlencode($CellNumber), 'ownerFName' => urlencode($OwnerFName), 'ownerLName' => urlencode($OwnerLName), 'suppl1' => urlencode($Suppl1), 'suppl2' => urlencode($Suppl2), 'userID' => urlencode($RegUserID), 'isHashed' => urlencode($isHashed?"true":"false"), 'pinCode' => urlencode($PinCode), 'distressPinCode' => urlencode($DistressPinCode), 'TextKeyMode' => urlencode($TextKeyMode), 'ReceiveMode' => urlencode($ReceiveMode) ) ), JSON_PRETTY_PRINT); // Handle the API request via CURL $curl = curl_init($url); // Set the CURL params and make sure it is a JSON request curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); curl_setopt($curl, CURLOPT_POST, true); curl_setopt($curl, CURLOPT_POSTFIELDS, $postdata); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json')); curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0); // Wildcard certificate $response = curl_exec($curl); curl_close($curl); // Handle the payload $textkey_payload = json_decode($response); if ($textkey_payload->d) { $textkey_result = $textkey_payload->d; } else { $textkey_result = $textkey_payload; }; // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } echo $results; } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; echo $results; }
JAVA
Example - Using the TextKey
JAVA Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKeyRest object to handle all of the heavy lifting.You will be returned a JSON string.
package com.textkey.rest.examples; import org.json.JSONObject; import com.textkey.rest.TextKeyRest; public class TestRegisterTextKeyUser { public static void main(String[] args) { /* Setup */ String TK_API = "9021fa44-f1bc-4590-b975-42fee031e078"; /* Create the TextKey object */ TextKeyRest textkey = new TextKeyRest(TK_API, false); /* Setup the API call parameters */ Integer Command = 0; String CellNumber = "8181231234"; String OwnerFName = ""; String OwnerLName = ""; String Suppl1 = ""; String Suppl2 = ""; String UserID = ""; String isHashed = "TRUE"; String PinCode = ""; String DistressPinCode = ""; Integer TextKeyMode = 0; Integer ReceiveMode = 0; /* Make the REST API Call */ String JSONpayload = textkey.perform_registerTextKeyUser(Command, CellNumber, OwnerFName, OwnerLName, Suppl1, Suppl2, UserID, isHashed, PinCode, DistressPinCode, TextKeyMode, ReceiveMode); /* Display the API Results */ try { JSONObject results = new JSONObject(JSONpayload).getJSONObject("d"); System.out.println("Test Results: \n" + TextKeyRest.toPrettyFormat(results.toString())); } catch(Exception pe){ pe.printStackTrace(); } } }
Here is an example of the JSON string with the d wrapper removed:
Test Results: { "receiveMode": 0, "q2": "", "q1": "", "errorDescr": "", "q3": "", "ownerGender": " ", "cellNumber": "8051231234", "ownerLName": "", "distressPinCode": "4321", "__type": "TextKeyCommon.TKStructures+RegisterTextKeyUserCSAReturn", "ownerFName": "Stan", "userID": "Stan", "pinCode": "1234", "textKeyMode": 0, "suppl1": "Suppl1", "a1": "", "action": "0", "a2": "", "a3": "", "suppl2": "Suppl2", "ownerBirthDate": "1/1/1970" }
NOTE: For more detais on the JAVA Library object and methods, you can take a look at the online documentation at http://textpower.github.io/RESTLibrary-java/.
RUBY
Example - Using the TextKey
RUBY Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKeyRest object to handle all of the heavy lifting.You will be returned a JSON string.
NOTE: To install the textkey_rest gem you can run gem install textkey_rest from a command line. To build the testkey_rest gem locally, get the latest repository at github and follow the instructions.
require 'json' require 'textkey_rest' # Setup apiKey = "9021fa44-f1bc-4590-b975-42fee031e078" # Create the textkey object textkey = TextKeyRest.new(apiKey, false) # Setup the API parameters command = 0 cellNumber = "8181231234" ownerFName = "" ownerLName = "" suppl1 = "" suppl2 = "" userID = "" isHashed = "TRUE" pinCode = "" distressPinCode = "" textKeyMode = 0 receiveMode = 0 # Make the API Call response = textkey.perform_registerTextKeyUser(command, cellNumber, ownerFName, ownerLName, suppl1, suppl2, userID, isHashed, pinCode, distressPinCode, textKeyMode, receiveMode) # Pull out the data from the response response_obj = JSON.parse(response) response_data = response_obj['d'] # Display the response puts "TextKey Results:" puts JSON.pretty_generate response_data
Here is an example of the JSON string with the d wrapper removed:
Test Results: { "receiveMode": 0, "q2": "", "q1": "", "errorDescr": "", "q3": "", "ownerGender": " ", "cellNumber": "8051231234", "ownerLName": "", "distressPinCode": "4321", "__type": "TextKeyCommon.TKStructures+RegisterTextKeyUserCSAReturn", "ownerFName": "Stan", "userID": "Stan", "pinCode": "1234", "textKeyMode": 0, "suppl1": "Suppl1", "a1": "", "action": "0", "a2": "", "a3": "", "suppl2": "Suppl2", "ownerBirthDate": "1/1/1970" }
NOTE: For more detais on the RUBY Library object and methods, you can take a look at the online documentation at http://textpower.github.io/RESTLibrary-ruby/.
Javascript
All of the TextKey
REST API calls are CORS compliant so they can be called via an Ajax request with no cross domain issues.In order to user the TextKey
REST API calls via javascript, you will need to setup the API payload using the appropriate parameters and the API key formatted as a JSON string and then make an Ajax POST request. The POST header does need to be setup as a JSON request (i.e. an application/json header) or you will not get a response.You will be returned a JSON string as the API call payload.
NOTE: Exposing your API key via any client side code is not recommended. If you choose to use the TextKey
API calls via a Javascript call, make sure to create a temporary API Key using the getTempAPIKey API call server side and then use that temporary key during its lifespan on any client side API calls.<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script> <script type="text/javascript"> // Build a class to handle the API call input payload function textkeyPayload(apiKey, command, cellNumber, ownerFName, ownerLName, suppl1, suppl2, userID, isHashed, pinCode, distressPinCode, TextKeyMode, ReceiveMode) { this.apiKey = apiKey; this.command = command; this.cellNumber = cellNumber; this.ownerFName = ownerFName; this.ownerLName = ownerLName; this.suppl1 = suppl1; this.suppl2 = suppl2; this.userID = userID; this.isHashed = isHashed; this.pinCode = pinCode; this.distressPinCode = distressPinCode; this.TextKeyMode = TextKeyMode; this.ReceiveMode = ReceiveMode; this.toJsonString = function () { return JSON.stringify({ 'DataIn': this }); }; }; // Handle the API Request and response function textkeyAPIRequest(txtCommand, APIJSONData) { // Setup the API URL var urlAPI = 'http://www.textkey.com/REST/TKRest.asmx/'+txtCommand; // Make the API call via a JSON Ajax request $.ajax({ type: "POST", contentType: "application/json; charset=utf-8", url: urlAPI, data: APIJSONData, dataType: "json", success: function (APIResponse, textStatus) { document.write("textStatus: "+textStatus+ "<HR>"); document.write("API Response: "+JSON.stringify(APIResponse, null, 4) + "<HR>"); if (textStatus == 'success') { if (APIResponse.hasOwnProperty('d')) { APIPayload = APIResponse.d; } else { APIPayload = APIResponse; } document.write("API Payload: "+JSON.stringify(APIPayload, null, 4) + "<HR>"); if (APIPayload.errorDescr == "") { document.write("userID: " + APIPayload.userID); } else { document.write("Error: " + APIPayload.errorDescr); } } else { document.write("Error: " + textStatus); } }, error: function (jqXHR, textStatus, errorThrown) { document.write("Error: " + jqXHR.status); } }); } // Setup the API command var txtCommand = 'registerTextKeyUser'; // Build the API payload var registerTextKeyUser = new textkeyPayload("9021fa44-f1bc-4590-b975-42fee031e078", "Query", "8181231234", "", "", "", "", "", true, "", "", "TextKeyOnly", "AnyCode"); // Make the API Call textkeyAPIRequest(txtCommand, registerTextKeyUser.toJsonString()); </script>
SOAP Example
- Step 1 - Authentication Settings
- Step 2 - Call Parameters
- Step 3 - SOAP Request
- Step 4 - SOAP Response
- Step 5 - Output Results
Authentication Settings
A SOAP header is required on all SOAP API calls using the _Key variant and the header information is identical on all calls.
registerTextKeyUser requires a SOAP header.
registerTextKeyUser_Key does not require a SOAP header but uses the API Key in the body of the SOAP request.Authentication Settings using an API Key
API Key: 9021fa44-f1bc-4590-b975-42fee031e078
OR
Authentication Settings using an UserID/Password Combination
userId: 1ed93006208f0540e452e3a37d8299bc
Password: Password12345
Campaign:
Keyword:The WSDL document for the TextKey
SOAP interface is located at: https://secure.textkey.com/ws/textkey.asmx?wsdl.The address for the SOAP calls on the TextKey
interface is: https://secure.textkey.com/ws/textkey.asmx.The name space for the SOAP calls on the TextKey
interface is: https://secure.textkey.com/services/.Call Parameters
The parameters should look something like this:
apiKey: 9021fa44-f1bc-4590-b975-42fee031e078 command: Query cellNumber: 8181231234 ownerFName: ownerLName: suppl1: suppl2: userID: isHashed: 1 pinCode: distressPinCode: TextKeyMode: TextKeyOnly ReceiveMode: AnyCode
SOAP Request
The SOAP request should look something like this:
SOAP Request using the API Key
OR
SOAP Request using the UserID/Password
SOAP Response
The SOAP response should look something like this:
SOAP Response with an valid payload
OR
SOAP Response with an error
Output Results
The final results will need to be extracted from the XML response payload should look something like this:
SOAP Response with a valid payload
stdClass Object ( [action] => 0 [cellNumber] => 8181231234 [ownerFName] => Stan [ownerLName] => Steamer [suppl1] => No [suppl2] => Yes [userID] => Stan [textKeyMode] => TextKeyOnly [receiveMode] => AnyCode [pinCode] => 123 [distressPinCode] => 1234 [ownerBirthDate] => 12/25/1984 [ownerGender] => M [q1] => q1 [a1] => a1 [q2] => q2 [a2] => a2 [q3] => q3 [a3] => a3 [errorDescr] => )
action: 0 cellNumber: 8181231234 ownerFName: Stan ownerLName: Steamer suppl1: No suppl2: Yes userID: Stan textKeyMode: TextKeyOnly receiveMode: AnyCode pinCode: 123 distressPinCode: 1234 ownerBirthDate: 12/25/1984 ownerGender: M q1: q1 a1: a1 q2: q2 a2: a2 q3: q3 a3: a3 errorDescr:
OR
SOAP Response with an error
stdClass Object ( [textKeyMode] => TextKeyOnly [receiveMode] => AnyCode [errorDescr] => Invalid Login )
Error: Invalid Login.
SOAP Code Examples
PHP
The PHP Helper library contain a textkey class that makes calling TextKey
SOAP API functions simple. Just include the helper file textkey_soap.php in your PHP code, inititalize a textkey object using your credentials (i.e. either an API key or a UserID/Password), and then make the API call with the appropriate parameters. You will be returned an object with the API call payload.// Include the TextKey classes include_once("../textkey_soap.php"); // Setup the API call parameters $Command = "Query"; $CellNumber = "8181231234"; $OwnerFName = ""; $OwnerLName = ""; $Suppl1 = ""; $Suppl2 = ""; $RegUserID = ""; $isHashed = TRUE; $PinCode = ""; $DistressPinCode = ""; $TextKeyMode = "TextKeyOnly"; $ReceiveMode = "AnyCode"; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Create a textkey object if ($apikey != "") { $tk = new textKey("", "", "", "", $apikey); } // Handle the operation $textkey_result = $tk->perform_registerTextKeyUser($Command, $CellNumber, $OwnerFName, $OwnerLName, $Suppl1, $Suppl2, $RegUserID, $isHashed, $PinCode, $DistressPinCode, $TextKeyMode, $ReceiveMode); // Show the textkey API payload object print_r($textkey_result); echo "<HR>"; // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; } echo $results;
CURL
From a command line, you can test the SOAP API calls using a CURL request:
The SOAP registerTextKeyUser Request is stored in a file called registerTextKeyUser.xml
<?xml version="1.0" encoding="UTF-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" > <soap:Body> <registerTextKeyUser_Key xmlns="https://secure.textkey.com/services/"> <apiKey>9021fa44-f1bc-4590-b975-42fee031e078</apiKey> <command>Query</command> <cellNumber>8181231234</cellNumber> <ownerFName> </ownerFName> <ownerLName> </ownerLName> <suppl1> </suppl1> <suppl2> </suppl2> <userID> </userID> <isHashed>true</isHashed> <TextKeyMode>TextKeyOnly</TextKeyMode> <ReceiveMode>AnyCode</ReceiveMode> <pinCode> </pinCode> <distressPinCode> </distressPinCode> </registerTextKeyUser_Key> </soap:Body> </soap:Envelope>
CURL command using registerTextKeyUser.xml
curl -H "Content-Type: text/xml; charset=utf-8" -H "SOAPAction:" -d @registerTextKeyUser.xml -X POST https://secure.textkey.com/ws/textkey.asmx
XML Response from API registerTextKeyUser Request
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Body> <registerTextKeyUser_KeyResponse xmlns="https://secure.textkey.com/services/"> <registerTextKeyUser_KeyResult> <action>0</action> <cellNumber>8181231234</cellNumber> <ownerFName>Stan</ownerFName> <ownerLName>Steamer</ownerLName> <suppl1>No</suppl1> <suppl2>Yes</suppl2> <userID>Stan</userID> <textKeyMode>TextKeyOnly</textKeyMode> <receiveMode>AnyCode</receiveMode> <pinCode>123</pinCode> <distressPinCode>1234</distressPinCode> <ownerBirthDate>12/25/1984</ownerBirthDate> <ownerGender>M</ownerGender> <q1>q1</q1> <a1>a1</a1> <q2>q2</q2> <a2>a2</a2> <q3>q3</q3> <a3>a3</a3> <errorDescr /> </registerTextKeyUser_KeyResult> </registerTextKeyUser_KeyResponse> </soap:Body> </soap:Envelope>
-
registerTextKeyUserCSA
Description
The registerTextKeyUserCSA API call allows you to add a new user registration, modify an existing registration, delete a registration or query an existing registration. It's functions are similar to the registerTextKeyUser API call but add the ability to set the Customer Service Agency functions.
API Testing Page
To test the registerTextKeyUserCSA API Call in a fully interactive environment, click here.
Input Parameters
Name Data Type Description Required apiKey String This is a unique key that is used to authenticate an API request. It should never be exposed. With the _Key function command Integer Defines the type of operation to be applied to the registered user.
Option Value Query 0 AddChange 1 Delete 2 Yes cellNumber String The Cell Number that you are registering Yes ownerFName String User's First Name. This parameter is only used to assist the customer's administrator. It may be blank. Yes ownerLName String User's Last Name. This parameter is only used to assist the customer's administrator. It may be blank. Yes suppl1 String An additional identifier chosen by the customer. Examples might be the department number, payroll ID number, etc. This parameter is only used to assist the customer's administrator. It may be blank. Yes suppl2 String Another additional identifier chosen by the customer. Examples might be the department number, payroll ID number, etc. This parameter is only used to assist the customer's administrator. It may be blank. Yes textKeyMode Integer The TextKey validation mode.
Option Value TextKeyOnly 0 PinCodeOnly 1 TextKeyPlusPin 2 Anything 3 Yes receiveMode Integer The TextKey receive mode.
The UseDefault option is valid only on registration API calls. It indicates that the option will be taken from the customer default.
Option Value AnyCode 0 SpecificCodeDisplay 1 SpecificCodeNoDisplay 2 RandomCode 3 UseDefault 4 Yes pinCode String The numeric Pin Code as a string. Empty String indicates no Pin Code. Yes distressPinCode String The numeric Distress Pin Code as a string. Empty String indicates no Distress Pin Code. Yes ownerBirthDate String The users birth date. The format should be MM/DD/YYYY (i.e. 12/25/1984). Yes ownerGender String The users gender. The values should be either M or F. Yes q1 String The first user profile question. Yes a1 String The answer to the first user question. Yes q2 String The second user profile question. Yes a2 String The answer to the second user question. Yes q3 String The third user profile question. Yes a3 String The answer to the third user question. Yes
Output
Name Data Type Description action Integer Defines the type of operation applied to the registered user.
Status Returned Value Query 0 AddChange 1 Delete 2 cellNumber String The Cell Number the operation was applied to ownerFName String The User's First Name. ownerLName String The User's Last Name. suppl1 String An additional identifier chosen by the customer. suppl2 String Another additional identifier chosen by the customer. textKeyMode Integer The TextKey validation mode.
Status Returned Value TextKeyOnly 0 PinCodeOnly 1 TextKeyPlusPin 2 Anything 3 receiveMode Integer The TextKey receive validation mode.
Status Returned Value AnyCode 0 SpecificCodeDisplay 1 SpecificCodeNoDisplay 2 RandomCode 3 UseDefault 4 pinCode String The numeric Pin Code. distressPinCode String The numeric Distress Pin Code. ownerBirthDate String The users birth date. The format should be MM/DD/YYYY (i.e. 12/25/1984). ownerGender String The users gender. The values should be either M or F. q1 String The first user profile question. a1 String The answer to the first user question. q2 String The second user profile question. a2 String The answer to the second user question. q3 String The third user profile question. a3 String The answer to the third user question.
REST Example
RESTful URL
The TextKey
Restful interface consists of the secure URL path followed by the appropriate CommandName.For instance:
https://secure.textkey.com/REST/TKRest.asmx/CommandName
The CommandName is the API call itself which in this case is registerTextKeyUserCSA.
Here is what the complete URL for this API call would look like:
https://secure.textkey.com/REST/TKRest.asmx/registerTextKeyUserCSA
All Restful calls must be made using the POST method and should be of the content type application/json.
Here is an example of what a request header should look like:
POST /REST/TKRest.asmx/registerTextKeyUserCSA HTTP/1.1 Host: secure.textkey.com Accept: */* Content-Type:application/json Content-Length: 584
JSON Input Payload
All TextKey
Restful service commands take a JSON object as the input and return a JSON object as the resulting payload. Authentication is handled via an API key as one of the parameters in the JSON input.The JSON Input payload for the registerTextKeyUserCSA API call should look something like this:
{ "DataIn": { "apiKey": "9021fa44-f1bc-4590-b975-42fee031e078", "command": "Query", "cellNumber": "8181231234", "ownerFName": "", "ownerLName": "", "ownerBirthDate": "", "ownerGender": "M", "suppl1": "", "suppl2": "", "userID": "", "isHashed": "true", "pinCode": "", "distressPinCode": "", "q1": "", "a1": "", "q2": "", "a2": "", "q3": "", "a3": "", "TextKeyMode": "TextKeyOnly", "ReceiveMode": "AnyCode" } }
JSON Output Payload
The JSON response should look something like this:
JSON Response with a valid payload
{ "d":{ "__type":"TextKeyCommon.TKStructures+RegisterTextKeyUserCSAReturn", "action":"0", "cellNumber":"8181231234", "ownerFName":"Stan", "ownerLName":"Steamer", "suppl1":"No", "suppl2":"Yes", "userID":"Stan", "textKeyMode":0, "receiveMode":0, "pinCode":"123", "distressPinCode":"1234", "ownerBirthDate":"12/25/1984", "ownerGender":"M", "q1":"q1", "a1":"a1", "q2":"q2", "a2":"a2", "q3":"q3", "a3":"a3", "errorDescr":"" } }
__type: TextKeyCommon.TKStructures+RegisterTextKeyUserCSAReturn action: 0 cellNumber: 8181231234 ownerFName: Stan ownerLName: Steamer suppl1: No suppl2: Yes userID: Stan textKeyMode: 0 receiveMode: 0 pinCode: 123 distressPinCode: 1234 ownerBirthDate: 12/25/1984 ownerGender: M q1: q1 a1: a1 q2: q2 a2: a2 q3: q3 a3: a3 errorDescr:
OR
JSON Response with an error
{ "d":{ "__type":"TextKeyCommon.TKStructures+RegisterTextKeyUserCSAReturn", "action":null, "cellNumber":null, "ownerFName":null, "ownerLName":null, "suppl1":null, "suppl2":null, "userID":null, "textKeyMode":0, "receiveMode":0, "pinCode":null, "distressPinCode":null, "ownerBirthDate":null, "ownerGender":null, "q1":null, "a1":null, "q2":null, "a2":null, "q3":null, "a3":null, "errorDescr":"Invalid Login" } }
Error: Invalid Login.
REST Code Examples
PHP
Example 1 - Using the TextKey
PHP Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKey object to handle all of the heavy lifting.You will be returned a PHP object and can reference all of the payload values directly from that object.
// Include the TextKey classes include_once("textkey_rest.php"); // Setup the API call parameters $Command = "Query"; $CellNumber = "8181231234"; $OwnerFName = ""; $OwnerLName = ""; $Suppl1 = ""; $Suppl2 = ""; $RegUserID = ""; $isHashed = TRUE; $PinCode = ""; $DistressPinCode = ""; $TextKeyMode = "TextKeyOnly"; $ReceiveMode = "AnyCode"; $Ownerbirthdate = ""; $Gender = ""; $q1 = ""; $a1 = ""; $q2 =""; $a2 = ""; $q3 = ""; $a3 = ""; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Create a TK object $tk = new textKey($apikey); // Handle the operation $textkey_result = $tk->perform_registerTextKeyUserCSA($Command, $CellNumber, $OwnerFName, $OwnerLName, $Suppl1, $Suppl2, $Ownerbirthdate, $Gender, $RegUserID, $isHashed, $PinCode, $DistressPinCode, $q1, $a1, $q2, $a2, $q3, $a3, $TextKeyMode, $ReceiveMode); // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } echo $results; } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; echo $results; }
Here is an example of the PHP object returned:
stdClass Object ( [__type] => TextKeyCommon.TKStructures+RegisterTextKeyUserCSAReturn [action] => [cellNumber] => [ownerFName] => [ownerLName] => [suppl1] => [suppl2] => [userID] => [textKeyMode] => 0 [receiveMode] => 0 [pinCode] => [distressPinCode] => [ownerBirthDate] => [ownerGender] => [q1] => [a1] => [q2] => [a2] => [q3] => [a3] => [errorDescr] => )
Example 2 - Using the REST API Call directly
In order to use the TextKey
REST API calls directly, you will need to setup the API payload using the appropriate parameters and the API key formatted as a JSON string and then make a CURL POST request.The POST header does need to be setup as a JSON request (i.e. an application/json header) or you will not get a response.
You will be returned a JSON string as the API call payload. That can be converted into a PHP object using the json_decode call.
// TextKey REST path define('TK_REST', 'https://secure.textkey.com/REST/TKRest.asmx/'); // Setup the API call parameters $Command = "Query"; $CellNumber = "8181231234"; $OwnerFName = ""; $OwnerLName = ""; $Suppl1 = ""; $Suppl2 = ""; $RegUserID = ""; $isHashed = TRUE; $PinCode = ""; $DistressPinCode = ""; $TextKeyMode = "TextKeyOnly"; $ReceiveMode = "AnyCode"; $Ownerbirthdate = ""; $Gender = ""; $q1 = ""; $a1 = ""; $q2 =""; $a2 = ""; $q3 = ""; $a3 = ""; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Build the REST API URL $url = TK_REST . 'registerTextKeyUserCSA'; // Setup data $postdata = json_encode( array('DataIn' => array( 'apiKey' => urlencode($apikey), 'command' => urlencode($Command), 'cellNumber' => urlencode($CellNumber), 'ownerFName' => urlencode($OwnerFName), 'ownerLName' => urlencode($OwnerLName), 'suppl1' => urlencode($Suppl1), 'suppl2' => urlencode($Suppl2), 'userID' => urlencode($RegUserID), 'isHashed' => urlencode($isHashed?"true":"false"), 'pinCode' => urlencode($PinCode), 'ownerBirthDate' => urlencode($Ownerbirthdate), 'ownerGender' => urlencode($Gender), 'q1' => urlencode($q1), 'a1' => urlencode($a1), 'q2' => urlencode($q2), 'a2' => urlencode($a2), 'q3' => urlencode($q3), 'a3' => urlencode($a3), 'distressPinCode' => urlencode($DistressPinCode), 'distressPinCode' => urlencode($DistressPinCode), 'TextKeyMode' => urlencode($TextKeyMode), 'ReceiveMode' => urlencode($ReceiveMode) ) ), JSON_PRETTY_PRINT); // Handle the API request via CURL $curl = curl_init($url); // Set the CURL params and make sure it is a JSON request curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); curl_setopt($curl, CURLOPT_POST, true); curl_setopt($curl, CURLOPT_POSTFIELDS, $postdata); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json')); curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0); // Wildcard certificate $response = curl_exec($curl); curl_close($curl); // Handle the payload $textkey_payload = json_decode($response); if ($textkey_payload->d) { $textkey_result = $textkey_payload->d; } else { $textkey_result = $textkey_payload; }; // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } echo $results; } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; echo $results; }
JAVA
Example - Using the TextKey
JAVA Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKeyRest object to handle all of the heavy lifting.You will be returned a JSON string.
package com.textkey.rest.examples; import org.json.JSONObject; import com.textkey.rest.TextKeyRest; public class TestRegisterTextKeyUserCSA { public static void main(String[] args) { /* Setup */ String TK_API = "9021fa44-f1bc-4590-b975-42fee031e078"; /* Create the TextKey object */ TextKeyRest textkey = new TextKeyRest(TK_API, false); /* Setup the API call parameters */ Integer Command = 1; String CellNumber = "8181231234"; String OwnerFName = "Stan"; String OwnerLName = ""; String Suppl1 = "Suppl1"; String Suppl2 = "Suppl2"; String ownerBirthDate = "01/01/1970"; String ownerGender = "M"; String UserID = "Stan"; String isHashed = "TRUE"; String PinCode = "1234"; String DistressPinCode = "4321"; String q1 = "Question 1"; String a1 = "Answer 1"; String q2 = "Question 2"; String a2 = "Answer 2"; String q3 = "Question 3"; String a3 = "Answer 3"; Integer TextKeyMode = 0; Integer ReceiveMode = 0; /* Make the REST API Call */ String JSONpayload = textkey.perform_registerTextKeyUserCSA(Command, CellNumber, OwnerFName, OwnerLName, Suppl1, Suppl2, ownerBirthDate, ownerGender, UserID, isHashed, PinCode, DistressPinCode, q1, a1, q2, a2, q3, a3, TextKeyMode, ReceiveMode); /* Display the API Results */ try { JSONObject results = new JSONObject(JSONpayload).getJSONObject("d"); System.out.println("Test Results: \n" + TextKeyRest.toPrettyFormat(results.toString())); } catch(Exception pe){ pe.printStackTrace(); } } }
Here is an example of the JSON string with the d wrapper removed:
Test Results: { "receiveMode": 0, "q2": "Question 1", "q1": "Question 2", "q3": "Question 3", "ownerGender": "M", "cellNumber": "8051231234", "ownerLName": "", "distressPinCode": "4321", "__type": "TextKeyCommon.TKStructures+RegisterTextKeyUserCSAReturn", "ownerFName": "Stan", "userID": "Stan", "pinCode": "1234", "textKeyMode": 0, "suppl1": "Suppl1", "a1": "Answer 1", "a2": "Answer 2", "a3": "Answer 3", "suppl2": "Suppl2", "ownerBirthDate": "1/1/1970" }
NOTE: For more detais on the JAVA Library object and methods, you can take a look at the online documentation at http://textpower.github.io/RESTLibrary-java/.
RUBY
Example - Using the TextKey
RUBY Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKeyRest object to handle all of the heavy lifting.You will be returned a JSON string.
NOTE: To install the textkey_rest gem you can run gem install textkey_rest from a command line. To build the testkey_rest gem locally, get the latest repository at github and follow the instructions.
require 'json' require 'textkey_rest' # Setup apiKey = "9021fa44-f1bc-4590-b975-42fee031e078" # Create the textkey object textkey = TextKeyRest.new(apiKey, false) # Setup the API parameters command = 1 cellNumber = "8181231234" ownerFName = "Stan" ownerLName = "" suppl1 = "Suppl1" suppl2 = "Suppl2" ownerBirthDate = "01/01/1970" ownerGender = "M" userID = "Stan" isHashed = "TRUE" pinCode = "1234" distressPinCode = "4321" q1 = "Question 1" a1 = "Answer 1" q2 = "Question 2" a2 = "Answer 2" q3 = "Question 3" a3 = "Answer 3" textKeyMode = 0 receiveMode = 0 # Make the API Call response = textkey.perform_registerTextKeyUserCSA(command, cellNumber, ownerFName, ownerLName, suppl1, suppl2, ownerBirthDate, ownerGender, userID, isHashed, pinCode, distressPinCode, q1, a1, q2, a2, q3, a3, textKeyMode, receiveMode) # Pull out the data from the response response_obj = JSON.parse(response) response_data = response_obj['d'] # Display the response puts "TextKey Results:" puts JSON.pretty_generate response_data
Here is an example of the JSON string with the d wrapper removed:
Test Results: { "receiveMode": 0, "q2": "Question 1", "q1": "Question 2", "q3": "Question 3", "ownerGender": "M", "cellNumber": "8051231234", "ownerLName": "", "distressPinCode": "4321", "__type": "TextKeyCommon.TKStructures+RegisterTextKeyUserCSAReturn", "ownerFName": "Stan", "userID": "Stan", "pinCode": "1234", "textKeyMode": 0, "suppl1": "Suppl1", "a1": "Answer 1", "a2": "Answer 2", "a3": "Answer 3", "suppl2": "Suppl2", "ownerBirthDate": "1/1/1970" }
NOTE: For more detais on the RUBY Library object and methods, you can take a look at the online documentation at http://textpower.github.io/RESTLibrary-ruby/.
Javascript
All of the TextKey
REST API calls are CORS compliant so they can be called via an Ajax request with no cross domain issues.In order to user the TextKey
REST API calls via javascript, you will need to setup the API payload using the appropriate parameters and the API key formatted as a JSON string and then make an Ajax POST request. The POST header does need to be setup as a JSON request (i.e. an application/json header) or you will not get a response.You will be returned a JSON string as the API call payload.
NOTE: Exposing your API key via any client side code is not recommended. If you choose to use the TextKey
API calls via a Javascript call, make sure to create a temporary API Key using the getTempAPIKey API call server side and then use that temporary key during its lifespan on any client side API calls.<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script> <script type="text/javascript"> // Build a class to handle the API call input payload function textkeyPayload(apiKey, command, cellNumber, ownerFName, ownerLName, suppl1, suppl2, userID, isHashed, pinCode, distressPinCode, ownerBirthDate, ownerGender, q1, a1, q2, a2, q3, a3, TextKeyMode, ReceiveMode) { this.apiKey = apiKey; this.command = command; this.cellNumber = cellNumber; this.ownerFName = ownerFName; this.ownerLName = ownerLName; this.suppl1 = suppl1; this.suppl2 = suppl2; this.userID = userID; this.isHashed = isHashed; this.pinCode = pinCode; this.distressPinCode = distressPinCode; this.ownerBirthDate = ownerBirthDate; this.ownerGender = ownerGender; this.q1 = q1; this.a1 = a1; this.q2 = q2; this.a2 = a2; this.q3 = q3; this.a3 = a3; this.TextKeyMode = TextKeyMode; this.ReceiveMode = ReceiveMode; this.toJsonString = function () { return JSON.stringify({ 'DataIn': this }); }; }; // Handle the API Request and response function textkeyAPIRequest(txtCommand, APIJSONData) { // Setup the API URL var urlAPI = 'http://www.textkey.com/REST/TKRest.asmx/'+txtCommand; // Make the API call via a JSON Ajax request $.ajax({ type: "POST", contentType: "application/json; charset=utf-8", url: urlAPI, data: APIJSONData, dataType: "json", success: function (APIResponse, textStatus) { document.write("textStatus: "+textStatus+ "<HR>"); document.write("API Response: "+JSON.stringify(APIResponse, null, 4) + "<HR>"); if (textStatus == 'success') { if (APIResponse.hasOwnProperty('d')) { APIPayload = APIResponse.d; } else { APIPayload = APIResponse; } document.write("API Payload: "+JSON.stringify(APIPayload, null, 4) + "<HR>"); if (APIPayload.errorDescr == "") { document.write("userID: " + APIPayload.userID); } else { document.write("Error: " + APIPayload.errorDescr); } } else { document.write("Error: " + textStatus); } }, error: function (jqXHR, textStatus, errorThrown) { document.write("Error: " + jqXHR.status); } }); } // Setup the API command var txtCommand = 'registerTextKeyUserCSA'; // Build the API payload var registerTextKeyUserCSA = new textkeyPayload("9021fa44-f1bc-4590-b975-42fee031e078", "Query", "8181231234", "", "", "", "", "", true, "", "", "", "", "", "", "", "", "", "", "TextKeyOnly", "AnyCode"); // Make the API Call textkeyAPIRequest(txtCommand, registerTextKeyUserCSA.toJsonString()); </script>
SOAP Example
- Step 1 - Authentication Settings
- Step 2 - Call Parameters
- Step 3 - SOAP Request
- Step 4 - SOAP Response
- Step 5 - Output Results
Authentication Settings
A SOAP header is required on all SOAP API calls using the _Key variant and the header information is identical on all calls.
registerTextKeyUserCSA requires a SOAP header.
registerTextKeyUserCSA_Key does not require a SOAP header but uses the API Key in the body of the SOAP request.Authentication Settings using an API Key
API Key: 9021fa44-f1bc-4590-b975-42fee031e078
OR
Authentication Settings using an UserID/Password Combination
userId: 1ed93006208f0540e452e3a37d8299bc
Password: Password12345
Campaign:
Keyword:The WSDL document for the TextKey
SOAP interface is located at: https://secure.textkey.com/ws/textkey.asmx?wsdl.The address for the SOAP calls on the TextKey
interface is: https://secure.textkey.com/ws/textkey.asmx.The name space for the SOAP calls on the TextKey
interface is: https://secure.textkey.com/services/.Call Parameters
The parameters should look something like this:
apiKey: 9021fa44-f1bc-4590-b975-42fee031e078 command: Query cellNumber: 850410576 ownerFName: ownerLName: suppl1: suppl2: userID: isHashed: 1 pinCode: distressPinCode: ownerBirthDate: ownerGender: M q1: a1: q2: a2: q3: a3: TextKeyMode: TextKeyOnly ReceiveMode: AnyCode
SOAP Request
The SOAP request should look something like this:
SOAP Request using the API Key
OR
SOAP Request using the UserID/Password
SOAP Response
The SOAP response should look something like this:
SOAP Response with an valid payload
OR
SOAP Response with an error
Output Results
The final results will need to be extracted from the XML response payload should look something like this:
SOAP Response with a valid payload
stdClass Object ( [action] => 0 [cellNumber] => 8181231234 [ownerFName] => Stan [ownerLName] => Steamer [suppl1] => No [suppl2] => Yes [userID] => Stan [textKeyMode] => TextKeyOnly [receiveMode] => AnyCode [pinCode] => 123 [distressPinCode] => 1234 [ownerBirthDate] => 12/25/1984 [ownerGender] => M [q1] => q1 [a1] => a1 [q2] => q2 [a2] => a2 [q3] => q3 [a3] => a3 [errorDescr] => )
action: 0 cellNumber: 8181231234 ownerFName: Stan ownerLName: Steamer suppl1: No suppl2: Yes userID: Stan textKeyMode: TextKeyOnly receiveMode: AnyCode pinCode: 123 distressPinCode: 1234 ownerBirthDate: 12/25/1984 ownerGender: M q1: q1 a1: a1 q2: q2 a2: a2 q3: q3 a3: a3 errorDescr:
OR
SOAP Response with an error
stdClass Object ( [textKeyMode] => TextKeyOnly [receiveMode] => AnyCode [errorDescr] => Invalid Login )
Error: Invalid Login.
SOAP Code Examples
PHP
The PHP Helper library contain a textkey class that makes calling TextKey
SOAP API functions simple. Just include the helper file textkey_soap.php in your PHP code, inititalize a textkey object using your credentials (i.e. either an API key or a UserID/Password), and then make the API call with the appropriate parameters. You will be returned an object with the API call payload.// Include the TextKey classes include_once("../textkey_soap.php"); // Setup the API call parameters $Command = "Query"; $CellNumber = "8181231234"; $OwnerFName = ""; $OwnerLName = ""; $Suppl1 = ""; $Suppl2 = ""; $RegUserID = ""; $isHashed = TRUE; $PinCode = ""; $DistressPinCode = ""; $TextKeyMode = "TextKeyOnly"; $ReceiveMode = "AnyCode"; $Ownerbirthdate = ""; $Gender = ""; $q1 = ""; $a1 = ""; $q2 =""; $a2 = ""; $q3 = ""; $a3 = ""; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Create a textkey object if ($apikey != "") { $tk = new textKey("", "", "", "", $apikey); } // Handle the operation $textkey_result = $tk->perform_registerTextKeyUserCSA($Command, $CellNumber, $OwnerFName, $OwnerLName, $Suppl1, $Suppl2, $Ownerbirthdate, $Gender, $RegUserID, $isHashed, $PinCode, $DistressPinCode, $q1, $a1, $q2, $a2, $q3, $a3, $TextKeyMode, $ReceiveMode); // Show the textkey API payload object print_r($textkey_result); echo "<HR>"; // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; } echo $results;
CURL
From a command line, you can test the SOAP API calls using a CURL request:
The SOAP registerTextKeyUserCSA Request is stored in a file called registerTextKeyUserCSA.xml
<?xml version="1.0" encoding="UTF-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" > <soap:Body> <registerTextKeyUserCSA_Key xmlns="https://secure.textkey.com/services/"> <apiKey>9021fa44-f1bc-4590-b975-42fee031e078</apiKey> <command>Query</command> <cellNumber>850410576</cellNumber> <ownerFName> </ownerFName> <ownerLName> </ownerLName> <suppl1> </suppl1> <suppl2> </suppl2> <userID> </userID> <isHashed>true</isHashed> <TextKeyMode>TextKeyOnly</TextKeyMode> <ReceiveMode>AnyCode</ReceiveMode> <pinCode> </pinCode> <distressPinCode> </distressPinCode> <ownerGender>M</ownerGender> <q1> </q1> <a1> </a1> <q2> </q2> <a2> </a2> <q3> </q3> <a3> </a3> </registerTextKeyUserCSA_Key> </soap:Body> </soap:Envelope>
CURL command using registerTextKeyUserCSA.xml
curl -H "Content-Type: text/xml; charset=utf-8" -H "SOAPAction:" -d @registerTextKeyUserCSA.xml -X POST https://secure.textkey.com/ws/textkey.asmx
XML Response from API registerTextKeyUserCSA Request
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Body> <registerTextKeyUserCSA_KeyResponse xmlns="https://secure.textkey.com/services/"> <registerTextKeyUserCSA_KeyResult> <action>0</action> <cellNumber>8181231234</cellNumber> <ownerFName>Stan</ownerFName> <ownerLName>Steamer</ownerLName> <suppl1>No</suppl1> <suppl2>Yes</suppl2> <userID>Stan</userID> <textKeyMode>TextKeyOnly</textKeyMode> <receiveMode>AnyCode</receiveMode> <pinCode>123</pinCode> <distressPinCode>1234</distressPinCode> <ownerBirthDate>12/25/1984</ownerBirthDate> <ownerGender>M</ownerGender> <q1>q1</q1> <a1>a1</a1> <q2>q2</q2> <a2>a2</a2> <q3>q3</q3> <a3>a3</a3> <errorDescr /> </registerTextKeyUserCSA_KeyResult> </registerTextKeyUserCSA_KeyResponse> </soap:Body> </soap:Envelope>
-
getTextKeyRegistration
Description
The getTextKeyRegistration API call allows you to retrieve a registration entry for any user. An entry can be retrieved either by its Cell Number or by one or both supplementart fields that can be set to any relevant data on the user such as their payroll ID.
API Testing Page
To test the getTextKeyRegistration API Call in a fully interactive environment, click here.
Input Parameters
Name Data Type Description Required apiKey String This is a unique key that is used to authenticate an API request. It should never be exposed. With the _Key function retrieveBy Integer Defines the type of retrieve option to use.
Option Value ByCellNumber 0 BySuppl1 1 BySuppl2 2 BySuppl1ANDSuppl2 2 Yes cellNumber String The Cell Number that you are searching for if part of the above selection criterion. Ignored otherwise. Yes suppl1 String The suppl1 field value that you are searching for if part of the above selection criterion. Ignored otherwise. Yes suppl2 String The suppl2 field value that you are searching for if part of the above selection criterion. Ignored otherwise. Yes
Output
Name Data Type Description action Integer Defines the type of operation applied to the registered user.
Status Returned Value Query 0 AddChange 1 Delete 2 cellNumber String The Cell Number the operation was applied to ownerFName String The User's First Name. ownerLName String The User's Last Name. suppl1 String An additional identifier chosen by the customer. suppl2 String Another additional identifier chosen by the customer. textKeyMode Integer The TextKey validation mode.
Status Returned Value TextKeyOnly 0 PinCodeOnly 1 TextKeyPlusPin 2 Anything 3 receiveMode Integer The TextKey receive validation mode.
Status Returned Value AnyCode 0 SpecificCodeDisplay 1 SpecificCodeNoDisplay 2 RandomCode 3 UseDefault 4 pinCode String The numeric Pin Code. distressPinCode String The numeric Distress Pin Code. ownerBirthDate String The users birth date. The format should be MM/DD/YYYY (i.e. 12/25/1984). ownerGender String The users gender. The values should be either M or F. q1 String The first user profile question. a1 String The answer to the first user question. q2 String The second user profile question. a2 String The answer to the second user question. q3 String The third user profile question. a3 String The answer to the third user question.
REST Example
RESTful URL
The TextKey
Restful interface consists of the secure URL path followed by the appropriate CommandName.For instance:
https://secure.textkey.com/REST/TKRest.asmx/CommandName
The CommandName is the API call itself which in this case is getTextKeyRegistration.
Here is what the complete URL for this API call would look like:
https://secure.textkey.com/REST/TKRest.asmx/getTextKeyRegistration
All Restful calls must be made using the POST method and should be of the content type application/json.
Here is an example of what a request header should look like:
POST /REST/TKRest.asmx/getTextKeyRegistration HTTP/1.1 Host: secure.textkey.com Accept: */* Content-Type:application/json Content-Length: 200
JSON Input Payload
All TextKey
Restful service commands take a JSON object as the input and return a JSON object as the resulting payload. Authentication is handled via an API key as one of the parameters in the JSON input.The JSON Input payload for the getTextKeyRegistration API call should look something like this:
{ "DataIn": { "apiKey": "9021fa44-f1bc-4590-b975-42fee031e078", "retrieveBy": "ByCellNumber", "cellNumber": "8181231234", "suppl1": "", "suppl2": "" } }
JSON Output Payload
The JSON response should look something like this:
JSON Response with a valid payload
{ "d":{ "__type":"TextKeyCommon.TKStructures+getTextKeyRegistrationReturn", "action":null, "cellNumber":"8181231234", "ownerFName":"Stan", "ownerLName":"Steamer", "suppl1":"No", "suppl2":"Yes", "userID":"Stan", "textKeyMode":0, "receiveMode":0, "pinCode":"123", "distressPinCode":"1234", "ownerBirthDate":"12/25/1984", "ownerGender":"M", "q1":"q1", "a1":"a1", "q2":"q2", "a2":"a2", "q3":"q3", "a3":"a3", "errorDescr":"" } }
__type: TextKeyCommon.TKStructures+getTextKeyRegistrationReturn action: cellNumber: 8181231234 ownerFName: Stan ownerLName: Steamer suppl1: No suppl2: Yes userID: Stan textKeyMode: 0 receiveMode: 0 pinCode: 123 distressPinCode: 1234 ownerBirthDate: 12/25/1984 ownerGender: M q1: q1 a1: a1 q2: q2 a2: a2 q3: q3 a3: a3 errorDescr:
OR
JSON Response with an error
{ "d":{ "__type":"TextKeyCommon.TKStructures+getTextKeyRegistrationReturn", "action":null, "cellNumber":null, "ownerFName":null, "ownerLName":null, "suppl1":null, "suppl2":null, "userID":null, "textKeyMode":0, "receiveMode":0, "pinCode":null, "distressPinCode":null, "ownerBirthDate":null, "ownerGender":null, "q1":null, "a1":null, "q2":null, "a2":null, "q3":null, "a3":null, "errorDescr":"Invalid Login" } }
Error: Invalid Login.
REST Code Examples
PHP
Example 1 - Using the TextKey
PHP Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKey object to handle all of the heavy lifting.You will be returned a PHP object and can reference all of the payload values directly from that object.
// Include the TextKey classes include_once("textkey_rest.php"); // Setup the API call parameters $RetrieveBy = "ByCellNumber"; $CellNumber = "8181231234"; $Suppl1 = ""; $Suppl2 = ""; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Create a TK object $tk = new textKey($apikey); // Handle the operation $textkey_result = $tk->perform_getTextKeyRegistration($RetrieveBy, $CellNumber, $Suppl1, $Suppl2); // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } echo $results; } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; echo $results; }
Here is an example of the PHP object returned:
stdClass Object ( [__type] => TextKeyCommon.TKStructures+getTextKeyRegistrationReturn [action] => [cellNumber] => 8051231234 [ownerFName] => Stan [ownerLName] => [suppl1] => Suppl1 [suppl2] => Suppl2 [userID] => Stan [textKeyMode] => 0 [receiveMode] => 0 [pinCode] => 1234 [distressPinCode] => 4321 [ownerBirthDate] => 1/1/1970 [ownerGender] => [q1] => [a1] => [q2] => [a2] => [q3] => [a3] => [errorDescr] => )
Example 2 - Using the REST API Call directly
In order to use the TextKey
REST API calls directly, you will need to setup the API payload using the appropriate parameters and the API key formatted as a JSON string and then make a CURL POST request.The POST header does need to be setup as a JSON request (i.e. an application/json header) or you will not get a response.
You will be returned a JSON string as the API call payload. That can be converted into a PHP object using the json_decode call.
// TextKey REST path define('TK_REST', 'https://secure.textkey.com/REST/TKRest.asmx/'); // Setup the API call parameters $RetrieveBy = "ByCellNumber"; $CellNumber = "8181231234"; $Suppl1 = ""; $Suppl2 = ""; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Build the REST API URL $url = TK_REST . 'getTextKeyRegistration'; // Setup data $postdata = json_encode( array('DataIn' => array( 'apiKey' => urlencode($apikey), 'cellNumber' => urlencode($CellNumber), 'suppl1' => urlencode($Suppl1), 'suppl2' => urlencode($Suppl2), 'retrieveBy' => urlencode($RetrieveBy), 'TextKeyMode' => urlencode($TextKeyMode), 'ReceiveMode' => urlencode($ReceiveMode) ) ), JSON_PRETTY_PRINT); // Handle the API request via CURL $curl = curl_init($url); // Set the CURL params and make sure it is a JSON request curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); curl_setopt($curl, CURLOPT_POST, true); curl_setopt($curl, CURLOPT_POSTFIELDS, $postdata); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json')); curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0); // Wildcard certificate $response = curl_exec($curl); curl_close($curl); // Handle the payload $textkey_payload = json_decode($response); if ($textkey_payload->d) { $textkey_result = $textkey_payload->d; } else { $textkey_result = $textkey_payload; }; // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } echo $results; } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; echo $results; }
JAVA
Example - Using the TextKey
JAVA Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKeyRest object to handle all of the heavy lifting.You will be returned a JSON string.
package com.textkey.rest.examples; import org.json.JSONObject; import com.textkey.rest.TextKeyRest; public class TestGetTextKeyRegistration { public static void main(String[] args) { /* Setup */ String TK_API = "9021fa44-f1bc-4590-b975-42fee031e078"; /* Create the TextKey object */ TextKeyRest textkey = new TextKeyRest(TK_API, false); /* Setup the API call parameters */ Integer RetrieveBy = 0; String CellNumber = "8181231234"; String Suppl1 = ""; String Suppl2 = ""; /* Make the REST API Call */ String JSONpayload = textkey.perform_getTextKeyRegistration(RetrieveBy, CellNumber, Suppl1, Suppl2); /* Display the API Results */ try { JSONObject results = new JSONObject(JSONpayload).getJSONObject("d"); System.out.println("Test Results: \n" + TextKeyRest.toPrettyFormat(results.toString())); } catch(Exception pe){ pe.printStackTrace(); } } }
Here is an example of the JSON string with the d wrapper removed:
Test Results: { "receiveMode": 0, "q2": "", "q1": "", "errorDescr": "", "q3": "", "ownerGender": " ", "cellNumber": "8051231234", "ownerLName": "", "distressPinCode": "4321", "__type": "TextKeyCommon.TKStructures+RegisterTextKeyUserCSAReturn", "ownerFName": "Stan", "userID": "Stan", "pinCode": "1234", "textKeyMode": 0, "suppl1": "Suppl1", "a1": "", "a2": "", "a3": "", "suppl2": "Suppl2", "ownerBirthDate": "1/1/1970" }
NOTE: For more detais on the JAVA Library object and methods, you can take a look at the online documentation at http://textpower.github.io/RESTLibrary-java/.
RUBY
Example - Using the TextKey
RUBY Helper LibraryThe simplest way to use TextKey
REST API calls, is to include the TextKey REST Helper Library and then use the TextKeyRest object to handle all of the heavy lifting.You will be returned a JSON string.
NOTE: To install the textkey_rest gem you can run gem install textkey_rest from a command line. To build the testkey_rest gem locally, get the latest repository at github and follow the instructions.
require 'json' require 'textkey_rest' # Setup apiKey = "9021fa44-f1bc-4590-b975-42fee031e078" # Create the textkey object textkey = TextKeyRest.new(apiKey, false) # Setup the API parameters retrieveBy = 0 cellNumber = "8051231234" suppl1 = "" suppl2 = "" # Make the API Call response = textkey.perform_getTextKeyRegistration(retrieveBy, cellNumber, suppl1, suppl2) # Pull out the data from the response response_obj = JSON.parse(response) response_data = response_obj['d'] # Display the response puts "TextKey Results:" puts JSON.pretty_generate response_data
Here is an example of the JSON string with the d wrapper removed:
Test Results: { "receiveMode": 0, "q2": "", "q1": "", "errorDescr": "", "q3": "", "ownerGender": " ", "cellNumber": "8051231234", "ownerLName": "", "distressPinCode": "4321", "__type": "TextKeyCommon.TKStructures+RegisterTextKeyUserCSAReturn", "ownerFName": "Stan", "userID": "Stan", "pinCode": "1234", "textKeyMode": 0, "suppl1": "Suppl1", "a1": "", "a2": "", "a3": "", "suppl2": "Suppl2", "ownerBirthDate": "1/1/1970" }
NOTE: For more detais on the RUBY Library object and methods, you can take a look at the online documentation at http://textpower.github.io/RESTLibrary-ruby/.
Javascript
All of the TextKey
REST API calls are CORS compliant so they can be called via an Ajax request with no cross domain issues.In order to user the TextKey
REST API calls via javascript, you will need to setup the API payload using the appropriate parameters and the API key formatted as a JSON string and then make an Ajax POST request. The POST header does need to be setup as a JSON request (i.e. an application/json header) or you will not get a response.You will be returned a JSON string as the API call payload.
NOTE: Exposing your API key via any client side code is not recommended. If you choose to use the TextKey
API calls via a Javascript call, make sure to create a temporary API Key using the getTempAPIKey API call server side and then use that temporary key during its lifespan on any client side API calls.<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script> <script type="text/javascript"> // Build a class to handle the API call input payload function textkeyPayload(apiKey, cellNumber, suppl1, suppl2, retrieveBy) { this.apiKey = apiKey; this.cellNumber = cellNumber; this.suppl1 = suppl1; this.suppl2 = suppl2; this.retrieveBy = retrieveBy; this.toJsonString = function () { return JSON.stringify({ 'DataIn': this }); }; }; // Handle the API Request and response function textkeyAPIRequest(txtCommand, APIJSONData) { // Setup the API URL var urlAPI = 'http://www.textkey.com/REST/TKRest.asmx/'+txtCommand; // Make the API call via a JSON Ajax request $.ajax({ type: "POST", contentType: "application/json; charset=utf-8", url: urlAPI, data: APIJSONData, dataType: "json", success: function (APIResponse, textStatus) { document.write("textStatus: "+textStatus+ "<HR>"); document.write("API Response: "+JSON.stringify(APIResponse, null, 4) + "<HR>"); if (textStatus == 'success') { if (APIResponse.hasOwnProperty('d')) { APIPayload = APIResponse.d; } else { APIPayload = APIResponse; } document.write("API Payload: "+JSON.stringify(APIPayload, null, 4) + "<HR>"); if (APIPayload.errorDescr == "") { document.write("userID: " + APIPayload.userID); } else { document.write("Error: " + APIPayload.errorDescr); } } else { document.write("Error: " + textStatus); } }, error: function (jqXHR, textStatus, errorThrown) { document.write("Error: " + jqXHR.status); } }); } // Setup the API command var txtCommand = 'getTextKeyRegistration'; // Build the API payload var getTextKeyRegistration = new textkeyPayload("9021fa44-f1bc-4590-b975-42fee031e078", "8181231234", "", "", "ByCellNumber"); // Make the API Call textkeyAPIRequest(txtCommand, getTextKeyRegistration.toJsonString()); </script>
SOAP Example
- Step 1 - Authentication Settings
- Step 2 - Call Parameters
- Step 3 - SOAP Request
- Step 4 - SOAP Response
- Step 5 - Output Results
Authentication Settings
A SOAP header is required on all SOAP API calls using the _Key variant and the header information is identical on all calls.
getTextKeyRegistration requires a SOAP header.
getTextKeyRegistration_Key does not require a SOAP header but uses the API Key in the body of the SOAP request.Authentication Settings using an API Key
API Key: 9021fa44-f1bc-4590-b975-42fee031e078
OR
Authentication Settings using an UserID/Password Combination
userId: 1ed93006208f0540e452e3a37d8299bc
Password: Password12345
Campaign:
Keyword:The WSDL document for the TextKey
SOAP interface is located at: https://secure.textkey.com/ws/textkey.asmx?wsdl.The address for the SOAP calls on the TextKey
interface is: https://secure.textkey.com/ws/textkey.asmx.The name space for the SOAP calls on the TextKey
interface is: https://secure.textkey.com/services/.Call Parameters
The parameters should look something like this:
apiKey: 9021fa44-f1bc-4590-b975-42fee031e078 retrieveBy: ByCellNumber cellNumber: 8181231234 suppl1: suppl2:
SOAP Request
The SOAP request should look something like this:
SOAP Request using the API Key
OR
SOAP Request using the UserID/Password
SOAP Response
The SOAP response should look something like this:
SOAP Response with an valid payload
OR
SOAP Response with an error
Output Results
The final results will need to be extracted from the XML response payload should look something like this:
SOAP Response with a valid payload
stdClass Object ( [action] => 0 [cellNumber] => 8181231234 [ownerFName] => Stan [ownerLName] => Steamer [suppl1] => No [suppl2] => Yes [userID] => Stan [textKeyMode] => TextKeyOnly [receiveMode] => AnyCode [pinCode] => 123 [distressPinCode] => 1234 [ownerBirthDate] => 12/25/1984 [ownerGender] => M [q1] => q1 [a1] => a1 [q2] => q2 [a2] => a2 [q3] => q3 [a3] => a3 [errorDescr] => )
action: 0 cellNumber: 8181231234 ownerFName: Stan ownerLName: Steamer suppl1: No suppl2: Yes userID: Stan textKeyMode: TextKeyOnly receiveMode: AnyCode pinCode: 123 distressPinCode: 1234 ownerBirthDate: 12/25/1984 ownerGender: M q1: q1 a1: a1 q2: q2 a2: a2 q3: q3 a3: a3 errorDescr:
OR
SOAP Response with an error
stdClass Object ( [textKeyMode] => TextKeyOnly [receiveMode] => AnyCode [errorDescr] => Invalid Login )
Error: Invalid Login.
SOAP Code Examples
PHP
The PHP Helper library contain a textkey class that makes calling TextKey
SOAP API functions simple. Just include the helper file textkey_soap.php in your PHP code, inititalize a textkey object using your credentials (i.e. either an API key or a UserID/Password), and then make the API call with the appropriate parameters. You will be returned an object with the API call payload.// Include the TextKey classes include_once("../textkey_soap.php"); // Setup the API call parameters $RetrieveBy = "ByCellNumber"; $CellNumber = "8181231234"; $Suppl1 = ""; $Suppl2 = ""; // Set the authentication $apikey = "9021fa44-f1bc-4590-b975-42fee031e078"; // Create a textkey object if ($apikey != "") { $tk = new textKey("", "", "", "", $apikey); } // Handle the operation $textkey_result = $tk->perform_getTextKeyRegistration($RetrieveBy, $CellNumber, $Suppl1, $Suppl2); // Show the textkey API payload object print_r($textkey_result); echo "<HR>"; // Handle the results if ($textkey_result->errorDescr == "") { $tkResultsArr = get_object_vars($textkey_result); $results = ""; foreach($tkResultsArr as $key => $value) { $results .= $key . ': ' . $value . "<BR>"; } } else { $results = 'Error: ' . $textkey_result->errorDescr . "<BR>"; } echo $results;
CURL
From a command line, you can test the SOAP API calls using a CURL request:
The SOAP getTextKeyRegistration Request is stored in a file called getTextKeyRegistration.xml
<?xml version="1.0" encoding="UTF-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" > <soap:Body> <getTextKeyRegistration_Key xmlns="https://secure.textkey.com/services/"> <apiKey>9021fa44-f1bc-4590-b975-42fee031e078</apiKey> <retrieveBy>ByCellNumber</retrieveBy> <cellNumber>8181231234</cellNumber> <suppl1> </suppl1> <suppl2> </suppl2> </getTextKeyRegistration_Key> </soap:Body> </soap:Envelope>
CURL command using getTextKeyRegistration.xml
curl -H "Content-Type: text/xml; charset=utf-8" -H "SOAPAction:" -d @getTextKeyRegistration.xml -X POST https://secure.textkey.com/ws/textkey.asmx
XML Response from API getTextKeyRegistration Request
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Body> <getTextKeyRegistration_KeyResponse xmlns="https://secure.textkey.com/services/"> <getTextKeyRegistration_KeyResult> <cellNumber>8181231234</cellNumber> <ownerFName>Stan</ownerFName> <ownerLName>Steamer</ownerLName> <suppl1>No</suppl1> <suppl2>Yes</suppl2> <userID>Stan</userID> <textKeyMode>TextKeyOnly</textKeyMode> <receiveMode>AnyCode</receiveMode> <pinCode>123</pinCode> <distressPinCode>1234</distressPinCode> <ownerBirthDate>12/25/1984</ownerBirthDate> <ownerGender>M</ownerGender> <q1>q1</q1> <a1>a1</a1> <q2>q2</q2> <a2>a2</a2> <q3>q3</q3> <a3>a3</a3> <errorDescr /> </getTextKeyRegistration_KeyResult> </getTextKeyRegistration_KeyResponse> </soap:Body> </soap:Envelope>
TextKey Technical Documentation
Here are a couple of links if you want to download a hard copy of the TextKey