Request PIN

Use this method to start the authentication process. Submit a mobile number in international format (MSISDN) to make the system send a verification SMS with a PIN code to that user on your behalf. You will later be able to verify the user's identity with that PIN code.

If you send multiple requests for the same number, only the last PIN code generated will be valid, i.e. only the last SMS will allow the user to complete the authentication process.

Endpoint

https://api.gateway360.com/api/2fa/request

Request

api_key Your API Key.
msisdn Mobile number to verify in international format (must include country calling code).
sender Sender field for the SMS (max 15 numeric or 11 alphanumeric characters).
hlr_lookup Perform a HLR lookup to guarantee the validity of the MSISDN provided. Use this parameter to avoid the SMS being sent to invalid numbers. If set to 1 the operation will fail if the HLR query fails. Possible values 1 or 0. Defaults to 1.
sms_text Text for the SMS. If specified, it must contain the placeholder string {PIN} exactly once, to be replaced by the generated PIN code. Max SMS length is 160 characters minus the length of the PIN code.
report_url Callback url to receive the SMS delivery report (DLR). For details on the format of this dlr, see Get Reports (Callback). Note that this delivery report only contains the status of the SMS sent to the user, not the actual verification process.
pin_params
typeType of characters for the generated PIN code. Allowed values are numeric, alpha and alphanumeric. Letters will always be uppercase. Defaults to numeric.
lengthLength of the generated PIN code. Between 4 and 16. Defaults to 6.
expires_inSeconds until the PIN code expires and is rendered invalid. 0 for unlimited validity (not recommended). Defaults to 3600 (1 hour).
max_triesMaximum number of failed confirmation attempts before the code is rendered invalid permanently. 0 for unlimited retries (not recommended). Defaults to 3.
Mandatory
Optional 
{
    "api_key":"399d2b438a53ebed3db8a7d52107f846",
    "msisdn":"34666666111",
    "sender":"GOOD PIZZA",
    "hlr_lookup":1
}
curl -X POST \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json' \
 -d '{
    "api_key":"399d2b438a53ebed3db8a7d52107f846",
    "msisdn":"34666666111",
    "sender":"GOOD PIZZA",
    "hlr_lookup":1
}' https://api.gateway360.com/api/2fa/request
$request = '{
    "api_key":"399d2b438a53ebed3db8a7d52107f846",
    "msisdn":"34666666111",
    "sender":"GOOD PIZZA",
    "hlr_lookup":1
}';
        	
$headers = array('Content-Type: application/json');        	

$ch = curl_init('https://api.gateway360.com/api/2fa/request');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);

$result = curl_exec($ch);
 
if (curl_errno($ch) != 0 ){
	die("curl error: ".curl_errno($ch));
}        	

/** Imports */
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.HttpClientBuilder;
/** End imports */


HttpClient httpClient = HttpClientBuilder.create().build();
HttpPost request = new HttpPost("https://api.gateway360.com/api/2fa/request");

StringEntity params = new StringEntity(
"{" +
"    \"api_key\":\"399d2b438a53ebed3db8a7d52107f846\"," +
"    \"msisdn\":\"34666666111\"," +
"    \"sender\":\"GOOD PIZZA\"," +
"    \"hlr_lookup\":1" +
"}");

request.addHeader("content-type", "application/json");
request.addHeader("Accept","application/json");
request.setEntity(params);
HttpResponse response = httpClient.execute(request);
.asString(); 
require 'uri'
require 'net/http'

url = URI("https://api.gateway360.com/api/2fa/request")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'

request.body = '{
    "api_key":"399d2b438a53ebed3db8a7d52107f846",
    "msisdn":"34666666111",
    "sender":"GOOD PIZZA",
    "hlr_lookup":1
}'

response = http.request(request)
puts response.read_body
conn = http.client.HTTPSConnection("api.gateway360.com")

payload = '{
    "api_key":"399d2b438a53ebed3db8a7d52107f846",
    "msisdn":"34666666111",
    "sender":"GOOD PIZZA",
    "hlr_lookup":1
}'

headers = {
    'content-type': "application/json",
    'accept': "application/json"
    }

conn.request("POST", "/api/3.0/2fa/request", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
var client = new RestClient("https://api.gateway360.com/api/2fa/request");

var request = new RestRequest(Method.POST);
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", '{
    "api_key":"399d2b438a53ebed3db8a7d52107f846",
    "msisdn":"34666666111",
    "sender":"GOOD PIZZA",
    "hlr_lookup":1
}', ParameterType.RequestBody);

IRestResponse response = client.Execute(request);
Private Sub Command1_Click()
Dim objHTTP As Object
Dim Json As String
Dim result As String


    Json = fJSON
    Set objHTTP = CreateObject("MSXML2.ServerXMLHTTP")
    URl = "https://api.gateway360.com/api/2fa/request"
    objHTTP.Open "POST", URl, False
    objHTTP.setRequestHeader "Content-type", "application/json"
    objHTTP.send (Json)
    result = objHTTP.responseText
   Set objHTTP = Nothing
End Sub

Private Function fJSON() As String
    fJSON = "{"
    fJSON = fJSON & """api_key"":""399d2b438a53ebed3db8a7d52107f846"","
    fJSON = fJSON & """msisdn"":""34666666667"","
    fJSON = fJSON & """sender"":""GOOD PIZZA"","
    fJSON = fJSON & """hlr_lookup"":1"
    fJSON = fJSON & "}"
End Function

Response

status Final status of request - either "ok" or "error"
error_id In case of status being "error", this will indicate the error code.
error_msg In case of status being "error", this param will contain additional information. Should only be used for debugging.
200 OK 
{
    "status":"ok"
}
Successful authentication request. SMS sent to specified number.
200 OK 
{
    "status":"error",
    "error_id":"INVALID_NUMBER",
    "error_msg":"HLR query returned error."
}
We didn't continue processing your request because the MSISDN wasn't valid.
401 Unauthorized 
{
    "status":"error",
    "error_id":"UNAUTHORIZED",
    "error_msg":"Your API key may be invalid or your IP is blocked."
}
We didn't continue processing your request because your API Key wasn't valid.
400 Bad Request 
{
    "status":"error",
    "error_id":"JSON_PARSE_ERROR",
    "error_msg":"Your JSON was formatted incorrectly."
}
We couldn't process your request.

Errors

Error ID Explanation
INVALID_CONTENT_TYPE The content type must be: Content-Type: application/json
JSON_PARSE_ERROR Your JSON was formatted incorrectly or was considered otherwise improper or incomplete. Check it here.
MISSING_PARAMS Your request is incomplete and missing some mandatory parameters.
BAD_PARAMS One or more of your parameters has incorrect format or value.
UNAUTHORIZED Your API key may be invalid, double-check that your API key was input correctly or see if the IP is blocked in your account API settings.
INVALID_HLR_LOOKUP_PARAM Invalid hlr_lookup param provided.
INVALID_PIN_PARAMS Invalid pin configuration parameters provided.
INVALID_SMS_TEXT The SMS text was deemed invalid. Either too long or mising the {PIN} placeholder.
INVALID_SENDER The sender address (from parameter) was not allowed for this message.
INVALID_NUMBER HLR query returned error. The number must be in MSISDN format. Check format here.
NOT_ENOUGH_BALANCE Your account has no funds to process this request, add credits to your account and try again.
UNKNOWN_ERROR The system threw an unknown error.