Send and verify PIN

Send 2FA PINs over SMS or Voice channels.

Once you’ve created a 2FA application and message template, you are ready to start using the 2FA service and send PIN codes to end users. You can send PINs as SMS or Voice message.

Note

After sending out the PIN message, use the Verify PIN method to verify the PIN returned by the recipient. Learn all about the 2FA process in the 2FA introduction.

On this page you will learn how to:

Resource

https://api.infobip.com/2fa/1/pin

Resource description

Parameter Type Description
to * string Phone number to which the 2FA message will be sent. Example: 41793026727.
*applicationId** string 2FA application ID.
messageId * string Message template ID that will be sent to a phone number.
from string Sender ID in numeric or alphanumeric format. If this parameter is not set, it will be automatically filled from the created message parameter sender.
ncNeeded boolean Indicates if Number Lookup is needed before sending the 2FA message. If the parameter value is true, Number Lookup will be requested before sending the SMS. If the value is false, the SMS will be sent without requesting Number Lookup
Default value: true.
ncStatus string Status of sent Number Lookup. Number Lookup status can have one of the following values: NC_DESTINATION_UNKNOWN, NC_DESTINATION_REACHABLE, NC_DESTINATION_NOT_REACHABLE, NC_NOT_CONFIGURED. If you get theNC_NOT_CONFIGURED status, you should contact your Account Manager. SMS will not be sent only if Number Lookup status is NC_NOT_REACHABLE.
smsStatus string Sent SMS status. Can have one of the following values: MESSAGE_SENT, MESSAGE_NOT_SENT.
pinId string Sent PIN code ID.
callStatus string Call status. View possible call status codes.

Call status codes

Value Description
BAD_REQUEST Provided request does not meet the required conditions.
PROCESSING Request is currently being processed.
PROCESSED Request has been successfully processed and answered by a human.
ANSWERED_MACHINE Request has been successfully processed and answered by a machine.
ERROR System error occurred during processing.
ERROR_NOT_ENOUGH_CREDITS Not enough credits in the account balance to pay for the call.
ERROR_NETWORK_NOT_AVAILABLE We could not find the network for the given destination address.
ERROR_ROUTE_NOT_AVAILABLE Route for TTS call is not set up on account.
ERROR_USER_BUSY User was busy during the call attempt(s).
ERROR_NO_ANSWER User did not answer the call(s).
UNDEFINED Request is undefined.

Application configuration warning

When sending out PIN messages, one of the common HTTP response messages is 429 Too Many Requests. The source of this message is often a security feature put in place on the application level. If you get too many 429 messages, please review your Application settings.

Send PIN over SMS

This method allows you to generate and send a PIN code over SMS to the provided destination address.

POST https://api.infobip.com/2fa/1/pin

Request example

POST /2fa/1/pin?ncNeeded=true HTTP/1.1
Host: api.infobip.com
Authorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9
Content-Type: application/json

{
  "applicationId": "HJ675435E3A6EA43432G5F37A635KJ8B",
  "messageId": "0130269F44AFD07AEBC2FEFEB30398A0",
  "from": "InfoSMS",
  "to": "41793026727"
}
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.infobip.com/2fa/1/pin?ncNeeded=true",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n    \"applicationId\": \"HJ675435E3A6EA43432G5F37A635KJ8B\",\n    \"messageId\": \"0130269F44AFD07AEBC2FEFEB30398A0\",\n    \"from\": \"InfoSMS\",\n    \"to\": \"41793026727\"\n}",
  CURLOPT_HTTPHEADER => array(
    "Authorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9",
    "Content-Type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Response:

{
  "pinId": "9C817C6F8AF3D48F9FE553282AFA2B67",
  "to": "41793026727",
  "ncStatus": "NC_DESTINATION_REACHABLE",
  "smsStatus": "MESSAGE_SENT"
}

Resend PIN over SMS

This method allows you to resend the already created PIN over SMS.

POST https://api.infobip.com/2fa/1/pin/{pinId}/resend

Request example

POST /2fa/1/pin/9C817C6F8AF3D48F9FE553282AFA2B67/resend HTTP/1.1
Host: api.infobip.com
Authorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9
Content-Type: application/json
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.infobip.com/2fa/1/pin/9C817C6F8AF3D48F9FE553282AFA2B67/resend",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => array(
    "Authorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9",
    "Content-Type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Response:

  • JSON
{
  "to": "41793026727",
  "ncStatus": "NC_DESTINATION_REACHABLE",
  "smsStatus": "MESSAGE_SENT",
  "pinId": "9C817C6F8AF3D48F9FE553282AFA2B67"
}

Send PIN over Voice

This method allows you to generate and send a PIN code over Voice to the provided destination address.

POST https://api.infobip.com/2fa/1/pin/voice

Request example

POST /2fa/1/pin/voice HTTP/1.1
Host: api.infobip.com
Authorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9
Content-Type: application/json
Accept: application/json

{
  "applicationId": "HJ675435E3A6EA43432G5F37A635KJ8B",
  "messageId": "0130269F44AFD07AEBC2FEFEB30398A0",
  "from": "41793012321",
  "to": "41793026727"
}
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.infobip.com/2fa/1/pin/voice",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n    \"applicationId\": \"HJ675435E3A6EA43432G5F37A635KJ8B\",\n    \"messageId\": \"0130269F44AFD07AEBC2FEFEB30398A0\",\n    \"from\": \"41793012321\",\n    \"to\": \"41793026727\"\n}",
  CURLOPT_HTTPHEADER => array(
    "Accept: application/json",
    "Authorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9",
    "Content-Type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Response:

{
  "pinId": "9C817C6F8AF3D48F9FE553282AFA2B67",
  "to": "41793026727",
  "callStatus": "PENDING_ACCEPTED"
}

Resend PIN over Voice

This method allows you to resend the already created PIN over Voice.

POST https://api.infobip.com/2fa/1/pin/{pinId}/resend/voice

Request example

POST /2fa/1/pin/9C817C6F8AF3D48F9FE553282AFA2B67/resend/voice HTTP/1.1
Host: api.infobip.com
Authorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9
Content-Type: application/json
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.infobip.com/2fa/1/pin/9C817C6F8AF3D48F9FE553282AFA2B67/resend/voice",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => array(
    "Authorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9",
    "Content-Type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Response:

{
  "to": "41793026727",
  "pinId": "9C817C6F8AF3D48F9FE553282AFA2B67",
  "callStatus": "PROCESSED"
}

Verify PIN

This method allows you to verify the received PIN.

POST https://api.infobip.com/2fa/1/pin/{pinId}/verify

Request example

POST /2fa/1/pin/9C817C6F8AF3D48F9FE553282AFA2B67/verify HTTP/1.1
Host: api.infobip.com
Authorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9
Content-Type: application/json

{
  "pin":"1598"
}
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.infobip.com/2fa/1/pin/9C817C6F8AF3D48F9FE553282AFA2B67/verify",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n    \"pin\": \"1598\"\n}",
  CURLOPT_HTTPHEADER => array(
    "Authorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9",
    "Content-Type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Response:

{
  "pinId": "9C817C6F8AF3D48F9FE553282AFA2B67",
  "msisdn": "41793026727",
  "verified": true,
  "attemptsRemaining": 0
}

Response description

Parameter Type Description
pinId String Sent PIN code ID.
msisdn String Phone number (MSISDN) to which the 2FA message was sent.
verified Boolean Indicates if the phone number (MSISDN) was successfully verified.
attemptsRemaining Integer Number of remaining PIN attempts.
pinError String Indicates if any error occurs during PIN verification.
PIN error can have one of the following values: WRONG_PIN, TTL_EXPIRED, NO_MORE_PIN_ATTEMPTS
Prev: Create API key for 2FA Next: Number verification history