API Documentation - TextKey™ APIs

TextKey™ API Calls

Here you can find details on each of our TextKey™ API calls. To see the details for any specific call, just click on the API Name in the list below and it will expand to show you the API Call details including a description, input and output parameters. and code examples.

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 Library

    The 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 Library

    The 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 Library

    The 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

    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: 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
(
    [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 Library

    The 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 Library

    The 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 Library

    The 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

    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 Library

    The 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 Library

    The 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 Library

    The 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

    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: 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
(
    [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 Library

    The 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 Library

    The 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 Library

    The 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

    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 Library

    The 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 Library

    The 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 Library

    The 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

    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 Library

    The 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 Library

    The 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 Library

    The 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

    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 Library

    The 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 Library

    The 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 Library

    The 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

    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 Library

    The 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 Library

    The 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 Library

    The 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

    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 Library

    The 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 Library

    The 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 Library

    The 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

    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 Library

    The 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 Library

    The 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 Library

    The 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

    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 Library

    The 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 Library

    The 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 Library

    The 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

    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 Library

    The 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 Library

    The 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 Library

    The 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

    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 Library

    The 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 Library

    The 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 Library

    The 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

    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™ API documentation or view them in a browser